Configuration Overview
Decide which CompozyOS file, overlay, or environment variable should change when you need to configure one machine, one workspace, one agent, or one skill.
Configuration is where CompozyOS stops being generic and starts matching one machine, one workspace, one team default, or one agent role. The key to using this section well is choosing the right surface for the change you actually want.
Start with the decision table
| If you want to change... | Primary surface | Reach for this when... |
|---|---|---|
| User defaults | $COMPOZY_HOME/config.toml | The daemon, default provider, permissions mode, HTTP bind address, automation defaults, or marketplace trust should change for every workspace on one machine. |
| One workspace | <workspace>/.compozy/config.toml | A repository needs different defaults, limits, or permissions than the rest of the machine. |
| One operator profile | $COMPOZY_HOME/profiles/<name>/config.toml | One profile needs different persona, provider, permission, hook, memory, or tool defaults without changing another profile. |
| One profile inside one workspace | <workspace>/.compozy/profiles/<name>/config.toml | A repository supplies a read-only named profile layer that activates only when the selected profile has the same name. |
| One agent | AGENT.md | A specific agent needs a different prompt, provider, permission mode, or MCP attachment. |
| One agent's advertised capabilities | capability catalog next to AGENT.md | Other peers need outcome-oriented discovery metadata about what that agent can do. |
| One skill | SKILL.md | You are defining reusable instructions, optional MCP metadata, or skill-owned hooks. |
| MCP server configuration | mcp.json | MCP declarations are easier to manage as JSON sidecars than inline frontmatter. |
| Encrypted CompozyOS-managed secrets | Vault | Store write-only vault:<namespace>/... values and inspect redacted metadata through CLI, HTTP, UDS, web, or session-scoped views. |
| Provider authentication | provider settings, native CLI login, credential_slots, or Vault | Let native ACP providers use their own CLI login state, and bind API-key providers to env: or encrypted vault:providers/<provider>/<slot> refs. |
| Remote gateway access | Gateway section + [gateway] keys | Expose selected private or public surfaces while the daemon keeps tier listeners on loopback. |
| Filesystem locations and precedence | file-locations reference | You need to know where CompozyOS looks for agents, skills, sessions, memory, or overlays. |
Read in this order
- config.toml
- Config Lifecycle Matrix
- Vault
- File Locations
- AGENT.md
- Agent Capabilities
- SKILL.md
- mcp.json
- Environment Variables
That order mirrors how operators usually troubleshoot CompozyOS: user defaults first, then
lifecycle, secret storage, path resolution, file formats, and agent sidecars. Remote access is
configured through explicit gateway transitions rather than config keys — the
Gateway section owns that flow, and the
[gateway] reference owns its bounded tunables.
Profile Layer Precedence
A profile is a named working context that owns its own layer on both the user and the workspace side. CompozyOS merges four operator-authored layers. Later rows win over earlier rows:
| Order | Layer | File | Writable through the CLI |
|---|---|---|---|
| 1 | User | $COMPOZY_HOME/config.toml | --scope user |
| 2 | Personal profile | $COMPOZY_HOME/profiles/<name>/config.toml | --scope profile |
| 3 | Workspace | <workspace>/.compozy/config.toml | --scope workspace |
| 4 | Workspace named profile | <workspace>/.compozy/profiles/<name>/config.toml | No; repository-authored |
The workspace named profile layer activates only when <name> matches the active profile. A folder
whose name is not in the profile catalog stays dormant and reports config_profile_layer_orphaned;
creating that profile activates the layer without rewriting it.
When --scope is omitted, default writes the user file and every other active profile writes its
personal profile file. An explicit --scope user|profile|workspace selects another writable target.
If a more specific layer already wins, the command returns ok_overridden with the winning layer:
the value was saved, but it is not the current effective value.
Profile files cannot change machine-only roots: http, daemon, log, database, gateway,
shell, marketplace, observability, network, or sandboxes. They also cannot change
window_manager.global_shortcuts, because the operating system has one shortcut registry. These
writes fail with profile_config_key_denied and direct the operator to --scope user.
For a worked example of writing to a profile layer, including the overridden case, see Create your first profile.
CLI Inspection and Mutation
Use compozy config path before editing to confirm the selected user, profile, or workspace overlay. Prefer
compozy config set <path> <value> for supported scalar and list settings because it writes through the
same validated persistence path as the settings API. config.toml is desired state; the daemon's
active generation is runtime truth. Every settings write, boot reconcile, and explicit reload is
recorded in config_apply_records.
Use compozy config reload after hand edits to reconcile desired state with the active generation. The
same operation is available through POST /api/settings/reload; agents can inspect history through
compozy config apply-history or GET /api/settings/apply.
Inspection commands are redacted by default. compozy config show, compozy config list, and
compozy config get <path> replace MCP and environment map values with [redacted] so copied
diagnostics do not leak runtime credentials.
Apply History and Recovery
compozy config apply-history lists each apply attempt with desired and active hashes, generation,
actor, lifecycle, status, diagnostics, and next action. Use --status blocked to find changes that
were written to desired state but could not become runtime truth without a daemon restart. Use
--status failed to find validation or subsystem reload failures that should be fixed and retried
with compozy config reload.
Status values are intentionally small:
| Status | Meaning |
|---|---|
pending_apply | The daemon has created an audit row and is still trying to reconcile runtime. |
applied | Desired state became the daemon active generation. |
blocked | Desired state was written, but runtime truth needs a restart or new session. |
failed | Validation or a subsystem reload failed; diagnostics describe the retry path. |
next_action tells operators what to do next: none, restart-daemon, new-session, or retry.
CompozyOS does not roll back config.toml after a reload failure; the apply record is the audit surface
that explains why the active generation did or did not advance.
Gateway security
What each gateway switch exposes and to whom, who can see your traffic, what CompozyOS guarantees when things fail, and what you still have to do yourself.
Overview
Decide which CompozyOS file, overlay, or environment variable should change when you need to configure one machine, one workspace, one agent, or one skill.