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... |
|---|---|---|
| Machine-wide defaults | ~/.compozy/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 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: global 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.
CLI Inspection and Mutation
Use compozy config path before editing to confirm the selected global 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.