Install

Buffaly install layout

Understand the authoritative install-root layout for copy-only Buffaly deployments, including which folders are deployable and which folders must preserve environment-owned configuration and runtime data.

Install root

Every deployed environment has one authoritative install root. All app, content, module, config, and data paths are derived from that root. Do not keep a second active root for the same environment; stale roots cause web, worker, session, and module resolution to disagree.

Example staging root: C:\inetpub\wwwroot\staging.buffaly.local3

Copy-only deployment means deployable files can be rebuilt and copied into place without overwriting environment-owned configuration, authentication, session history, or user/runtime data.

Top-level layout

Area	Purpose	Examples
`app`	Replaceable web and worker app payloads.	`agent-web`, `agent-worker`, `sessions-web`, `voice-gateway`
`config`	Environment-owned role-specific configuration.	`config\agent-web\appsettings.json`
`config-template`	Deployable templates for new or repaired config.	`appsettings.template.json`
`content`	Installed projects, skills, prompts, and ontology content.	`content\projects\<ProjectName>\Project.pts`
`data`	Runtime and user-owned data.	`sessions`, `codex-auth`, `temp`
`lib`	Shared deployable libraries and installed web modules.	`lib\web-modules\WebModules.json`

Ownership rules

Deployment safety depends on knowing which folders are replaceable and which folders are environment state.

Deployableapp, content, lib, and config-template are package/deploy owned, with provisioning rules for content and modules.

Preservedconfig and data are environment/operator or runtime/user state. Do not overwrite them during copy deployment.

The short rule is: app, content, lib, and config-template are deployable; config and data are preserved.

Configuration

Role-specific configuration lives outside app binaries under config\agent-web, config\agent-worker, config\sessions-web, and config\voice-gateway. Copying a new app folder must not erase connection strings, provider settings, worker settings, or auth settings.

Runtime data

data\sessions stores session files or artifacts when file-backed artifacts are used. data\codex-auth stores Buffaly-managed Codex authorization profiles when configured; preserve it during rebuilds.

Database-backed feature settings

Some runtime settings live in the database Features table, including OpenAI, Codex Auth, Codex Backend, Runtime, and Worker feature rows. Copy deployment must not reseed feature rows with empty/default payloads over an existing environment database.

Web modules, static files, and JsonWs files

Installed web modules are single-owned under <installRoot>\lib\web-modules, with the manifest at lib\web-modules\WebModules.json. Each module owns one subdirectory containing its assembly, deps file, install receipt, generated JsonWs files, static web files, and skills.

Static filesCopied to app\agent-web\wwwroot\web-modules\<ModuleName> and served as /web-modules/<ModuleName>/....

JsonWs filesGenerated manifests and stubs are copied directly to app\agent-web\wwwroot\JsonWs because the loader discovers services from that shared folder.

Do not use duplicate module locations such as app\agent-web\lib\web-modules or project-local module DLL copies. Duplicate DLLs can shadow the authoritative module copy and cause stale types to load.

ProtoScript projects, skills, and workers

The deployed project lives under content\projects\<ProjectName>, with authoritative project file content\projects\<ProjectName>\Project.pts.
Worker configuration points to that project file through WorkerFeature.ProjectFilePath; code should derive the project root from that setting.
Installed module skills belong under content\projects\<ProjectName>\Skills\<SkillName> and should use portable named web-module references.
Per-session workers run from app\agent-worker. Update the worker app payload when runtime assemblies it loads change, and recycle affected workers through Worker Manager when possible.

Copy-only deployment flow

Build source and create a complete package.
Preserve target config and data.
Copy package app, content, lib, and config-template into the install root.
Remove obsolete app\agent-web\lib\web-modules if it exists.
Prevent web-module DLLs from being copied into project lib.
Run provisioning registration for web modules and skills.
Recycle affected workers when worker-loaded binaries changed.
Validate runtime behavior.

Post-deploy validation

There is one active install root.
config and data survived the copy.
WorkerFeature.ProjectFilePath points under content\projects.
RuntimeFeature.InstallRootPath points at the install root.
lib\web-modules\WebModules.json exists.
No obsolete app\agent-web\lib\web-modules tree exists.
No known web-module DLLs exist in project lib.
ProtoScript project compiles and key web modules load without ambiguous assembly resolution.

Install Buffaly Building ProtoScript services Web modules and UI Secrets handling Troubleshooting and recovery Build/run/deploy profiles