File Locations

CompozyOS uses one user home directory plus optional personal-profile and workspace-local .compozy/ directories. The user home defaults to ~/.compozy and can be changed with COMPOZY_HOME.

Quick ReferenceCopy Anchor Link

Profile resource discovery is most-specific first: workspace named profile, workspace base, personal profile, then user. A workspace named profile activates only when its directory name matches the active profile; unmatched directories stay dormant.

Global HomeCopy Anchor Link

EnsureHomeLayout creates the root, agents, skills, loops, profiles, the default profile directory, sessions, logs, and gateway directories. Individual files are created by the features that own them.

Profile FilesCopy Anchor Link

Profile config.toml and mcp.json files whose directory name is absent from the profile catalog are ignored and reported as config_profile_layer_orphaned. Creating the named profile adopts them.

What a profile does and does not own is explained in Profiles; the repository-side folders are how a division of contexts travels with a checkout.

Global Runtime FilesCopy Anchor Link

Provider Home FilesCopy Anchor Link

When a provider sets home_policy = "isolated", CompozyOS creates a private provider home under $COMPOZY_HOME/providers/<provider> with 0700 permissions. The launch environment points HOME, PROVIDER_HOME, XDG directories, and known provider-specific variables such as CLAUDE_CONFIG_DIR, CODEX_HOME, and OPENCODE_CONFIG_DIR at that directory. CompozyOS never copies credentials from the operator home into an isolated provider home.

The default home_policy = "operator" does not create this directory and lets native ACP CLIs use their existing login/session state.

Session FilesCopy Anchor Link

Each session owns a directory under $COMPOZY_HOME/sessions/<session-id>/.

~/.compozy/sessions/<session-id>/
  events.db
  meta.json

The append-only events.db is the source of truth for the session record. Read it through compozy session events and compozy session history rather than opening the file directly.

Agent FilesCopy Anchor Link

Agent discovery order is workspace root, additional roots in registered order, then global home. First name wins.

Skill FilesCopy Anchor Link

Two more families of skill directories are scanned when configuration turns them on. Folder conventions from other agent tools come from skills.sources, and free-form directories come from skills.custom_sources:

Preset roots are fixed paths CompozyOS knows; custom roots are the exact directories you list, with no .compozy/skills suffix appended. A custom source takes its display name from the directory's own name. Exposure links are the only files CompozyOS writes outside its own folders, and it writes them only when you ask.

Skill filesystem precedence is bundled, marketplace, user, personal profile, additional root, workspace, workspace named profile, then the winning agent's skills/ directory as a final overlay. Enabled extensions can also register runtime-owned skills into the live registry. Those overlays do not come from a filesystem path, so they are documented in Skills Overview rather than in this file-path table.

Every <group>/.../ segment above is optional and organizational. CompozyOS discovers skill leaves at any depth, and the name in each leaf's frontmatter remains its resolver identity.

Workspace FilesCopy Anchor Link

my-project/
  .env
  .agents/
    skills/                 # scanned when skills.sources includes "agents"
  .claude/
    skills/                 # scanned when skills.sources includes "claude"
  .compozy/
    workspace.toml
    config.toml
    mcp.json
    agents/
    skills/

CompozyOS only loads the .compozy/config.toml for the resolved primary workspace root. Additional roots are resource discovery roots for agents and skills; they do not contribute config overlays.

Extension FilesCopy Anchor Link

Extension registry records are stored in the global database, not in a separate user-authored config file.

Path OverridesCopy Anchor Link

Special CasesCopy Anchor Link

Related PagesCopy Anchor Link

• config.toml documents the schema for global and workspace config files.
• mcp.json documents JSON sidecars.
• Workspace Resolver explains how CompozyOS finds the primary workspace root.