← Schema index / Config Reference
projects schema (1-150)
Canonical generated docsThis section is generated from
caco config schema --json. The table below preserves the runtime field path, type, required/default markers, and canonical description for every value in this slice.Project definitions — repositories managed by Cacophony. Accepts both a list of projects (with 'name' field) and a map keyed by project name.
| Field path | Type | Required | Default | Canonical description |
|---|---|---|---|---|
projects | section | optional | Project definitions — repositories managed by Cacophony. Accepts both a list of projects (with 'name' field) and a map keyed by project name. | |
└ projects.name | string | required | Unique project name. | |
└ projects.remote | string | required | Git remote URL. | |
└ projects.default_branch | string | optional | main | Default branch name. |
└ projects.canonical_nodes | list[string] | optional | Hard allowlist of nodes permitted to materialize and use this project's canonical source checkout. Omission preserves legacy derived placement. | |
└ projects.always_update | bool | optional | false | Keep the canonical checkout materialized and periodically refreshed on every node permitted by canonical_nodes, independent of local agent/default/friend selection. |
└ projects.identity | string | optional | Identity to use for git operations. | |
└ projects.github_ssh_routing | string | optional | auto | GitHub SSH routing for daemon-managed git in this project: auto (respect configured host/port), ssh_over_443, or default_port. Node-level policy wins when set. |
└ projects.reintegration_max_stale_count | u32 | optional | 5 | Maximum reintegration-count staleness tolerated by future reintegration guards. |
└ projects.auth_token | string | optional | Inline auth token for repo-backed project registries. | |
└ projects.status | string | optional | active | Project lifecycle status: active or pending_creation. |
└ projects.beads | map | optional | Beads config. | |
└ projects.beads.enabled | bool | optional | false | Whether beads are enabled. |
└ projects.beads.branch | string | optional | Beads branch name. | |
└ projects.beads.dispatch_queue_ttl | string | optional | Auto-clean TTL for queued async bead dispatch intents. | |
└ projects.beads.sync_interval_secs | u64 | optional | 10 | Floor cadence for background beads sync in seconds. |
└ projects.beads.sync_backoff | map | optional | Opt-in exponential backoff after consecutive no-change syncs. | |
└ projects.beads.sync_backoff.enabled | bool | optional | false | Enable no-change backoff. |
└ projects.beads.sync_backoff.max_interval_secs | u64 | optional | 1800 | Maximum no-change interval; must be at least sync_interval_secs. |
└ projects.beads.sync_backoff.multiplier | f64 | optional | 2.0 | No-change interval multiplier (1.0..=16.0). |
└ projects.beads.sync_backoff.jitter_secs | u64 | optional | 0 | Deterministic per-project jitter, capped by max_interval_secs. |
└ projects.beads.failover | map | optional | Project-level failover overrides. | |
└ projects.beads.failover.reclaim_unavailable_agents_after | duration | optional | Project-level override for global reclaim timer. | |
└ projects.worktree | map | optional | Worktree base directory. | |
└ projects.worktree.base_dir | string | optional | Base directory for worktrees. | |
└ projects.friend_projects | list[friend_project] | optional | Project-level friends inherited by all agents unless narrowed or disabled by more-specific config. | |
└ projects.friend_projects.project | string | required | Target project name. | |
└ projects.friend_projects.branch | string | optional | Target branch; omitted means the friend project's default_branch. Mutually exclusive with revision. | |
└ projects.friend_projects.revision | string | optional | Pinned git revision. Mutually exclusive with branch. | |
└ projects.friend_projects.permissions | list[string] | optional | [checkout_read] | Granted operations: checkout_read, checkout_write, beads_read, beads_create, beads_update, beads_claim, beads_close, beads_dispatch. |
└ projects.friend_projects.materialize | bool | optional | false | Materialize a real friend checkout cloned from the friend project's remote; omitted means a virtual friend with no checkout. |
└ projects.friend_projects.enabled | bool | optional | true | Set false in a narrower layer to disable an inherited friend. |
└ projects.agent_defaults | map | optional | Default agent spawn parameters. | |
└ projects.agent_defaults.type | string | optional | Default agent type. | |
└ projects.agent_defaults.effort | string | optional | Runtime reasoning effort; explicit requests win. | |
└ projects.agent_defaults.profile | string | list[string] | optional | Profile or ordered list for composite composition. | |
└ projects.agent_defaults.preset | string | optional | Default preset ID. | |
└ projects.agent_defaults.readiness_timeout_secs | u64 | optional | 60 | Readiness sentinel timeout. |
└ projects.agent_defaults.node_selector | string | optional | Spawn placement: local_only, round_robin, or least_overloaded. | |
└ projects.agent_defaults.resources | map | optional | Per-agent resource ceilings. | |
└ projects.agent_defaults.resources.vcpu | f64 | optional | Logical CPU budget (e.g. 2.0 for two cores). | |
└ projects.agent_defaults.resources.memory | string | optional | Memory ceiling (e.g. '8GiB', '512MiB'). | |
└ projects.agent_defaults.model | string | optional | Model to use for agent launches (e.g. 'opus', 'sonnet'). Passed as --model. | |
└ projects.agent_defaults.provider | string | optional | Provider for agent launches (e.g. 'openai', 'anthropic', 'google', 'github-copilot'). | |
└ projects.agent_defaults.short_name_strategy | map | optional | Strategy for generating a short human-friendly display name at agent creation time. | |
└ projects.agent_defaults.short_name_strategy.strategy | string | required | Short-name strategy: adj_noun, template or llm. | |
└ projects.agent_defaults.short_name_strategy.template | string | optional | Bounded display template for strategy = template. Placeholders: {adj}, {noun}, {profile}, {bead}, {node}, {n}. Names remain aliases, not identities. | |
└ projects.agent_defaults.short_name_strategy.llm | string | optional | Top-level llm alias used when strategy = llm. | |
└ projects.agent_defaults.checkout_type | string | optional | worktree | How this project's agents materialize their working checkout: worktree (default; a git worktree sharing the canonical.git, fastest startup), clone, full, read_only_symlink, or pr_branch (an existing GitHub PR head branch; requires github_integration.enabled,). made worktree the default. |
└ projects.agent_defaults.persistent_agent_idle_timeout_secs | u64 | optional | 1800 | Auto-restart persistent agents after this much tool inactivity. |
└ projects.agent_defaults.completed_retention_hours | u64 | optional | 72 | Delete acknowledged completed agent checkouts after N hours. |
└ projects.agent_defaults.completed_retention_count | u32 | optional | 20 | Keep at most N acknowledged completed agent checkouts per project, pruning oldest first. |
└ projects.agent_defaults.completed_retention_bytes | string | optional | 50GB | Hard cap on acknowledged completed checkout disk usage for this project. |
└ projects.agent_defaults.pi_extra_config_dirs | list[string] | optional | Extra config directories merged into managed Pi workspaces. | |
└ projects.agent_defaults.override_pi_agent_dir | string | optional | Read-only operator-owned Pi agent directory passed directly to managed Pi launches instead of materializing .pi-agent config. | |
└ projects.agent_defaults.warmup_cache_injection | map | optional | Disabled-by-default advisory warmup-cache prompt injection settings for spawned agents. | |
└ projects.agent_defaults.warmup_cache_injection.enabled | bool | optional | false | Enable advisory warmup-cache prompt injection. |
└ projects.agent_defaults.warmup_cache_injection.max_age_seconds | i64 | optional | 86400 | Maximum accepted warmup summary age before skipping injection. |
└ projects.agent_defaults.warmup_cache_injection.max_chars | usize | optional | 2048 | Maximum characters injected from the warmup summary. |
└ projects.agent_defaults.pane_error_detection | bool | optional | false | Enable tmux pane content scanning for Pi agent fatal error detection. |
└ projects.agent_defaults.eligible_nodes | list[string] | optional | Allowlist of node names for round_robin/least_overloaded placement. Manual --node overrides bypass this. | |
└ projects.agent_defaults.friend_projects | list[friend_project] | optional | Agent-default friend project overlays inherited by agents in this project. | |
└ projects.agent_defaults.friend_projects.project | string | required | Target project name. | |
└ projects.agent_defaults.friend_projects.branch | string | optional | Target branch; omitted means the friend project's default_branch. Mutually exclusive with revision. | |
└ projects.agent_defaults.friend_projects.revision | string | optional | Pinned git revision. Mutually exclusive with branch. | |
└ projects.agent_defaults.friend_projects.permissions | list[string] | optional | [checkout_read] | Granted operations: checkout_read, checkout_write, beads_read, beads_create, beads_update, beads_claim, beads_close, beads_dispatch. |
└ projects.agent_defaults.friend_projects.materialize | bool | optional | false | Materialize a real friend checkout cloned from the friend project's remote; omitted means a virtual friend with no checkout. |
└ projects.agent_defaults.friend_projects.enabled | bool | optional | true | Set false in a narrower layer to disable an inherited friend. |
└ projects.context | map | optional | Per-project `caco context` section-limit overrides. | |
└ projects.context.beads_limit | usize | optional | 12 | Max recent open/in-progress beads in the dump. |
└ projects.context.inbox_limit | usize | optional | 8 | Max recent inbox messages in the dump. |
└ projects.context.commits_limit | usize | optional | 12 | Max recent commits in the dump. |
└ projects.context.summaries_limit | usize | optional | 1 | Max recent session summaries in the dump. |
└ projects.context.section_byte_cap | usize | optional | 8192 | Max bytes per section before truncation. |
└ projects.agent_runtime | map | optional | Per-project managed shell/runtime overrides. | |
└ projects.agent_runtime.multiplexer | string | optional | herdr | Persistent terminal host for new shell agents: herdr or tmux. Existing agents retain their backend. |
└ projects.agent_runtime.herdr | map | optional | Herdr terminal host settings. | |
└ projects.agent_runtime.herdr.session | string | optional | caco | Named Herdr session shared by Caco agents; default selects the user's main Herdr session. |
└ projects.agent_runtime.herdr.binary | string | optional | herdr | Herdr executable on the owning node. |
└ projects.agent_runtime.shell | map | optional | Shell/interpreter configuration. | |
└ projects.agent_runtime.shell.program | string | optional | bash | Shell binary path or name. |
└ projects.agent_runtime.shell.init | string | optional | minimal | Init mode: minimal (default), user, or file. |
└ projects.agent_runtime.shell.init_file | string | optional | Custom init file path (when init is 'file'). | |
└ projects.agent_runtime.shell.args | list[string] | optional | Extra arguments passed to the shell. | |
└ projects.agent_runtime.shell.shell_rc | string | optional | Inline shell init content sourced into every agent shell (concatenated across layers). | |
└ projects.agent_runtime.path | map | optional | Ordered PATH additions. | |
└ projects.agent_runtime.path.prepend | list[string] | optional | Directories prepended to PATH. | |
└ projects.agent_runtime.environment | map[string, string] | optional | Non-secret environment defaults. | |
└ projects.environment | map[string, string] | optional | Non-secret env defaults for managed agent launches. | |
└ projects.checkout_bootstrap | list[string] | optional | Shell snippets run during checkout bootstrap. | |
└ projects.concurrency | map | optional | Agent spawn concurrency ceilings for this project. | |
└ projects.concurrency.global | map | optional | Global ceiling across all profiles. | |
└ projects.concurrency.global.max_parallel | u32 | required | Maximum live non-terminal agents. | |
└ projects.concurrency.profile | map[string, map] | optional | Per-profile ceilings keyed by profile name. | |
└ projects.concurrency.profile.max_parallel | u32 | required | Maximum live non-terminal agents for this profile. | |
└ projects.test | map | optional | Queued test defaults for this project. | |
└ projects.test.command | string | optional | Default test command (autodetected if omitted). | |
└ projects.test.max_parallel | u32 | optional | 1 | Maximum concurrent test jobs. |
└ projects.test.wait_timeout_secs | u64 | optional | 60 | How long caco test run --wait blocks before returning the job ID. |
└ projects.test.max_runtime_secs | u64 | optional | 7200 | Runaway safety net on queued test job execution time in seconds. |
└ projects.build | map | optional | Queued build defaults for this project. | |
└ projects.build.command | string | optional | Default build command (autodetected if omitted). | |
└ projects.build.max_parallel | u32 | optional | 1 | Maximum concurrent build jobs. |
└ projects.build.wait_timeout_secs | u64 | optional | 60 | How long caco build run --wait blocks before returning the job ID. |
└ projects.build.max_runtime_secs | u64 | optional | 7200 | Runaway safety net on queued build job execution time in seconds. |
└ projects.releases | map | optional | Release system configuration. | |
└ projects.releases.channels | map[string, map] | optional | Named release channels keyed by channel name. | |
└ projects.releases.channels.<channel-name> | map | optional | Release channel definition. | |
└ projects.releases.channels.<channel-name>.strategy | string | required | Release strategy: node, cluster, github, bead_dispatch, command, or a named custom release type. | |
└ projects.releases.channels.<channel-name>.build_command | string | optional | Build command to run in the release worktree. | |
└ projects.releases.channels.<channel-name>.push_command | string | optional | Push/upload command to run after a successful build. | |
└ projects.releases.channels.<channel-name>.runs_on | map[string, list[string]] | optional | Per-architecture node mappings for cluster strategy. | |
└ projects.releases.channels.<channel-name>.workflow | string | optional | GitHub Actions workflow file name for github strategy. | |
└ projects.releases.channels.<channel-name>.trigger_ref | string | optional | Git ref to trigger the workflow against. | |
└ projects.releases.channels.<channel-name>.max_runtime_secs | u64 | optional | 1800 | Hard ceiling on release job execution time in seconds. |
└ projects.releases.android_companion | map | optional | Android companion release automation (Play internal-testing auto-push toggle,). | |
└ projects.releases.android_companion.owner_node | string | optional | Single node that owns companion detection, notification/choice creation, and Play dispatch. Required for unattended auto-push to prevent one dispatch per daemon node. | |
└ projects.releases.android_companion.auto_push | string | optional | off | Unattended Play internal-testing auto-push mode: off (default) keeps the operator-gated caco choices promotion path; rollout/draft skip the choice and dispatch the companion workflow with the matching play_upload_mode. |
└ projects.releases.app_stores | map[string, map] | optional | First-party mobile app-store release sources keyed by a stable id; their store-derived state is surfaced by caco release refresh/list/status alongside GitHub Actions release jobs. | |
└ projects.releases.app_stores.<source-id> | map | optional | Mobile app-store release source definition. | |
└ projects.releases.app_stores.<source-id>.provider | string | required | Store provider: google_play or app_store_connect. | |
└ projects.releases.app_stores.<source-id>.app_id | string | required | App identifier: Android applicationId or iOS bundle id. | |
└ projects.releases.app_stores.<source-id>.platform | string | required | Platform surface: android, wearos, ios, or watchos. | |
└ projects.releases.app_stores.<source-id>.track | string | optional | Store track/channel to track (e.g. internal, wear:internal, a TestFlight group). Defaults to the provider's primary internal track. | |
└ projects.releases.app_stores.<source-id>.credential | string | optional | Name of a configured credential wrapper supplying store API credentials. Only the wrapper name is stored; secrets are never inlined. | |
└ projects.releases.app_stores.<source-id>.label | string | optional | Optional human-readable label for status surfaces. | |
└ projects.agents | map | optional | Project-scoped agent declarations and groups. | |
└ projects.agents.flow | map | optional | Flow-created worker preferences. | |
└ projects.agents.flow.default | map | optional | Project Flow launch overlay. | |
└ projects.agents.flow.default.type | string | optional | Default agent type. | |
└ projects.agents.flow.default.effort | string | optional | Runtime reasoning effort; explicit requests win. | |
└ projects.agents.flow.default.profile | string | list[string] | optional | Profile or ordered list for composite composition. | |
└ projects.agents.flow.default.preset | string | optional | Default preset ID. | |
└ projects.agents.flow.default.readiness_timeout_secs | u64 | optional | 60 | Readiness sentinel timeout. |
└ projects.agents.flow.default.node_selector | string | optional | Spawn placement: local_only, round_robin, or least_overloaded. | |
└ projects.agents.flow.default.resources | map | optional | Per-agent resource ceilings. | |
└ projects.agents.flow.default.resources.vcpu | f64 | optional | Logical CPU budget (e.g. 2.0 for two cores). | |
└ projects.agents.flow.default.resources.memory | string | optional | Memory ceiling (e.g. '8GiB', '512MiB'). | |
└ projects.agents.flow.default.model | string | optional | Model to use for agent launches (e.g. 'opus', 'sonnet'). Passed as --model. | |
└ projects.agents.flow.default.provider | string | optional | Provider for agent launches (e.g. 'openai', 'anthropic', 'google', 'github-copilot'). | |
└ projects.agents.flow.default.short_name_strategy | map | optional | Strategy for generating a short human-friendly display name at agent creation time. | |
└ projects.agents.flow.default.short_name_strategy.strategy | string | required | Short-name strategy: adj_noun, template or llm. | |
└ projects.agents.flow.default.short_name_strategy.template | string | optional | Bounded display template for strategy = template. Placeholders: {adj}, {noun}, {profile}, {bead}, {node}, {n}. Names remain aliases, not identities. | |
└ projects.agents.flow.default.short_name_strategy.llm | string | optional | Top-level llm alias used when strategy = llm. | |
└ projects.agents.flow.default.checkout_type | string | optional | worktree | How this project's agents materialize their working checkout: worktree (default; a git worktree sharing the canonical.git, fastest startup), clone, full, read_only_symlink, or pr_branch (an existing GitHub PR head branch; requires github_integration.enabled,). made worktree the default. |
└ projects.agents.flow.default.persistent_agent_idle_timeout_secs | u64 | optional | 1800 | Auto-restart persistent agents after this much tool inactivity. |
└ projects.agents.flow.default.completed_retention_hours | u64 | optional | 72 | Delete acknowledged completed agent checkouts after N hours. |
└ projects.agents.flow.default.completed_retention_count | u32 | optional | 20 | Keep at most N acknowledged completed agent checkouts per project, pruning oldest first. |
└ projects.agents.flow.default.completed_retention_bytes | string | optional | 50GB | Hard cap on acknowledged completed checkout disk usage for this project. |
└ projects.agents.flow.default.pi_extra_config_dirs | list[string] | optional | Extra config directories merged into managed Pi workspaces. |