Workspace Config Overlays

Workspace config lets one project change runtime behavior without changing every CompozyOS session on the machine. The loader starts from built-in defaults, applies global config, then applies the resolved workspace root overlay.

This keeps project behavior portable. Copy a repository with .compozy/config.toml, .compozy/agents/, and .compozy/skills/, register the copied path, and the project-level runtime context comes with it.

Load OrderCopy Anchor Link

The effective config for a resolved workspace is built in this order:

Workspace additional roots do not contribute config. They can contribute agents and skills, but only the primary root contributes config.toml and top-level mcp.json.

Create A Workspace OverlayCopy Anchor Link

Create the config file under the project root:

mkdir -p /Users/you/src/checkout-api/.compozy

# /Users/you/src/checkout-api/.compozy/config.toml
[defaults]
agent = "reviewer"
provider = "claude"

[permissions]
mode = "approve-reads"

[limits]
max_concurrent_agents = 12

[skills]
disabled_skills = ["public-cloud-deploy"]

[[mcp_servers]]
name = "repo-fs"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/src/checkout-api"]

Then register the workspace:

compozy workspace add /Users/you/src/checkout-api --name checkout-api

Sessions that target checkout-api now inherit the overlay:

compozy session new --workspace checkout-api

The command uses reviewer as the default agent unless you pass --agent.

Merge RulesCopy Anchor Link

TOML overlays are field-aware. A field changes only when the overlay provides that field.

This example keeps the global skill scan interval while changing only skill enablement:

# ~/.compozy/config.toml
[skills]
poll_interval = "5m"

# <workspace>/.compozy/config.toml
[skills]
enabled = false

The final config has skills.enabled = false, while the inherited skills.poll_interval = "5m" remains in effect.

MCP SidecarsCopy Anchor Link

Top-level mcp.json files are optional. They may use either mcpServers or mcp_servers.

{
  "mcpServers": {
    "repo-db": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "postgres://localhost/checkout"
      }
    }
  }
}

When both key styles appear in the same mcp.json, mcp_servers replaces same-name entries from mcpServers. When a TOML MCP server and an mcp.json server have the same name, the JSON sidecar replaces the whole server object at that scope.

Across the session start path, MCP servers are then resolved in this order:

1. top-level config MCP servers
2. provider MCP servers
3. agent MCP servers
4. active skill MCP servers

Workspace Agents And SkillsCopy Anchor Link

Config overlays do not define agents or skills directly. They change the runtime defaults around the agents and skills discovered by the resolver.

Workspace registration has one extra override: default_agent. When it is set on the workspace row, the resolver applies it after loading config by setting defaults.agent for the resolved snapshot. The Web Start session dialog preselects this registered default for the active workspace, or for the owning workspace when launched from a worktree. An agent-specific Start session action keeps its explicitly chosen agent.

compozy workspace edit checkout-api --default-agent reviewer

Set it to an empty value to clear it:

compozy workspace edit checkout-api --default-agent ""

Concrete Overlay WalkthroughCopy Anchor Link

Global config:

# ~/.compozy/config.toml
[defaults]
agent = "general"
provider = "codex"

[permissions]
mode = "approve-all"

[limits]
max_concurrent_agents = 20

[skills]
disabled_skills = ["legacy-notes"]

Workspace config:

# <workspace>/.compozy/config.toml
[defaults]
agent = "reviewer"

[permissions]
mode = "approve-reads"

[skills]
disabled_skills = ["deploy-production", "legacy-notes"]

Effective result for the workspace:

defaults.model and defaults.reasoning_effort follow defaults.provider: a layer that sets a different defaults.provider drops the model and reasoning inherited from lower layers, so a model chosen for one provider never reaches another. A layer that repeats the same provider, or sets only defaults.model, keeps refining the inherited choice.

.env And COMPOZY_HOMECopy Anchor Link

If a workspace root contains .env, CompozyOS loads it before resolving the CompozyOS home layout for that config load. That means a workspace can set COMPOZY_HOME for sessions that resolve that workspace:

COMPOZY_HOME=/Users/you/.compozy-checkout

Use this carefully. It changes the global config, agents, skills, sessions, logs, socket, and database locations for that resolved workspace config load. Most projects should prefer <workspace>/.compozy/config.toml for project-specific behavior and keep COMPOZY_HOME stable.

Failure BehaviorCopy Anchor Link

Unknown keys in a workspace .compozy/config.toml reject registration and resolution with HTTP/UDS 422 and code workspace_config_invalid. The error includes config_path, a sorted, deduplicated unknown_keys array, and an actionable error message. The CLI preserves these fields with -o json and exits with code 78; Add project displays the message without clearing the form. The workspace list remains available because it reads registrations without resolving configuration.

Legacy CLI configuration is unsupported. If the error names legacy keys such as defaults.ide or tasks.run.task_runtime_rules, remove those keys, or rename or remove the legacy file before trying again. CompozyOS does not translate these settings or modify the rejected file. Other configuration decode errors and server failures retain their existing behavior.

Related PagesCopy Anchor Link

• Workspace Resolver explains when config loading happens.
• Multi-Root Workspaces explains why additional roots do not add config overlays.
• Agent Definitions documents agent-local MCP sidecars.
• Skills Overview documents skill-local MCP sidecars and disabled skill behavior.