config.toml

config.toml is the main Compozy runtime desired-state file. Compozy 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 Compozy 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

[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
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 Compozy 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"

[tools]
# Disables registry dispatch and hosted MCP exposure when false.
enabled = true
# Enables Compozy-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 = "sse"
url = "https://mcp.example.com/sse"

[mcp_servers.auth]
type = "oauth2_pkce"
issuer_url = "https://auth.example.com"
client_id = "compozy-desktop"
client_secret_ref = "env:REMOTE_DOCS_MCP_CLIENT_SECRET"
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
metrics_enabled = true

[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.marketplace]
registry = "github"
base_url = "https://api.github.com"
allow_unverified = false

[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.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]
# Watch loops run until stopped unless a loop or run override sets a cap.
iteration_cap = 0
fan_out_width = 2

[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.inputs.software-delivery]
# Explicit false, zero, and valid empty strings remain present values.
auto_commit = false
verify_command = ""

[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"
# 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"

[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, Compozy 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]

[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.

[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 window command-registry IDs to unique, non-empty chord strings; conflicting chords reject the whole candidate. 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 Compozy-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 bundle materialization. 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; Compozy never silently reroutes work after acceptance. Immediately before each fallback attempt, Compozy 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.supervision]

Session supervision keeps long-running prompts observable without turning every heartbeat into a stored event. Compozy 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 Compozy 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. Compozy 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]

[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, Compozy 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_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 HTTP/SSE MCP endpoints.

OAuth-enabled remote servers store only metadata in config. Token material is encrypted in the Compozy 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.

Configure one of metadata_url, issuer_url, or both authorization_url and token_url, then authenticate with:

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

compozy mcp authorize remote-docs --scope workspace --workspace <workspace-id>

authorize and auth login use the same daemon-owned PKCE session. Both print the live authorization URL. --manual accepts either the returned code or 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. Compozy 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.

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 Compozy 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. Discovery never creates an ACP session; if discovery is unavailable or fails, the catalog records source status and falls back to stale or lower-priority rows. Session creation never depends on a successful discovery refresh.

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 Compozy 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. Compozy 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 Compozy 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 Compozy-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 Compozy-managed bound_secret slots while Compozy 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 Compozy 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.

[marketplace.catalog]

Compozy 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, Compozy 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, Compozy 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 Compozy-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.

[memory.daily]

[memory.file]

[memory.provider]

name = "" selects the bundled local provider. Setting a configured provider name routes runtime calls through the registered MemoryProvider while keeping the local provider as a circuit-breaker fallback (see Extensions).

[memory.workspace]

[skills]

If enabled = false, skill polling and marketplace validation are skipped.

[skills.marketplace]

[extensions.marketplace]

allow_unverified controls non-curated side-loads only. Enabling it permits the install path, but each install must still include the --allow-unverified confirmation. Curated installs always verify the catalog-pinned archive digest before extraction; a mismatch cannot be bypassed. Policy changes apply live.

extensions.marketplace.allow_unverified is the only live path in this key family; the registry and base URL remain restart-required under the broader extensions.* lifecycle. Verify the exact result through compozy config reload -o json and compozy config apply-history -o json. A policy-blocked side-load reports extension_unverified_policy_blocked and points to /settings/extensions.

[automation]

[automation.suggestions]

Changes under automation.suggestions.* require a daemon restart. Agents can write the desired value with compozy config set automation.suggestions.pending_cap <value> and inspect the resulting restart action through structured config apply history.

[[automation.jobs]]

Jobs are appended by overlays; they do not replace earlier jobs with the same name.

[[automation.triggers]]

Triggers are appended by overlays; they do not replace earlier triggers with the same name.

See Vault for the CLI, HTTP, UDS, web, and session-scoped surfaces that store and inspect encrypted Compozy-managed secret refs.

[loops.defaults.*]

[loops.defaults.delivery] and [loops.defaults.watch] are global or workspace seed defaults for new loop runs. They are a config plane, not the per-loop loop_config store: effective loop config is resolved as definition defaults, then [loops.defaults.*], then loop_config, then per-run overrides. Existing loop runs keep the config values materialized at start.

Compile-time ceilings stay in code. Operator config can tighten fan-out, no-progress, and gate revision defaults, but it cannot loosen them past the hard runtime ceilings.

| Field | Delivery default | Watch default | Valid values | Description | | ---------------------------------------------- | ---------------- | ------------- | ------------------------------- | --------------------------------------------------------------------------- | ------------------------------- | ------------------------------------------------- | ---- | ----- | ----- | ------------------------- | | iteration_cap | 50 | 0 | Zero or positive integer. | Maximum loop iterations seeded for new runs. 0 means no configured cap. | | no_progress.window | 3 | 2 | 0 through 30. | Generation-hash no-progress window. This is not the inactivity clock. | | gates.max_revisions | 10 | 0 | 0 through 64. | Gate revision seed default. 0 means no gate-revision seed for that class. | | budget.tokens | 0 | 0 | Zero or positive integer. | Token budget. 0 means unlimited. A set budget is enforced. | | budget.wall_clock_sec | 0 | 0 | Zero or positive integer. | Wall-clock budget in seconds. 0 means unlimited. | | budget.on_exceeded | halt | halt | halt or escalate. | Enforcement policy once a non-zero budget is exceeded. | | runtime_defaults.worker.provider | empty | empty | Configured provider name/alias. | Worker provider default. | | runtime_defaults.worker.model | empty | empty | Non-empty model ID. | Worker model default. Gateway IDs may contain /. | | runtime_defaults.worker.reasoning | empty | empty | none | minimal | low | medium | high | xhigh | max. | Worker reasoning default. | | runtime_defaults.judge.provider | empty | empty | Configured provider name/alias. | Judge provider default. | | runtime_defaults.judge.model | empty | empty | Non-empty model ID. | Judge model default. | | runtime_defaults.judge.reasoning | empty | empty | none | minimal | low | medium | high | xhigh | max. | Judge reasoning default. | | runtime_rules[].match.id | type | complexity | none | none | Exactly one non-empty selector. | Selects imported tasks; id > type > complexity. | | runtime_rules[].runtime.{provider,model,...} | none | none | At least one populated field. | Field-merged override; later equal-specificity rules win. | | fan_out_width | 4 | 2 | 0 through 64. | Fan-out width seed default for new runs. |

These paths are mutable through compozy config set and the native config tools. Writes return lifecycle="restart-required" because the daemon does not rewrite active runs after defaults change. New starts read the resolved defaults after the daemon reloads its config state; live runs keep the effective config materialized at start.

For workers, runtime fields resolve from per-run rules, imported task frontmatter, configured rules, node params.runtime, runtime defaults, then the agent definition. Judges use judge defaults plus criterion runtime; task rules never apply. model_defaults, scalar params.model, and scalar criterion model are rejected instead of translated. Static loop validate checks authored definition values; dry-run and submission check the effective workspace/run values before any ACP process starts.

[loops.inputs.<loop-name>]

Each table supplies global or workspace defaults for inputs declared by one dynamically enrolled Loop. Values resolve independently as per-run input, workspace default, global default, then definition default. Presence is tracked before config overlays merge, so false, 0, and valid empty strings do not collapse into “unset.” Dry-run exposes every effective value and its run|workspace|global|definition origin.

Config loading accepts dynamic Loop names and scalar values without consulting the current catalog. Static loop validate validates only defaults authored in the definition. Configured defaults and per-run values are validated together during effective dry-run or submission; unknown keys and type mismatches return typed input_default {loop,key,reason} diagnostics before a run or ACP process is created.

Manage one value through the validated config writer:

compozy config set loops.inputs.software-delivery.auto_commit false \
  --scope workspace --workspace /absolute/project/root
compozy config get loops.inputs.software-delivery.auto_commit \
  --workspace /absolute/project/root
compozy config unset loops.inputs.software-delivery.auto_commit \
  --scope workspace --workspace /absolute/project/root

HTTP and UDS provide exact-scope inspect, replace, set, and delete operations at /api/workspaces/{workspace_id}/loops/{name}/input-defaults. These paths are also available through native config tools. Changes are restart-required; existing runs retain their materialized inputs.

[goals]

[goals] defines global or workspace defaults for newly started Goals. Its global configuration also controls the daemon-wide durable Goal session-event relay. All four paths are mutable through compozy config set and the native config tools. Writes return lifecycle="restart-required"; restarting activates Goal defaults for later starts and applies global relay settings without rewriting active Runs or their checkpoints. Workspace overlays affect Goal defaults only because one relay serves every workspace in the daemon.

context_nudge_ratio = 0.0 is explicit and disables context nudging. A config change cannot alter the ratio of an existing Run, including after daemon restart or a later generation.

Goal defaults follow the normal config precedence: built-in defaults, then global $COMPOZY_HOME/config.toml, then the resolved workspace's .compozy/config.toml. The Run start resolves that effective config once and persists the selected values. Later config generations apply only to later starts.

The CLI and native-tool mutation allowlists contain exactly these Goal paths:

• goals.max_turns — integer
• goals.context_nudge_ratio — number
• goals.outbox_batch_size — integer
• goals.outbox_poll_interval — duration

# Global desired state
compozy config set goals.max_turns 30 -o json

# Workspace desired state
compozy config set goals.context_nudge_ratio 0.75 \
  --scope workspace \
  --workspace /absolute/path/to/workspace \
  -o json

The equivalent agent path is compozy__config_set after resolving its live descriptor. Both surfaces validate the same allowlist and bounds, write desired state at global or workspace scope, and return lifecycle="restart-required" with next_action="restart-daemon". They do not mutate a live Goal.

[autonomy]

Top-level [autonomy] holds task-kernel autonomy defaults that are not scoped to the coordinator or scheduler subtables. The default below is loaded from internal/config/autonomy.go.