Workspaces
How Compozy resolves workspace roots, layers config overlays, and attaches additional roots for monorepos and cross-project agent sharing.
A workspace is a registered project root. Compozy uses it as the source of truth for workspace-scoped agents, skills, memory, and config overlays. Sessions inherit the workspace context, and resolution is deterministic — the registered root wins over global defaults.
Use this section when the same machine runs more than one project, when an agent needs project-local instructions, or when a monorepo needs extra directories attached without copying files into the primary root. The important rule is that Compozy treats the registered workspace as an identity, not just as the current shell directory. That identity is what sessions, memories, overlays, and additional roots attach to.
That identity is also a boundary. An agent session works inside the workspace it started in, and asking for another one is a decision the runtime makes from the session's permission mode — not a setting of its own. You are not bound by it: your own commands, reads, and deep links still reach every registered workspace. See Isolation and cross-workspace access.
In this section
Workspace resolver
Use this page for how Compozy registers workspace roots and resolves an active workspace at session start.
Workspace config overlays
Use this page for how `<workspace>/.compozy/config.toml` and `mcp.json` layer over global config.
Multi-root workspaces
Use this page when one session must see additional directories for monorepos or shared agent libraries.