config.toml

config.toml is the main CompozyOS runtime desired-state file. CompozyOS loads the built-in defaults, then overlays global and workspace files when they exist. The daemon only treats a change as runtime truth after ConfigApplyService advances the active generation and writes a config_apply_records audit row.

Unknown TOML keys are errors. Sandbox profiles are implemented under [sandboxes.<name>]. Use only [sandboxes.<name>] for session execution boundaries.

Quick Reference

Load And Merge Order

TOML [[mcp_servers]] entries merge fields by name: non-empty command, non-empty args, and new env keys overlay the existing server. JSON sidecars replace same-name servers as whole objects.

Daemon boot uses the home config for boot-time daemon settings. The general config loader applies global and workspace MCP sidecars for session and runtime resolution.

Complete Annotated Example

# ~/.compozy/config.toml

[daemon]
# Path to the Unix domain socket used by CompozyOS CLI commands.
socket = "~/.compozy/daemon.sock"
# Emit daemon process-memory snapshots every five minutes. Set to "0s" to disable.
memory_report_interval = "5m"
# Escalate a task-bound session after three consecutive failed subprocess health checks.
# Set to 0 to keep status and doctor evidence without changing task-run state.
subprocess_health_escalation_threshold = 3

[daemon.reload_timeouts]
# Provider runtime reload budget. Valid range: 1s to 60s.
providers = "5s"
# MCP runtime reload budget. Valid range: 1s to 60s.
mcp = "10s"
# Bridge runtime reload budget. Valid range: 1s to 300s.
bridges = "30s"

[http]
# HTTP/SSE API bind address.
host = "localhost"
port = 2123

[app]
# Check for desktop app and app-owned runtime updates.
update_check = true
# Check cadence. Valid range: 15m to 168h.
update_check_interval = "6h"

[attention]
toasts = true
sound = true
system = false
muted_workspaces = []

[shell.sessions]
# Session ordering: "last_activity" or "attention".
sort = "last_activity"
# Session breadth: "recent", "all", or "all-workspaces".
scope = "recent"

[window_manager]
new_window_policy = "floating"
small_viewport_policy = "stack"
focus_policy = "click_directional"
focus_wrap = false
focus_follows_pointer = false
raise_on_focus = true
drag_away_policy = "window"
group_move_modifier = "alt"
swap_modifier = "shift"
history_limit = 50
# Retain at most this many prior routes per window when a new route is pushed.
nav_stack_limit = 50
# Retain at most this many newest closed-window entries for reopen.
closed_entry_limit = 20
desktop_transition = "slide"

[window_manager.gaps]
inner = 8
top = 8
right = 10
bottom = 8
left = 10

[window_manager.snap]
edge_band = 32
corner_reach = 150
exit_slack = 16
repeat_ratios = [0.5, 0.666667, 0.333333]

[window_manager.bindings]
top_center = "zoom"
bottom_center = "reserved"

[defaults]
# Agent name used when a command or API request does not specify one.
agent = "general"
# Provider used by AGENT.md files that omit provider.
provider = "claude"
# Sandbox profile used when a workspace does not set sandbox_ref.
sandbox = "local"

[roles.coordinator]
# Coordinator is a virtual builtin when agent is omitted. It is disabled by default.
enabled = false
ttl = "2h"
max_children = 5
max_active_sessions_per_workspace = 5

[roles.dream]
# Route dreaming work to a custom authored curator instead of the builtin dreaming-curator.
enabled = true
agent = "memory-curator"

[roles.checkpoint_summary]
# Empty agent selects the builtin dreaming-curator.
enabled = true

[roles.memory_extractor]
# Empty agent inherits the invoking context's agent at runtime.
enabled = true

[roles.auto_title]
# Use a small model for the bounded automatic-title pass.
enabled = true
provider = "claude"
model = "claude-haiku-4-5-20251001"
reasoning_effort = "low"

[[roles.auto_title.fallback_chain]]
# Fallback routes are tried in declaration order before a session is accepted.
provider = "codex"
model = "gpt-5.4-mini"
reasoning_effort = "low"

[roles.memory_controller]
# This in-process role has no agent field.
enabled = true
provider = "pi"
model = "anthropic/claude-haiku-4"
timeout = "250ms"
top_k = 5
prompt_version = "v1"
max_tokens_out = 256

[limits]
# Positive daemon-wide agent concurrency bound.
max_concurrent_agents = 20

[session.limits]
# 0 means no configured wall-clock timeout. Use Go durations such as "30m" or "2h".
timeout = "0s"

[session.supervision]
# Short heartbeats update durable liveness only. They are not persisted as session events.
activity_heartbeat_interval = "30s"
# 0 disables periodic progress events.
progress_notify_interval = "10m"
# 0 disables inactivity warnings.
inactivity_warning_after = "15m"
# 0 disables inactivity timeout.
inactivity_timeout = "30m"
# Grace period after cooperative prompt cancel before CompozyOS stops the session as timeout.
timeout_cancel_grace = "30s"

[session.compaction]
# Disable all pressure-triggered compaction work when false.
enabled = true
# Context-used/context-size ratio that admits compaction. 0 also disables admission.
pressure_threshold = 0.85
# Maximum failed or successful compaction starts admitted for one triggering turn.
max_attempts_per_turn = 1
# Delay before a failed session compaction may be attempted again.
failure_cooldown = "10m"

[agents.soul]
# Disabling pauses prompt injection but keeps inspect/validate/write/delete/history/rollback available.
enabled = true
# Hard cap for SOUL.md body bytes after normalization.
max_body_bytes = 32768
# Compact /agent/context projection budget. Must be <= max_body_bytes.
context_projection_bytes = 2048

[agents.heartbeat]
# Disabling pauses wake decisions but keeps managed authoring available for repair.
enabled = true
# Bounded HEARTBEAT.md body size (snapshot uses normalized body).
max_body_bytes = 32768
# Compact projection budget for status surfaces.
context_projection_bytes = 4096
# Hard floor for authored preferences.min_interval. Files below this are clamped.
min_interval = "5m"
# Default cadence baseline used when authored files omit min_interval.
default_interval = "30m"
# Cooldown between wakes for a single session.
wake_cooldown = "1m"
# Maximum scheduler-cycle wakes across the daemon.
max_wakes_per_cycle = 25
# When true, wake only sessions in active runtime state.
active_session_only = true
# When true, authored active_hours/quiet_windows preferences are honored within bounds.
allow_active_hours_preferences = true
# Retention for agent_heartbeat_wake_events audit rows. Minimum 1h.
wake_event_retention = "168h"
# Idle age before metadata-only presence is treated as stale for wake eligibility.
session_health_stale_after = "2m"
# Minimum interval between session.health.update.after hook fires for the same session.
session_health_hook_min_interval = "1m"

[permissions]
# Valid values: deny-all, approve-reads, approve-all.
mode = "approve-all"

[worktrees]
# Empty uses $COMPOZY_HOME/worktrees/<workspace>/<name> for new managed checkouts.
root = ""
# Lowercase, slash-terminated namespace for task per-run branches.
run_branch_namespace = "run/"
# Relative Git pathspecs for ignored, untracked files copied during managed creation.
copy_list = []
# Empty skips setup; a non-empty command runs inside the new checkout.
setup_command = ""
setup_timeout = "10m"
discovery_cache_ttl = "30s"

[tools]
# Disables registry dispatch and hosted MCP exposure when false.
enabled = true
# Enables CompozyOS-hosted local MCP projection for session-visible tools.
hosted_mcp_enabled = true
# Default result cap for tool descriptors that do not set a smaller cap.
default_max_result_bytes = 262144

[tools.artifacts]
# Global retained-artifact count ceiling across workspaces.
max_count = 200
# Global retained-artifact byte ceiling across workspaces.
max_bytes = 1073741824
# Maximum retained-artifact age.
max_age = "720h"

[tools.hosted_mcp]
# Non-secret launch correlation nonce lifetime before UDS peer binding.
bind_nonce_ttl_seconds = 30

[tools.clarify]
# Maximum wait for an operator answer before the caller receives the fallback sentinel.
timeout = "5m"

[tools.policy]
# Valid values: disabled, ask, enabled.
external_default = "disabled"
# Bounded wait for daemon-mediated approval flows.
approval_timeout_seconds = 120
# External read-only sources trusted for approve-reads. Entries use kind:owner.
trusted_sources = []

[[mcp_servers]]
name = "filesystem"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/work"]
env = { LOG_LEVEL = "info" }

[[mcp_servers]]
name = "remote-docs"
transport = "http"
url = "https://mcp.example.com/mcp"

[mcp_servers.auth]
registration = "auto"
scopes = ["mcp.read", "mcp.write"]

[providers.claude]
# Overrides the built-in Claude provider command and records native auth diagnostics.
command = "npx -y @agentclientprotocol/claude-agent-acp@latest"
auth_mode = "native_cli"
auth_status_command = "claude auth status"
auth_login_command = "claude auth login"

[providers.claude.models]
# Pre-session catalog defaults consumed by the daemon-owned model catalog.
default = "claude-sonnet-5"

[providers.claude.models.reasoning]
apply = "acp_option"

[[providers.claude.models.curated]]
id = "claude-sonnet-5"
display_name = "Claude Sonnet 5"

[[providers.claude.models.curated]]
id = "claude-fable-5"
display_name = "Claude Fable 5"
featured = true
release_date = "2026-06-09"

[model_catalog.sources.models_dev]
# Optional models.dev enrichment source for catalog metadata.
enabled = true
endpoint = "https://models.dev/api.json"
ttl = "24h"
timeout = "10s"

[marketplace.catalog]
# Base directory containing mcp.json, extensions.json, and skills.json.
base_url = "https://raw.githubusercontent.com/compozy/compozy/main/catalog"
# A browse after this interval refreshes the affected kind before serving it.
ttl = "1h"
# Per-request deadline for fetching one catalog document.
timeout = "10s"

[[providers.claude.mcp_servers]]
name = "github"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
secret_env = { GITHUB_TOKEN = "env:GITHUB_TOKEN" }

[sandboxes.local]
backend = "local"
sync_mode = "none"
persistence = "reuse"
runtime_root = "~"

[sandboxes.daytona-dev]
backend = "daytona"
sync_mode = "session-bidirectional"
persistence = "reuse"
runtime_root = "/home/daytona/workspace"

[sandboxes.daytona-dev.env]
NODE_ENV = "development"

[sandboxes.daytona-dev.network]
allow_public_ingress = false
allow_outbound = true
allow_list = ["api.example.test"]
deny_list = ["metadata.google.internal"]

[sandboxes.daytona-dev.daytona]
api_url = "https://app.daytona.io/api"
target = "team-default"
snapshot = "snap-agent-base"
image = "ubuntu:24.04"
class = "cpu-2"
auto_stop = "30m"
auto_archive = "24h"

[observability]
enabled = true
retention_days = 7
max_global_bytes = 1073741824

[observability.transcripts]
enabled = true
segment_bytes = 1048576
max_bytes_per_session = 268435456

[log]
level = "info"
max_size_mb = 10
max_backups = 5
max_age_days = 30
compress_backups = false

[redact]
# Detect likely credentials in content before logs, streams, or event storage receive them.
# Changing this value requires a daemon restart.
enabled = true

[memory]
enabled = true
global_dir = "~/.compozy/memory"

[memory.controller]
mode = "hybrid"                              # hybrid | rules | llm
max_latency = "300ms"
default_op_on_fail = "noop"

[memory.controller.policy]
max_content_chars = 4096
max_writes_per_min = 60
allow_origins = ["cli", "http", "uds", "tool", "extractor", "dreaming", "file", "provider"]

[memory.recall]
top_k = 5
raw_candidates = 50
fusion = "weighted"
include_already_surfaced = false
include_system = false

[memory.recall.weights]
bm25_unicode = 0.55
bm25_trigram = 0.20
recency = 0.15
recall_signal = 0.10

[memory.recall.freshness]
banner_after_days = 1

[memory.recall.signals]
queue_capacity = 256
worker_retry_max = 3

[memory.decisions]
prune_after_applied_days = 90
keep_audit_summary = true
max_post_content_bytes = 65536

[memory.extractor]
mode = "post_message"
throttle_turns = 1
deadline = "60s"
sandbox_inbox_only = true
inbox_path = "$COMPOZY_HOME/memory/_inbox"
dlq_path = "$COMPOZY_HOME/memory/_system/extractor/failures"

[memory.extractor.queue]
capacity = 1
coalesce_max = 16

[memory.dream]
min_hours = 24
min_sessions = 3
debounce = "10m"
prompt_version = "v1"
check_interval = "30m"

[memory.dream.gates]
min_unpromoted = 5
min_recall_count = 2
min_score = 0.75

[memory.dream.scoring]
recency_half_life_days = 14

[memory.dream.scoring.weights]
frequency = 0.30
relevance = 0.35
recency = 0.20
freshness = 0.15

[memory.session]
ledger_format = "jsonl"
ledger_root = "$COMPOZY_HOME/sessions"
events_purge_grace = "24h"
cold_archive_days = 30
hard_delete_days = 0
max_archive_bytes = 10737418240
unbound_partition = "_unbound"

[memory.daily]
max_bytes = 1048576
max_lines = 5000
rotate_format = "{date}.{seq}.md"
dreaming_window = 7
cold_archive_days = 30
hard_delete_days = 0
max_archive_bytes = 1073741824
sweep_hour = 3
archive_path = "_system/archive"

[memory.file]
max_lines = 200
max_bytes = 25600

[memory.provider]
name = ""                                    # empty = bundled local provider
timeout = "2s"
failure_threshold = 5
cooldown = "30s"

[memory.workspace]
toml_path = "<workspace>/.compozy/workspace.toml" # informational; not configurable
auto_create = true

[skills]
enabled = true
disabled_skills = ["experimental-skill"]
poll_interval = "3s"
allowed_marketplace_mcp = ["clawhub:@team/search-skill"]
allowed_marketplace_hooks = ["clawhub:@team/format-hook"]

[skills.marketplace]
registry = "clawhub"
base_url = "https://registry.example.com"

[extensions.trust]
allow_unverified = true

[extensions.sources.github]
enabled = true
base_url = "https://api.github.com"

[extensions.sources.git]
enabled = true

[extensions.dev]
watch_interval = "2s"

[extensions.resources]
allowed_kinds = ["window_layout"]
max_scope = "workspace"

[automation]
enabled = true
timezone = "UTC"
max_concurrent_jobs = 5
default_fire_limit = { max = 12, window = "1h" }

[automation.suggestions]
pending_cap = 5

[[automation.jobs]]
scope = "workspace"
name = "daily-doc-check"
agent = "docs"
workspace = "workspace-id-or-path"
prompt = "Review changed docs and report stale links."
enabled = true
fire_limit = { max = 2, window = "24h" }

[automation.jobs.schedule]
mode = "cron"
expr = "0 9 * * 1-5"

[automation.jobs.retry]
strategy = "backoff"
max_retries = 3
base_delay = "2s"

[[automation.triggers]]
scope = "workspace"
workspace = "workspace-id-or-path"
name = "failed-session-summary"
agent = "general"
prompt = "Summarize why session {{ index .Data \"session_id\" }} stopped."
event = "session.stopped"
enabled = true

[automation.triggers.filter]
kind = "session.stopped"
data.stop_reason = "error"

[loops.defaults.delivery]
# Global/workspace defaults that seed new delivery loop runs.
iteration_cap = 50
fan_out_width = 4

[loops.defaults.delivery.retry]
# Mechanical node families inherit this policy. 0 disables; maximum 10.
max_attempts = 3
backoff_base = "1s"
backoff_max = "30s"

[loops.defaults.delivery.liveness]
# 0 disables silence attention. Silence never auto-kills or auto-pauses a node.
silence_window = "30m"

[loops.defaults.delivery.resume]
death_streak_limit = 3

[loops.defaults.delivery.predicates]
# CEL warns at 80% of this runtime cost and stops at the limit.
cost_limit = 10000

[loops.defaults.delivery.waits]
admission_attempts = 3
admission_retry_interval = "60s"

[loops.defaults.delivery.admission]
tombstone_horizon = "168h"

[[loops.defaults.delivery.autopause]]
# Ordered, first match wins. Rules are not agent-mutable.
match = "class == 'transport' && attempt >= 2"
action = "pause"

[loops.defaults.delivery.no_progress]
# Generation-hash no-progress window. Compile-time ceiling: 30.
window = 3

[loops.defaults.delivery.gates]
# Gate revision seed default. Compile-time ceiling: 64.
max_revisions = 10

[loops.defaults.delivery.runtime_defaults.worker]
provider = "codex"
model = "gpt-5.4"
reasoning = "high"

[loops.defaults.delivery.runtime_defaults.judge]
provider = "claude"
model = "opus"

[[loops.defaults.delivery.runtime_rules]]
[loops.defaults.delivery.runtime_rules.match]
type = "frontend"
[loops.defaults.delivery.runtime_rules.runtime]
model = "gpt-5.5-codex"

[loops.defaults.delivery.budget]
# 0 means unlimited. When set, budgets are enforced with halt or escalate.
tokens = 0
wall_clock_sec = 0
on_exceeded = "halt"

[loops.defaults.watch]
# Definitions containing watch-source use watch defaults. watch-events alone does not.
iteration_cap = 0
fan_out_width = 2

[loops.defaults.watch.retry]
max_attempts = 3
backoff_base = "1s"
backoff_max = "30s"

[loops.defaults.watch.liveness]
silence_window = "30m"

[loops.defaults.watch.resume]
death_streak_limit = 3

[loops.defaults.watch.predicates]
cost_limit = 10000

[loops.defaults.watch.waits]
admission_attempts = 3
admission_retry_interval = "60s"

[loops.defaults.watch.admission]
tombstone_horizon = "168h"

[loops.defaults.watch.no_progress]
window = 2

[loops.defaults.watch.runtime_defaults.worker]
provider = "codex"
model = "gpt-5.4-mini"

[loops.defaults.watch.runtime_defaults.judge]
provider = "claude"
model = "sonnet"

[loops.defaults.watch.budget]
tokens = 0
wall_clock_sec = 0
on_exceeded = "halt"

[loops.breaker]
# Shared per workspace, target family, and target; only transport failures count.
threshold = 5
probe_interval = "60s"

[loops.inputs.implement-tasks]
# Explicit false remains a present value.
auto_commit = false

[loops.inputs.review-and-fix]
auto_commit = false

[goals]
# Defaults for newly started Goals. Active Runs keep their pinned values.
max_turns = 20
context_nudge_ratio = 0.8
# Durable session-event relay controls. Applied when the daemon starts.
outbox_batch_size = 50
outbox_poll_interval = "100ms"

[autonomy]
# Same-kind re-block count that escalates a task to needs_attention. 0 disables the breaker.
block_recurrence_limit = 2

[task.orchestration]
# Bounds for task summaries, context bundles, scheduler health, and runtime watchdogs.
summary_max_bytes = 4096
context_body_max_bytes = 8192
context_prior_attempts = 5
context_recent_events = 50
spawn_failure_limit = 5
scheduler_bad_tick_threshold = 6
scheduler_bad_tick_cooldown = "5m"
# Zero disables the per-task max-runtime watchdog default. Tasks may still set a per-task override.
default_max_runtime = "0s"
bridge_notification_timeout = "10s"
designated_run_max = 5
# Maximum active worker and coordinator runs per workspace. 0 disables the limit.
max_active_runs_per_workspace = 16
# Default wall-clock deadline for action nodes that omit their own timeout.
action_run_timeout = "30m"
network_status_queue_size = 64
network_status_timeout = "5s"

[task.orchestration.profile]
# Defaults that apply when a task does not persist its own execution profile.
default_coordinator_mode = "inherit"
default_worker_mode = "inherit"
default_sandbox_mode = "inherit"
# inherit has workspace-root semantics unless a higher task policy supplies a mode.
default_worktree_mode = "inherit"
# Gate task-level provider/model overrides on the profile.
allow_task_provider_override = true
# Gate task-level sandbox = "none" selections.
allow_task_sandbox_none = true

[task.orchestration.review]
# Defaults for the post-terminal review gate. See the review-gate docs for end-to-end behavior.
default_policy = "none"
max_rounds = 3
max_review_attempts = 2
timeout = "20m"
rapid_terminal_window = "2m"
rapid_terminal_limit = 3
missing_work_max_items = 20
missing_work_item_max_bytes = 512
reason_max_bytes = 2048
review_text_max_bytes = 12000
next_round_guidance_max_bytes = 4096
failure_policy = "block_task"

[task.recovery]
# When true, agent identities may use force release, force fail, retry, and bulk recovery surfaces.
# Set false to reserve those verbs for non-agent operator identities.
allow_agent_force = true

[[hooks.declarations]]
name = "record-session-start"
event = "session.post_create"
mode = "async"
required = false
priority = 500
timeout = "5s"
command = "printf"
args = ["session started\n"]
env = { HOOK_LOG = "1" }

[hooks.declarations.matcher]
agent_name = "general"

[network]
enabled = true
max_replay_age = 300

[network.live.defaults]
max_wakes = 8
max_wake_wall_time = "5m"
max_total_wall_time = "30m"
max_input_tokens = 200000
max_output_tokens = 50000
max_wake_depth = 3
coalesce_window = "500ms"

[network.live.limits]
max_wakes = 64
max_wake_wall_time = "15m"
max_total_wall_time = "2h"
max_input_tokens = 1000000
max_output_tokens = 200000
max_wake_depth = 5
min_coalesce_window = "100ms"
max_coalesce_window = "5s"

[gateway]
enabled = false
private_port = 0
public_port = 0

[gateway.pairing]
ttl = "5m"
max_pending = 8

[gateway.stream_ticket]
ttl = "30s"

[gateway.auth.rate_limit]
window = "60s"
max_fails = 10

[gateway.verify]
timeout = "10s"
public_dns_resolver = "1.1.1.1:853"

[daemon]

The daemon captures a baseline snapshot at startup, periodic snapshots at this cadence, and one final snapshot during joined shutdown. Each [memory] log record and the runtime.memory item from compozy doctor -o json reports Go heap allocation, heap in-use bytes, goroutines, uptime, and resident memory when the operating system exposes it. resident_memory_kind distinguishes current resident memory from the peak value available on macOS. Setting the interval to 0s starts no sampling worker; doctor reports the feature as disabled. Changing this field is restart-required.

subprocess_health_escalation_threshold consumes the health verdict exposed by an active ACP subprocess. At the configured consecutive-failure count, CompozyOS moves the exact task run bound to that session from queued, claimed, starting, or running to needs_attention. Repeated failed verdicts do not emit another transition, and a completed, failed, or canceled run remains terminal. An unexpected ACP process exit triggers the same transition immediately when the value is positive. Set the field to 0 when you want compozy status and compozy doctor evidence without task mutation. Changing this field is restart-required.

[http]

[app]

The daemon is the sole consumer of both keys. It schedules read-only checks for the runtime and, when installed, the desktop app. The shell does not read config.toml; it observes the durable update operation when an app apply is staged.

[attention]

Attention settings are global and live-applied as one validated candidate. Operators can use the Settings attention controls; agents can use compozy config get|set attention.<key> or the typed GET/PATCH /api/settings/attention surface. The title count is always on and has no config key.

All four fields have the live lifecycle. Removing a workspace also removes its ID from muted_workspaces; unmuting never replays notifications that were suppressed.

[shell.sessions]

Shell session preferences are global and live-applied as one validated candidate. The session list updates them through the typed Settings API; operators and agents can also use compozy config get|set shell.sessions.<key> or GET/PATCH /api/settings/shell.

Both fields have the live lifecycle. The daemon stores them in global config.toml, so the preference survives browser restarts without browser-local storage. Workspace overlays and workspace-scoped CLI or native-tool writes are rejected.

[window_manager]

Window-manager defaults are global desired state and may be overridden by the same typed fields in a workspace config overlay. Every field is live-applied as one validated candidate; an invalid field writes/applies nothing and leaves the previous active generation in place. Operators can use Settings › Layouts, while agents can use compozy config or the typed GET/PATCH /api/settings/window-manager surface and inspect config apply history.

nav_stack_limit applies when compozy window navigate --mode push records the current route. closed_entry_limit applies when a non-minimize close records a reopen entry. Lowering either live limit does not remove existing state; the next relevant mutation retains only the newest values.

[window_manager.gaps]

inner, top, right, bottom, and left are integer CSS pixels from 0 through 64. Clients apply them to the measured work area; normalized durable geometry never stores pixels.

[window_manager.snap]

[window_manager.bindings] and shortcuts

top_center and bottom_center accept zoom, reserved, or none. reserved blocks that edge-center snap; the default bottom_center = "reserved" keeps the approach strip above the Dock clear (the Dock band itself is already excluded from the measured work area). A target-less stack action is invalid because stacking requires an occupied target window. [window_manager.shortcuts] maps action IDs to a chord string or an array of chords. An empty string or array disables an action. desktop.switch accepts ranges through Digit1..9; window.tab.jump accepts Digit1..8. Range members expand before full-map validation, and any duplicate rejects the whole candidate. See Keyboard shortcuts for defaults, examples, and the Terminal preset. Named any/landscape/portrait layout profiles are declarative window_layout resources, not a second config source.

[defaults]

[roles.<role>]

[roles] is the closed routing roster for daemon-owned background work. It is not an extension registry: only the six sections below are accepted. Global $COMPOZY_HOME/config.toml values apply to every workspace unless the selected workspace's .compozy/config.toml overlays them.

coordinator and dreaming-curator are CompozyOS-owned virtual identities. They resolve without an authored AGENT.md, do not appear in public agent catalogs, and are reserved from create, update, duplicate, and extension agent publication. Their embedded prompts are fixed; selecting a custom agent changes routing, not the builtin prompt.

Session-backed role fields

These fields apply to coordinator, dream, checkpoint_summary, memory_extractor, and auto_title.

Fallback chains replace as a whole when a workspace overlay declares them. A session-backed consumer may advance only before ACP accepts a session; CompozyOS never silently reroutes work after acceptance. Immediately before each fallback attempt, CompozyOS emits role.fallback.used with the role, the fallback's one-based attempt, provider, and model. The event records an attempt, not success.

[[roles.auto_title.fallback_chain]]
provider = "codex"
model = "gpt-5.4-mini"
reasoning_effort = "low"

[roles.coordinator]

Coordinator routing uses the shared session-backed fields plus these coordinator-owned safety limits. Task creation alone does not start a coordinator; an executable workspace run must be enqueued, the role must be enabled, and no healthy workspace coordinator may already exist.

[roles.memory_controller]

The memory controller is an in-process model call, so it has no agent field. It accepts enabled, provider, model, reasoning_effort, and fallback_chain with the same routing semantics above, plus these call-policy fields:

timeout is valid only for roles.memory_controller; the strict decoder rejects it on any session-backed role. Role changes are classified live and affect later invocations without a daemon restart. Inspect the resolved roster and per-field provenance with:

compozy roles list --workspace <workspace> -o json
compozy roles show auto_title --workspace <workspace> -o json

HTTP and UDS expose the same GET /api/roles and GET /api/roles/{role} projections. A missing authored agent remains visible as role_agent_not_found; an unknown role returns role_unknown.

[limits]

[session.limits]

[session.attachments]

Session attachments are stored under $COMPOZY_HOME/session-attachments/<workspace_id>/<session_id>/. CompozyOS uses the detected file type rather than a client-supplied Content-Type. Image bytes are stored as received in v1, including EXIF metadata.

[session.attachments]
max_file_bytes = 10485760
max_files_per_prompt = 10
allowed_mime = ["image/png", "image/jpeg", "image/webp", "application/pdf", "text/markdown", "text/plain"]

[session.attachments.retention]
max_count = 200
max_bytes = 1073741824
max_age = "720h"

All session.attachments.* changes are restart-required. A sweep runs at startup, during store access, and periodically. Archiving or clearing a conversation keeps its attachments; deleting a session removes its attachment directory, and unregistering a workspace removes that workspace's complete attachment subtree. Support bundles exclude attachment files and their home-tree entries.

Manage attachment settings

All six session.attachments.* paths are agent-mutable. Use compozy config get|set|unset with -o json to inspect, change, or remove a global value; add --scope workspace --workspace <workspace> to write the workspace overlay. The same paths are available through the typed compozy__config_get, compozy__config_set, and compozy__config_unset tools; resolve the live descriptor before a native-tool mutation so its scope and input type are explicit.

compozy config get session.attachments.max_file_bytes --workspace <workspace> -o json
compozy config set session.attachments.max_file_bytes 20971520 --scope workspace --workspace <workspace> -o json
compozy config set session.attachments.allowed_mime '["image/png","application/pdf","text/plain"]' --scope workspace --workspace <workspace> -o json
compozy config unset session.attachments.max_file_bytes --scope workspace --workspace <workspace> -o json

The other mutable paths are session.attachments.max_files_per_prompt, session.attachments.retention.max_count, session.attachments.retention.max_bytes, and session.attachments.retention.max_age. Each bound must stay positive; allowed_mime must be a non-empty, duplicate-free subset of the six v1 MIME types. A rejected write reports validation rather than changing the desired state. A successful structured response reports lifecycle="restart-required" and next_action="restart-daemon"; restart the daemon, then read the path again to confirm the active generation.

[session.supervision]

Session supervision keeps long-running prompts observable without turning every heartbeat into a stored event. CompozyOS updates session metadata on short heartbeats and only writes durable events for lower-frequency progress, warnings, and timeout classification.

This timeout is based on inactivity, not total runtime. A prompt can run for hours as long as CompozyOS continues to observe runtime activity or controlled waiting heartbeats.

[session.compaction]

[session.compaction] bounds daemon-owned compaction of completed persisted turns when an ACP usage update reports context pressure. CompozyOS first updates the workspace checkpoint with durable sequence coverage, then marks that exact event range archived. Archived rows remain queryable in session events and history; only degraded transcript replay excludes them. The triggering turn is never included in its own compaction span.

These paths are global or workspace desired state and are available through compozy config set and the compozy__config_* native tools. Structured writes return lifecycle="restart-required" and next_action="restart-daemon"; the running daemon keeps its bound compaction policy until restart. Use compozy config apply-history -o json to inspect the blocked apply record.

[agents.soul]

[agents.soul] controls the optional SOUL.md authored persona artifact. Config owns body limits, compact projection budget, and the enabled toggle. SOUL.md cannot redefine any of these keys, and forbidden operational fields in SOUL.md are rejected. See Agent Soul.

Workspace overlay merges scalar fields predictably; setting any key zero-clamps to the validated positive value or fails with a typed validation error. Disabling at runtime does not clear stored snapshots; managed authoring keeps working so operators can repair a broken file.

[agents.heartbeat]

[agents.heartbeat] controls the optional HEARTBEAT.md advisory wake policy and the runtime health/wake-audit subsystem. Config owns cadence, rate limits, retention, and stale thresholds; authored files express bounded preferences only. See Agent Heartbeat.

[agents.heartbeat] does not own task-run lease heartbeat (task_runs + ClaimNextRun + HeartbeatRunLease), [session.supervision] activity heartbeat, or Compozy Network [network] greet presence. Those four authorities remain independent.

HEARTBEAT.md snapshot digest covers the normalized body, canonical frontmatter JSON, and a canonical digest of the resolved [agents.heartbeat] config subset. Editing any field that affects parsing, preference resolution, eligibility, retention, or coalescing invalidates the digest and triggers a fresh resolution at the next wake decision.

[permissions]

The mode also decides cross-workspace requests from agent sessions: approve-all crosses without asking, approve-reads asks at the native-tool boundary and denies elsewhere, and deny-all never crosses and never prompts. There is no separate workspace-access key. See Permissions.

[worktrees]

These values belong to the parent workspace. A workspace overlay changes later creates and Git discovery for that workspace; it does not move existing Worktrees or create a separate Worktree config scope.

The section applies live. New creation and later discovery read the active generation; accepted creations and existing paths keep their recorded decisions. Adoption does not run the copy or setup steps. See Worktree configuration for the full bootstrap flow.

[tools]

Tool registry configuration is loaded before runtime policy and dispatch consume it. These keys only establish defaults and parse-time guardrails; dispatch still revalidates visibility, permission, availability, hooks, and approval state per call. When enabled = true and hosted MCP is enabled, a bare managed session receives the full availability-gated callable catalog unless effective policy narrows it. The startup prompt and hosted MCP metadata still teach the search → info → invoke loop through canonical discovery tools.

[tools.artifacts]

When a post-hook, redacted tool result exceeds its effective result cap, CompozyOS retains the canonical JSON envelope and returns a bounded preview plus an opaque artifact URI. Retention is global across the daemon, while every read remains bound to the workspace that produced the result. The daemon snapshots these settings at boot; config changes require a restart.

[tools.hosted_mcp]

[tools.clarify]

The daemon snapshots this global setting at boot. A structured config write records desired state with lifecycle="restart-required"; it does not change a question already waiting for an answer.

[tools.policy]

trusted_sources does not store credentials. Remote MCP OAuth tokens remain in the MCP auth store, and hosted MCP bind nonces are transient session launch state.

[mcp.oauth]

These global values identify CompozyOS to authorization servers that support a client metadata document. They are restart-required because an in-flight authorization is bound to its callback identity.

The published CompozyOS document lists the default callback only. If you change the daemon port or use a self-hosted callback, publish a matching metadata document and configure both fields together. When the active callback is not listed, CompozyOS skips CIMD and may use the provider's one DCR fallback.

[[mcp_servers]]

Top-level MCP servers are merged with provider, agent, and skill MCP servers during session startup. They can point at local stdio processes or remote Streamable HTTP MCP endpoints.

OAuth-enabled remote servers store only metadata in config. Token material is encrypted in the CompozyOS Vault and is exposed through API, settings, CLI, logs, and the agent-callable compozy__mcp_status / compozy__mcp_auth_status tools only as redacted status. Authorization and logout are daemon-mediated operator flows available through CLI, HTTP, and UDS. The browser callback is HTTP-only and enabled only when the daemon binds to a loopback host.

With registration = "auto", CompozyOS resolves protected-resource metadata, then CIMD, then makes one Dynamic Client Registration fallback attempt. A pre-registered server must include issuer_url and client_id. Authenticate with:

compozy mcp auth login remote-docs
compozy mcp auth login remote-docs --manual
compozy mcp auth status remote-docs
compozy mcp auth logout remote-docs

compozy mcp auth login remote-docs --scope workspace --workspace <workspace-id>

auth login starts the daemon-owned PKCE session and prints the live authorization URL. --manual accepts the full redirect URL, which is the supported path for remote operators and non-loopback HTTP binds. A command succeeds only after status confirms both authenticated and token_present.

Agents can read the same redacted status from inside a session through compozy__mcp_status or compozy__mcp_auth_status. These tools never trigger an OAuth browser flow; missing or expired authentication is repaired through the operator login/logout commands above. Auth-blocked MCP tools are omitted from callable discovery while status/probe output explains the repair path.

For workspace-scoped servers, five consecutive confirmed permanent discovery failures mark the MCP runtime as dead. Settings, status, doctor, and compozy__mcp_status expose the redacted diagnostic; last-known tool descriptors remain visible through compozy__tool_info with reason backend_dead during the same daemon lifetime instead of disappearing from the catalog. CompozyOS suppresses ordinary attempts while the mark is active. After 60 seconds, the next runtime MCP status or discovery access may run one recovery probe; a successful probe clears the mark without restarting the daemon. Doctor reads the durable mark without starting that probe. Recovery is automatic, so there is no manual clear or revive command.

[providers.<name>]

Provider keys override built-ins with the same name or create a custom provider. Built-ins are claude, codex, gemini, opencode, copilot, cursor, kiro, blackbox, cline, goose, hermes, junie, kimi-cli, openclaw, openhands, qoder, qwen-code, pi, openrouter, zai, moonshot, vercel-ai-gateway, xai, minimax, mistral, and groq.

auth_login_command accepts writes in config.toml, through compozy config set, or through the compozy__config_set native tool. It is never a readable configuration value: the set response and compozy config show, list, get, and diff redact it. Provider status, doctor, Settings, HTTP, and UDS likewise never expose the command, its arguments, or its resolved path.

Instead, they expose a safe login descriptor: configured, source = "auth_login_command", an executable basename, presence (present, missing, or unknown), and a recommended_action when recovery is needed (install_cli, login, bind_secret, retry, inspect, or no_retry).

The flat keys default_model, supported_models, and supports_reasoning_effort are no longer accepted. Config that still sets them is rejected with a deterministic hard-cut error citing the exact path. Move every value into [providers.<id>.models] below.

Provider aliases are small and explicit. Aliases such as claude-code, ai-gateway, vercel, kimi, glm, x.ai, grok, open-code, and qwen resolve to the canonical provider ID before config is applied. Model aliases and unknown-to-default fallback were removed: model values must be the exact IDs accepted by the active adapter. Runtime diagnostics, session metadata, and catalog rows preserve that canonical value.

The old providers.<id>.aliases config key was removed for v1. Reference providers by canonical name only; config files that set aliases = [...] under a provider are rejected during load.

auth_mode = "none" means No auth required and is only valid when the provider needs no CompozyOS or provider-owned credential. Set none_security to state why that is safe: local-only transport, external identity enforcement, or public read-only access. No-auth providers cannot define credential_slots, auth_status_command, or auth_login_command; those keys are rejected during config validation.

[providers.<id>.models]

Pre-session model defaults and curated metadata are owned by the daemon-owned model catalog. The catalog merges builtin defaults, the operator config, the optional models.dev enrichment source, live provider discovery sources, and extension model sources, and exposes the result through HTTP, UDS, CLI, the OpenAI-compatible projection, the Host API, and the web. Active ACP configOptions continue to govern model and reasoning controls inside a running session, so curated entries are metadata, never an allowlist.

Rate changes apply to subsequent usage updates and do not reprice persisted token statistics. Agent-reported actual cost remains authoritative over catalog estimation. Estimation requires a finite, non-negative rate for every nonzero token bucket; missing cache-read, cache-write, or reasoning rates do not fall back to input or output rates.

Discovery adapters use the resolved provider auth, env, and home policy. Most discovery paths do not create an ACP session. Cursor is the exception: it starts a short-lived cursor-agent acp inspection and uses only the exact values advertised by its model option. If discovery is unavailable or fails, the catalog records source status and falls back to stale or lower-priority rows. An explicit Cursor model refreshes that ACP catalog before session creation and must be one of its fresh advertised values. A blank Cursor model still lets Cursor choose its native default. The built-in Cursor adapter uses the operator home and stores either the advertised ACP rows or a failed status; later reads use that stored state until an explicit refresh runs. Writes under providers.<id>.models.discovery apply live. A changed discovery source refreshes immediately; provider model metadata changes do not rerun discovery.

OpenClaw, Hermes, and Pi only register a live provider source when models.discovery.enabled = true and either command or endpoint is set; with no discovery wiring, those providers stay on builtin/config rows plus the optional models.dev enrichment.

Top-level [model_catalog.sources.models_dev] controls the cross-provider models.dev enrichment source documented in the next section.

models.reasoning.apply = "none" means CompozyOS does not apply a reasoning level for the provider; it is different from explicit effort none. For a custom provider with provider-controlled reasoning:

[providers.custom.models.reasoning]
apply = "none"

Selectable effort lists come only from config/catalog/live truth. CompozyOS does not infer them from GPT or Claude name prefixes, and it never substitutes the provider default for an unknown model ID.

env_policy = "filtered" preserves ordinary operator context such as PATH, HOME, and locale while stripping secret-shaped daemon variables before launch. env_policy = "isolated" starts from a small operational allowlist and then adds only CompozyOS session metadata, provider-home variables, and explicit bound_secret slots. home_policy = "operator" lets native CLIs reuse existing login state. home_policy = "isolated" creates $COMPOZY_HOME/providers/<provider> with private permissions, sets PROVIDER_HOME, XDG directories, and known provider-specific home variables such as CLAUDE_CONFIG_DIR, CODEX_HOME, and OPENCODE_CONFIG_DIR.

Credential slots use this shape:

[providers.openrouter]
auth_mode = "bound_secret"

[[providers.openrouter.credential_slots]]
name = "api_key"
target_env = "OPENROUTER_API_KEY"
secret_ref = "vault:providers/openrouter/api-key"
kind = "api_key"
required = true

secret_ref supports env:NAME for operator-managed environment variables and vault:providers/<provider>/<slot> for CompozyOS-managed encrypted provider credentials written through the settings API, compozy vault, or web provider editor. The vault: form accepts lowercase provider/slot identifiers only, with letters, numbers, hyphens, underscores, or dots; arbitrary vault paths are not valid provider credential refs.

The slot required flag is enforced at session start for both env: and vault: refs. credential_slots are valid only when auth_mode = "bound_secret". Direct ACP built-ins and the direct pi provider use native_cli by default and do not preflight provider API keys. Pi-backed API-key wrappers such as OpenRouter, z.ai, Moonshot/Kimi, Vercel AI Gateway, xAI, MiniMax, Mistral, and Groq default to CompozyOS-managed bound_secret slots while CompozyOS runs Pi under the hood.

[model_catalog.sources.models_dev]

The models.dev enrichment source feeds catalog metadata such as token windows, tool support, and reasoning hints. It is cross-provider, daemon-owned, and never proves account-level availability.

[model_catalog.sources.models_dev]
enabled = true
endpoint = "https://models.dev/api.json"
ttl = "24h"
timeout = "10s"

models.dev rows write provider-scoped status: a single models.dev refresh records one (source_id="models_dev", provider_id) status row per CompozyOS provider mapped, never a global empty-provider sentinel. Disabled sources still expose status but skip outbound calls. Refresh lifetime is daemon-owned: requests trigger refreshes but the daemon detaches the work, applies an explicit deadline, and joins outstanding refresh workers during shutdown.

Live provider discovery is configured per provider through [providers.<id>.models.discovery]. Discovery refresh is serialized per provider_id before any subprocess or provider-home work, and concurrent refresh requests for the same provider coalesce behind the in-flight refresh. Cursor's default command is cursor-agent acp; setting command overrides that ACP discovery path.

[marketplace.catalog]

CompozyOS fetches the curated MCP server, extension, and skill documents from this base URL. Each kind is validated independently and projected into the global database. If a fetch fails after a successful projection, CompozyOS keeps serving the prior rows with stale status instead of replacing them with an invalid or incomplete document.

This section is global-only because the projection and refresh service are global. Put it in $COMPOZY_HOME/config.toml; workspace overlays and workspace-scoped CLI/native writes are rejected.

[marketplace.catalog]
base_url = "https://catalog.example.com/compozy"
ttl = "30m"
timeout = "5s"

Repository development uses the checkout catalog without changing production defaults. make dev and make dev-daemon set COMPOZY_MARKETPLACE_CATALOG_BASE_URL=file://<checkout>/catalog for their daemon process. This runtime-only value takes precedence over config.toml, appears in effective config reads, and is never persisted. Normal daemon launches keep the main catalog default.

These paths are live in the generated lifecycle matrix: the next feed fetch reads the applied values. Reconcile and inspect the active generation after a write:

compozy config set marketplace.catalog.ttl 30m -o json
compozy config reload -o json
compozy config apply-history --limit 5 -o json

Agent-side config mutation is narrower than the operator CLI. compozy__config_set accepts marketplace.catalog.ttl and marketplace.catalog.timeout with the same duration validation and live lifecycle. It rejects marketplace.catalog.base_url with config_trust_root_forbidden; changing the feed root remains an operator action through compozy config set. Both surfaces require global scope for every marketplace.catalog.* write.

[observability]

[observability.transcripts]

[log]

The daemon writes structured logs to $COMPOZY_HOME/logs/compozy.log. Rotation is owned by the daemon's LogSink, so operators do not need an external logrotate rule for the default file.

Changing any [log] key is restart-required in v1. The daemon applies the new rotation writer on the next start.

[redact]

The daemon snapshots this value during boot, so changing redact.enabled is restart-required. When enabled, CompozyOS redacts matching content before appending it to the global event ledger or a session's events.db; SSE, history, and replay consume that stored redacted form. Structured correlation fields such as session and run IDs, hashes, digests, and fingerprints remain intact.

Disabling the heuristic does not disable exact protections for claim tokens, secret references, or secrets registered by the Vault and other runtime subsystems. Those protections remain authoritative. The heuristic is an additional defense for unregistered provider keys and similar credentials.

Manage the setting through General Settings, compozy config set redact.enabled <true|false> -o json, or the live compozy__config_set descriptor. These writes return lifecycle="restart-required" and next_action="restart-daemon"; they do not change the running process.

[memory]

The [memory] tree is the Memory v2 runtime configuration. Memory v2 is the only memory subsystem; there is no [memory.v2] enabled flag and no parallel compatibility namespace. Disabling [memory] enabled short-circuits prompt assembly, the controller, recall, dreaming, the extractor, and the bundled local provider.

[memory.controller]

[memory.controller.policy]

[memory.recall]

[memory.recall.weights]

Weights are blended into the recall score. Defaults sum to 1.0.

[memory.recall.freshness]

[memory.recall.signals]

[memory.decisions]

WAL retention controls. Pruned rows are replaced by a redaction-safe summary so audit history survives.

[memory.extractor]

The extractor consumes the session.message_persisted hook and writes structured proposals via the controller. inbox_path and dlq_path are validation-locked to the canonical CompozyOS-managed locations.

[memory.extractor.queue]

[memory.dream]

[memory.dream.gates]

[memory.dream.scoring]

[memory.dream.scoring.weights]

Defaults sum to 1.0 across the four factors.

[memory.session]

Forensic ledger materialization. The materializer writes one read-only ledger.jsonl under <ledger_root>/<workspace_id>/<session_id>/. Sessions without a workspace use <unbound_partition> instead of a workspace_id segment.