Configuration Schema
This page is a flat reference for the most commonly used colony.config.yaml fields. It is not exhaustive. For a narrative guide that explains when and why to use each section, see Self-Host — Configuration.
Config File Location
Section titled “Config File Location”Colony loads config from the first location found:
- Path passed via the
--configCLI flag ./colony.config.yaml(current working directory)~/.colony/config.yaml(user home directory)
Call resolveConfig() before any GitHub operations. It validates the config and resolves credentials from environment variables.
Environment Variables
Section titled “Environment Variables”| Variable | Required | Description |
|---|---|---|
GITHUB_TOKEN (or the variable named by github.token_env) | Required unless github.app is configured | Personal Access Token for GitHub API access. Only needed for PAT auth |
ANTHROPIC_API_KEY | Required with the default anthropic provider and api-key auth mode | Anthropic API key for Claude Code invocations. Not used with claude.auth_mode: oauth-token (CLAUDE_CODE_OAUTH_TOKEN), claude.auth_mode: wif, claude.provider: foundry (ANTHROPIC_FOUNDRY_API_KEY) or claude.provider: gateway (ANTHROPIC_AUTH_TOKEN or the variable named by claude.gateway.auth_token_env; see ClaudeGatewayConfig) |
OPENAI_API_KEY (or the variable named by codex.api_key_env) | Required when any agent uses engine: codex | OpenAI API key for Codex invocations; see codex |
DATABASE_URL (or the variable named by database.url_env) | required | Postgres connection string, read via database.url_env |
github
Section titled “github”Authentication and identity settings for the target repository.
| Field | Type | Default | Description |
|---|---|---|---|
owner | string | required | GitHub organization or user that owns the target repository |
repo | string | required | Target repository name |
token_env | string | 'GITHUB_TOKEN' | Name of the environment variable containing the Personal Access Token |
app | GitHubAppConfig | — | GitHub App credentials for the coder identity (Analyzer, Developer). Use instead of token_env for App-based auth |
ops_app | GitHubAppConfig | — | Separate GitHub App credentials for the ops identity (Mayor, Reviewer, Merger) |
ops_token_env | string | — | Name of the environment variable containing the PAT for the ops identity |
bot_username | string | — | Display name shown for bot-authored comments and labels |
GitHubAppConfig
Section titled “GitHubAppConfig”Used by github.app and github.ops_app.
| Field | Type | Default | Description |
|---|---|---|---|
app_id | number | required | GitHub App ID (found in the App settings page) |
private_key_path | string | required | Path to the .pem private key file for this App |
installation_id | number | required | Installation ID for this App on the target organization or repo |
labels
Section titled “labels”| Field | Type | Default | Description |
|---|---|---|---|
prefix | string | 'colony' | Prefix for pipeline state labels (e.g. colony:analyzing, colony:ready-for-dev). Change to run multiple Colony instances against the same repo with distinct namespaces |
commands
Section titled “commands”Controls operator slash commands posted as issue comments.
| Field | Type | Default | Description |
|---|---|---|---|
root | string | 'colony' | Prefix for slash commands (e.g. /colony:retry). Must be lowercase, start with a letter, contain only a-z, 0-9 and -, and be 1–32 characters long |
authorization | 'write' | 'any' | 'write' | Who may run slash commands. 'write' accepts only commenters with write access to the repo; 'any' accepts any non-bot commenter. Bot comments are always ignored |
workspace
Section titled “workspace”Controls how Colony creates and manages git worktrees for each issue.
| Field | Type | Default | Description |
|---|---|---|---|
repo_dir | string | '.' | Path to the local git clone of the target repository. Not required for Docker Compose deployments — Workers clone automatically |
base_dir | string | '~/.colony/workspaces/{owner}/{repo}' | Base directory for worktrees. Supports {owner} and {repo} template tokens |
branch | string | 'main' | Default branch name. Override when the repo’s default branch is not main |
setup_command | string | — | Command to run after creating a worktree, instead of the one Colony detects from the repository’s files. Setting it also turns off runtime version auto-detection |
setup_timeout | number | 300 | Seconds to allow the setup command to run before timing out |
prebuild_command | string | — | Command to run after setup_command to pre-build workspace packages |
cleanup_after_merge | boolean | true | Remove the worktree after a PR is merged |
prune_blocked_after_days | number | 7 | Days before worktrees for blocked issues are automatically pruned |
review_workspace_base | string | — | Container-local path for ephemeral reviewer worktrees |
skip_pre_push_hook | boolean | — | When true, passes --no-verify to git push |
database
Section titled “database”Connection settings for the Postgres pipeline store. Optional in config — if omitted, Colony reads DATABASE_URL from the environment. A Postgres connection is always required at runtime.
| Field | Type | Default | Description |
|---|---|---|---|
url_env | string | 'DATABASE_URL' | Name of the environment variable containing the Postgres connection string |
max_connections | number | 10 | Maximum connections in the pg connection pool |
idle_timeout | number | 10000 | idleTimeoutMillis for the pg pool (milliseconds) |
ssl | boolean | false | Enable SSL for Postgres connections. Required for most cloud-hosted Postgres instances |
logging
Section titled “logging”| Field | Type | Default | Description |
|---|---|---|---|
level | string | 'info' | Pino log level: 'trace', 'debug', 'info', 'warn', 'error', 'fatal' |
format | 'json' | 'pretty' | 'pretty' | Use 'json' in production for structured log ingestion; 'pretty' for local development |
max_daily_usd
Section titled “max_daily_usd”Top-level scalar. Caps each tenant’s aggregate spend for the current UTC day. When a tenant reaches the cap, its new work halts until the next UTC day.
| Field | Type | Default | Description |
|---|---|---|---|
max_daily_usd | number | 50 | Maximum USD per UTC day |
budget_headroom_pct | number (0–100) | 10 | Percentage reserved below max_daily_usd to absorb overage from concurrent Workers. 0 disables the reservation |
The effective stop threshold is max_daily_usd × (1 − budget_headroom_pct / 100). With the defaults (50 and 10), Workers stop at $45.
Soft cap:
max_daily_usdis an approximate limit, not an exact one. With concurrent workers, each worker checks the DB cost independently before claiming a task, so up to(pool_size − 1)in-flight tasks may complete past the cap.budget_headroom_pctlowers the effective ceiling to absorb this overage.
max_daily_usd is an enforced runtime ceiling. It differs from cost_budget.monthly_usd (tenant-level monthly enforcement) and the per-repo enforced monthly cap, which is stored in the Pipeline Store rather than in this file. In Colony Cloud, set it under Reporting budgets. In a self-hosted deployment, set repo_configs.budget_cap_usd directly; see Self-Host — Configuration. Self-hosters set max_daily_usd in their own config; on Colony Cloud it is managed by Colony and shown read-only. See Cost & Budget concepts — the three budget controls.
attribution
Section titled “attribution”| Field | Type | Default | Description |
|---|---|---|---|
enabled | boolean | true | When false, no disclosure footer is appended. Disabling weakens EU AI Act Article 50(1) compliance — only disable after legal review |
text | string | 'Orchestrated by [Colony](https://runcolony.com) — autonomous software development pipeline.' | Disclosure text appended after a horizontal rule |
intelligence
Section titled “intelligence”Controls automatic promotion of repo intelligence candidates. When auto-promote is enabled, Colony promotes high-confidence patterns to approved status without manual review, reducing curation overhead for large repos.
intelligence.auto_promote
Section titled “intelligence.auto_promote”| Field | Type | Default | Description |
|---|---|---|---|
enabled | boolean | false | When true, Colony automatically promotes intelligence candidates that meet the confidence and observation thresholds |
confidence_threshold | number (0–1) | 0.8 | Minimum confidence score a candidate must reach before auto-promotion. Raise to require stronger evidence; lower to promote sooner |
min_observation_count | positive integer | 2 | Minimum number of observations required before a candidate is eligible for auto-promotion. Raise for repos with high issue volume; lower for repos where patterns accumulate slowly |
event_log
Section titled “event_log”Controls the local event log written by Colony agents.
| Field | Type | Default | Description |
|---|---|---|---|
enabled | boolean | true | Enable or disable event logging |
dir | string | '~/.colony/events' | Directory where event log files are written |
retention_days | number | 30 | Days to retain event log files before pruning |
webhook
Section titled “webhook”Configures the webhook receiver that listens for incoming GitHub webhook events. Omit if not running the webhook receiver.
| Field | Type | Default | Description |
|---|---|---|---|
enabled | boolean | required | Enable the webhook receiver |
port | number (1–65535) | required | Port for the webhook receiver HTTP server |
secret_env | string | — | Name of the environment variable containing the HMAC secret for verifying GitHub webhook payloads |
claude
Section titled “claude”Controls Claude CLI invocation behavior and model selection for all agents.
| Field | Type | Default | Description |
|---|---|---|---|
timeout | number | 1800 | Overall Claude CLI invocation timeout in seconds |
max_retries | number | 1 | Number of times to retry a failed Claude invocation |
inactivity_timeout | number | 300 | Seconds without output before the process is killed with SIGKILL |
max_cost_per_issue | number | — | USD cost cap per issue. When reached, the issue moves to failure-blocked. Omit for no limit |
binary_path | string | 'claude' | Path to the Claude CLI binary |
provider | 'anthropic' | 'foundry' | 'gateway' | 'anthropic' | API provider. Use 'foundry' to route through Azure Foundry, or 'gateway' to route through any Anthropic-compatible AI gateway (e.g. TrueFoundry, LiteLLM) |
foundry | ClaudeFoundryConfig | — | Azure Foundry settings. Only used when provider: 'foundry' |
gateway | ClaudeGatewayConfig | — | Anthropic-compatible gateway settings. Only used when provider: 'gateway' |
auth_mode | 'api-key' | 'oauth-token' | 'wif' | 'api-key' | Claude Code authentication mode. api-key uses Anthropic/Foundry API keys; oauth-token uses a Claude subscription OAuth token; wif uses Anthropic Workload Identity Federation with the anthropic provider and needs claude.wif. Self-hosted only for now: Colony Cloud has no WIF setting |
api_key_env | string | 'ANTHROPIC_API_KEY' | Informational. Names the API key variable so Colony can keep it out of subprocess environments; it does not change which variable the key is read from |
oauth_token_env | string | 'CLAUDE_CODE_OAUTH_TOKEN' | Environment variable containing the OAuth token. Used when auth_mode: oauth-token |
models | ClaudeModelsConfig | — | Per-agent model overrides |
scaling | ClaudeScalingConfig | — | Per-complexity turn limits and model overrides |
ClaudeFoundryConfig
Section titled “ClaudeFoundryConfig”Used by claude.foundry.
| Field | Type | Default | Description |
|---|---|---|---|
resource | string | — | Azure resource name. URL constructed as https://{resource}.services.ai.azure.com/anthropic. Mutually exclusive with base_url |
base_url | string | — | Full Foundry base URL. Mutually exclusive with resource |
api_key_env | string | 'ANTHROPIC_FOUNDRY_API_KEY' | Environment variable holding the Foundry API key |
pin_models.opus | string | — | Pin the Opus deployment name |
pin_models.sonnet | string | — | Pin the Sonnet deployment name |
pin_models.haiku | string | — | Pin the Haiku deployment name |
ClaudeGatewayConfig
Section titled “ClaudeGatewayConfig”Used by claude.gateway. Only used when provider: 'gateway'.
| Field | Type | Default | Description |
|---|---|---|---|
base_url | string | required | Base URL for the gateway |
auth_token_env | string | 'ANTHROPIC_AUTH_TOKEN' | Environment variable holding the gateway auth token. Gateway traffic uses this token rather than ANTHROPIC_API_KEY |
custom_headers | string | — | Custom headers, injected as ANTHROPIC_CUSTOM_HEADERS |
disable_experimental_betas | boolean | — | When true, sets CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1 |
pin_models.opus | string | — | Pin the Opus model identifier |
pin_models.sonnet | string | — | Pin the Sonnet model identifier |
pin_models.haiku | string | — | Pin the Haiku model identifier |
budget_exhausted_match | { status, text }[] | — | Rules for recognizing a gateway budget block. A failed result with that HTTP status (400–599) whose error text contains text (case-insensitive) is treated as gateway_budget rather than a quota pause |
attribution.header | string | — | Header name (letters, digits, hyphens). Setting attribution turns per-request attribution on. In Colony Cloud, attribution is dropped with a warning if it collides with a custom_headers entry |
attribution.format | 'json' | 'headers' | 'json' | json sends one header; headers sends one <header>-<field> header per field |
attribution.fields | ('tenant' | 'repo' | 'issue' | 'station' | 'task')[] | all five | Non-empty, unique subset of attribution fields |
ClaudeModelsConfig
Section titled “ClaudeModelsConfig”Used by claude.models.
| Field | Type | Default | Description |
|---|---|---|---|
developer | string | 'claude-opus-5-5' | Model used for the developer agent |
reviewer | string | 'claude-opus-5-5' | Model used for the reviewer agent |
analyzer | string | 'claude-sonnet-5' | Model used for the analyzer agent |
planner | string | 'claude-opus-5-5' | Model used for the planner agent |
merger | string | 'claude-opus-5-5' | Model used for the merger agent |
conversation | string | 'claude-haiku-4-5' | Model used for conversational replies |
strategist | string | 'claude-opus-5-5' | Model used for the strategist |
ClaudeScalingConfig
Section titled “ClaudeScalingConfig”Used by claude.scaling. A map with keys small, medium, and large, each a ClaudeScalingEntry.
ClaudeScalingEntry
Section titled “ClaudeScalingEntry”| Field | Type | Default (built-in) | Description |
|---|---|---|---|
developer_max_turns | number | 80 / 150 / 250 (small/medium/large) | Maximum Claude turns for a developer invocation at this complexity |
model | string | claude-sonnet-5 (small) / claude-opus-5-5 (medium/large) | Override the model for this complexity level |
effort | 'low' | 'medium' | 'high' | 'max' | high (small/medium) / max (large) | Effort level hint passed to the Claude CLI |
planning_max_turns | number | 500 | Maximum turns for planning sub-tasks at this complexity |
no_progress_window | number | — (75 for large only) | Turns without measurable progress before aborting |
backstop_max_turns | number | 500 | Hard turn ceiling regardless of other limits |
model_routing
Section titled “model_routing”Controls automatic model selection per task type and complexity tier. This is the primary lever for reducing cost on simple issues without sacrificing quality on complex ones.
| Field | Type | Default | Description |
|---|---|---|---|
enabled | boolean | true when the block is present | Master switch. When false, routes are ignored and resolution falls back to claude.models.* |
override | string | — | Global force-model. When set, forces this model for every task regardless of task type, tier, or enabled. Use as a kill-switch to pin all agents to one model temporarily |
routes | map: task → tier → model | — | Per-task-type, per-tier model map (see Routes) |
Routes
Section titled “Routes”Used by model_routing.routes. A two-level map: task type → complexity tier → model string.
Task keys: analyze · develop · review · merge · plan
Tier keys: small · medium · large
Omitted cells fall through to claude.models.<agent>. All fields are optional — only specify the task/tier combinations you want to override.
model_routing: enabled: true routes: analyze: small: claude-sonnet-5 medium: claude-opus-5-5 large: claude-opus-5-5 develop: small: claude-sonnet-5 medium: claude-opus-5-5 large: claude-opus-5-5 review: small: claude-sonnet-5 medium: claude-opus-5-5 large: claude-opus-5-5 merge: small: claude-sonnet-5 medium: claude-opus-5-5 large: claude-opus-5-5 plan: small: claude-opus-5-5 medium: claude-opus-5-5 large: claude-opus-5-5Task-type mapping notes: The sweep internal task maps to the analyze route key; review-external maps to review.
Precedence chain
Section titled “Precedence chain”Model resolution evaluates sources in this order (highest priority first):
override— when set, applies unconditionally regardless ofenabledorroutes- A model declared on the workflow state — beats the route table and the per-role settings
routes[taskType][tier]— whenenabledis notfalseand a matching route entry existsrepos[].claude.models.<agent>— for the analyzer, developer and reviewer in that repositoryclaude.models.<agent>— fallback when routing is absent, disabled, or has no matching entry- Foundry
pin_models— backstop whenclaude.provider: foundry; maps model family names (opus/sonnet/haiku) to deployment identifiers
Interaction with claude.scaling
Section titled “Interaction with claude.scaling”For the developer agent only, claude.scaling[tier].model is a separate per-tier override that sits between routes.develop[tier] and claude.models.developer in the resolution order:
- Routing disabled: developer agent uses
claude.scaling[tier].model→claude.models.developer - Routing enabled:
routes.develop[tier]→claude.scaling[tier].model→claude.models.developer
Routing selects the model; claude.scaling controls per-tier turn budgets independently. The two settings do not conflict — you can set both and they apply to separate dimensions of the invocation.
review
Section titled “review”Controls PR review behavior — deterministic check commands, LLM review rounds, CI gating, and merge policy.
| Field | Type | Default | Description |
|---|---|---|---|
checks | Record<string, string | { command, blocking }> | {} | Named shell commands to run as deterministic review checks (e.g. test: 'npm test'). Use the object form with blocking: false for a check that should not block. blocking defaults to true. Do not leave empty — without checks Colony uses LLM judgment alone |
timeout_per_check | number | 120 | Seconds allowed for each check command before it is killed |
max_review_cycles | number | 5 | Maximum LLM review rounds before Colony stops and escalates |
max_reimplement_cycles | number | 3 | Maximum re-implement cycles after a review rejection |
ci_flaky_reruns | number | 1 | Times a failed CI check run on GitHub is re-run on the same head commit before the reviewer routes the issue back or the merger reports a failure. Separate from flaky_reruns. 0 disables reruns; maximum 5 |
flaky_reruns | number | 1 | Times a failed blocking check is re-run before the baseline step. 0 disables reruns; maximum 5 |
flaky_quarantine_threshold | number | — | When a blocking check’s flake count over the rolling 14-day window reaches this value, it is quarantined (advisory). Must be an integer ≥ 1. No quarantine if unset |
max_diff_lines | number | — | Removed. Reviews now see the whole diff, up to a shared size ceiling. The key is still accepted and ignored. |
auto_merge_on_approval | boolean | false | Automatically merge the PR after the reviewer approves it |
require_ci_pass | boolean | true | Wait for all required CI checks to pass before merging |
ci_check_timeout | number | 300 | Seconds to wait for CI checks to complete |
ci_required_checks | string[] | [] | Names of CI checks that must pass. When empty, all checks must pass |
format_command | string | — | Formatting command to run before review checks (e.g. 'npm run format:fix') |
empty_verdict_auto_approve | boolean | true | Auto-approve when the LLM returns an empty or unparseable verdict and all deterministic checks passed |
external_prs | ExternalPrReviewConfig | mode: off | External PR review settings |
ExternalPrReviewConfig
Section titled “ExternalPrReviewConfig”Used by review.external_prs. Controls how Colony handles PRs not part of its own pipeline.
| Field | Type | Default | Description |
|---|---|---|---|
mode | 'off' | 'on_request' | 'on_ready' | 'auto' | 'off' | When to review external PRs. off — disabled. on_request — only when a human comments /colony:review. on_ready — automatically when a PR is opened or transitions from draft to ready. auto — same as on_ready, with auto_approve flag available |
author_filter | string[] | ['*'] | Allowlist of GitHub usernames to review. ['*'] means any author |
label_filter | string[] | [] | Require all listed labels to be present on the PR before reviewing |
exclude_bots | boolean | true | Skip PRs authored by bot accounts |
exclude_drafts | boolean | true | Skip draft PRs |
auto_approve | boolean | false | Only valid with mode: auto. When true, Colony submits an approving review on external PRs that pass review, except when production files went unreviewed. When false, a passing PR gets a neutral comment |
agents
Section titled “agents”Configures the Colony agent processes.
Engine selection
Section titled “Engine selection”Each of the five executor roles can be independently routed to a different execution engine. This is separate from executors.* (which holds executor-specific tuning like forbidden_paths); agents.<role>.engine controls which CLI runtime is invoked.
| Field | Type | Default | Description |
|---|---|---|---|
agents.analyzer.engine | 'claude-code' | 'codex' | 'claude-code' | Execution engine for the analyzer role |
agents.developer.engine | 'claude-code' | 'codex' | 'claude-code' | Execution engine for the developer role |
agents.reviewer.engine | 'claude-code' | 'codex' | 'claude-code' | Execution engine for the reviewer role |
agents.merger.engine | 'claude-code' | 'codex' | 'claude-code' | Execution engine for the merger role |
agents.planner.engine | 'claude-code' | 'codex' | 'claude-code' | Execution engine for the planner role |
When a role is set to 'codex', the Worker invokes the OpenAI Codex CLI instead of the Claude Code CLI. The codex top-level section (see ## codex) configures the Codex CLI path, timeouts, and per-role model IDs. claude.models.* and claude.scaling do not apply to Codex-engine roles; use codex.models.* for model selection when Codex is active.
Engine selection is read by the Worker on startup and is not hot-reloadable — a Worker redeploy is required after changing any agents.<role>.engine value.
Common AgentConfig Fields
Section titled “Common AgentConfig Fields”All agent types share these base fields:
| Field | Type | Default | Description |
|---|---|---|---|
enabled | boolean | true | Whether the agent runs |
poll_interval | number | 30 | Seconds between poll cycles (minimum 5) |
health_port | number | (per agent) | HTTP health check port |
effort | 'low' | 'medium' | 'high' | 'max' | — | Claude effort level for this agent |
agents.sprint_master
Section titled “agents.sprint_master”| Field | Type | Default | Description |
|---|---|---|---|
| Common fields | health_port: 9100 | See Common AgentConfig Fields | |
intake_mode | 'all' | 'tagged' | 'tagged' | 'all' picks up every new issue automatically; 'tagged' requires the colony:enqueue label |
heartbeat_timeout_minutes | number | 5 | Minutes before reclaiming stale tasks from Workers that stopped heartbeating |
sweep_cooldown_minutes | number | 10 | Minutes to suppress re-enqueueing a sweep task after completion |
label_sync_limit | number | 25 | Max issues to reconcile labels for per poll cycle |
projection_drain_limit | number | 50 | Max queued VCS write projections to drain per poll cycle |
auto_unblock_transient | boolean | true | Automatically unblock issues blocked by transient infrastructure failures |
work_task_retention_days | number | 31 | Days to retain terminal work tasks before pruning |
agents.analyzer
Section titled “agents.analyzer”Uses bare AgentConfig with no additional fields. health_port: 9101.
agents.reviewer
Section titled “agents.reviewer”Uses bare AgentConfig with no additional fields. health_port: 9103.
agents.developer
Section titled “agents.developer”| Field | Type | Default | Description |
|---|---|---|---|
| Common fields | health_port: 9102 | See Common AgentConfig Fields | |
repo_context | RepoContextConfig | — | Controls repository context injection into prompts |
pr_overlap_threshold | number (0–1) | 0.5 | Fraction of plan files overlapping with open PRs to trigger block |
forbidden_paths | string[] | — | Glob patterns the agent may not read or write |
read_only_paths | string[] | — | Glob patterns the agent may read but not write |
RepoContextConfig
Section titled “RepoContextConfig”| Field | Type | Default | Description |
|---|---|---|---|
enabled | boolean | true | Enable repository context injection |
max_tokens | number | 2000 / 4000 / 7000 (small/medium/large) | Maximum tokens for the context payload |
tree_depth | number | 3 / 4 / 5 (small/medium/large) | Depth of the directory tree to include |
Protected Paths
Section titled “Protected Paths”forbidden_paths and read_only_paths restrict which files the developer agent may access or modify. Paths are repo-relative and use minimatch glob syntax with { dot: true }.
forbidden_paths— the agent cannot read or write these paths. Use for secrets and credentials (e.g..env*,secrets/**).read_only_paths— the agent can read but not write these paths. Use for IaC, migrations, and CI workflows (e.g.infrastructure/**,.github/workflows/**).
agents.planner
Section titled “agents.planner”| Field | Type | Default | Description |
|---|---|---|---|
| Common fields | health_port: 9105 | See Common AgentConfig Fields | |
max_turns | number | 200 | Max Claude turns for planning |
model | string | — | Override model for the planner |
agents.merger
Section titled “agents.merger”| Field | Type | Default | Description |
|---|---|---|---|
| Common fields | health_port: 9104 | See Common AgentConfig Fields | |
conflict_resolution | ConflictResolutionConfig | — | Automated merge conflict resolution settings |
ConflictResolutionConfig
Section titled “ConflictResolutionConfig”| Field | Type | Default | Description |
|---|---|---|---|
enabled | boolean | — | Enable automated conflict resolution |
max_conflict_files | number | — | Maximum number of conflicting files to attempt resolution on |
max_conflict_regions | number | — | Maximum number of conflict regions to attempt resolution on |
timeout | number | — | Timeout in seconds for conflict resolution |
model | string | — | Override model for conflict resolution |
auto_merge_high_confidence_resolutions | boolean | — | Automatically merge when conflict resolution has high confidence |
agents.monitor
Section titled “agents.monitor”Pipeline observability, self-healing, and Prometheus metrics. Enabled by default. Colony Cloud does not run this agent and has its own monitoring.
| Field | Type | Default | Description |
|---|---|---|---|
| Common fields | enabled: true, health_port: 9106 | See Common AgentConfig Fields | |
agent_down_timeout | number | 120 | Seconds before alerting that an agent is down |
pipeline_stall_timeout_minutes | number | 60 | Minutes before alerting a pipeline stall |
error_rate_threshold | number (0–1) | 0.5 | Alert if error rate exceeds this fraction |
error_rate_window | number | 30 | Minutes, rolling window for error rate calculation |
cost_alert_threshold | CostAlertThreshold | — | Cost alerting thresholds |
alert_cooldown | number | 30 | Minutes, deduplication window for alerts |
alert_channels | MonitoringAlertChannel[] | [] | Alert delivery channels |
metrics_refresh_minutes | number | 10 | How often to refresh pipeline metrics |
sweep_cooldown_minutes | number | 10 | Minutes to suppress re-enqueueing a sweep task |
agent_health_host | string | 'localhost' | Host for polling agent health endpoints |
auth | MonitorAuth | — | Basic auth for the monitor HTTP API |
self_healing | SelfHealingConfig | (see below) | Self-healing automation settings |
CostAlertThreshold
Section titled “CostAlertThreshold”| Field | Type | Default | Description |
|---|---|---|---|
daily_usd | number | — | Alert when daily cost exceeds this USD amount |
monthly_usd | number | — | Alert when monthly cost exceeds this USD amount |
MonitorAuth
Section titled “MonitorAuth”| Field | Type | Default | Description |
|---|---|---|---|
username | string | required | Username for basic auth |
password_env | string | required | Name of the environment variable containing the password |
MonitoringAlertChannel
Section titled “MonitoringAlertChannel”| Field | Type | Default | Description |
|---|---|---|---|
type | 'github_issue' | 'webhook' | 'slack' | 'pagerduty' | required | Alert channel type |
url | string | — | Endpoint URL for webhook/slack/pagerduty |
url_env | string | — | Name of the environment variable containing the endpoint URL |
routing_key | string | — | PagerDuty integration routing key: the name of an environment variable holding the key, or the key itself |
SelfHealingConfig
Section titled “SelfHealingConfig”| Field | Type | Default | Description |
|---|---|---|---|
max_auto_unblocks_per_issue | number | — | Maximum automatic unblocks per issue before requiring manual intervention |
auto_restart | boolean | false | Enable automatic agent restart on failure |
restart_strategy | 'pid' | 'systemd' | 'pm2' | 'pid' | Process restart mechanism |
restart_cooldown | number | 300 | Seconds between restart attempts |
max_restart_attempts | number | 3 | Maximum restart attempts before giving up |
restart_dry_run | boolean | false | Log restart actions without executing them |
agents.workers
Section titled “agents.workers”Per-repo Worker pool configuration. Workers claim tasks from the Postgres work_tasks queue.
| Field | Type | Default | Description |
|---|---|---|---|
heartbeat_interval | number | 30 | Seconds between task heartbeats |
max_task_retries | number | 3 | Max failures for a repo+issue+taskType combination within 60 minutes before dropping re-enqueue |
Resolution Chain
Section titled “Resolution Chain”When a field can be set both globally and per-repo, Colony resolves the value using this fallback chain:
repoConfig.<field> ?? config.<field> ?? defaultself_improvement
Section titled “self_improvement”| Field | Type | Default | Description |
|---|---|---|---|
enabled | boolean | false | Enable the self-improvement feature |
label | string | 'colony:self-improvement' | GitHub label used to tag self-improvement issues |
cooldown_minutes | number (≥1) | 30 | Minimum minutes between self-improvement issue filings |
calibration
Section titled “calibration”| Field | Type | Default | Description |
|---|---|---|---|
lookback_days | number | 7 | Days of historical issues to consider when calibrating complexity estimates |
executors
Section titled “executors”Executor-specific settings distinct from agent process infrastructure (poll_interval, health_port). If not set, values are auto-populated from the corresponding agents.* fields for backward compatibility.
executors.analyzer
Section titled “executors.analyzer”| Field | Type | Default | Description |
|---|---|---|---|
effort | 'low' | 'medium' | 'high' | 'max' | — | Claude effort level for the analyzer |
max_turns | number | — | Maximum turns for the analyzer’s Claude session |
executors.developer
Section titled “executors.developer”| Field | Type | Default | Description |
|---|---|---|---|
repo_context | RepoContextConfig | — | Repository context injection settings |
pr_overlap_threshold | number (0–1) | 0.5 | Fraction of plan files overlapping with open PRs to trigger block |
max_plan_files | number | — | Override the complexity gate threshold for planned files. Runtime default is floor(maxTurns / 10); set 0 to disable |
auto_decompose_on_exhaustion | boolean | true | Route oversized issues to planner after developer turn-limit exhaustion |
forbidden_paths | string[] | — | Glob patterns the agent may not read or write |
read_only_paths | string[] | — | Glob patterns the agent may read but not write |
self_validation_max_cycles | number (1–10) | 3 | Maximum self-validation repair cycles before escalating to human review |
ci_repair_max_cycles | number (1–10) | 2 | Maximum CI repair cycles before escalating to human review |
executors.reviewer
Section titled “executors.reviewer”| Field | Type | Default | Description |
|---|---|---|---|
effort | 'low' | 'medium' | 'high' | 'max' | — | Claude effort level for the reviewer |
max_turns | number | — | Maximum turns for the reviewer’s Claude session |
executors.planner
Section titled “executors.planner”| Field | Type | Default | Description |
|---|---|---|---|
max_turns | number | — | Maximum turns for the planner’s Claude session |
effort | 'low' | 'medium' | 'high' | 'max' | — | Claude effort level for the planner |
model | string | — | Override the Claude model used by the planner |
executors.merger
Section titled “executors.merger”| Field | Type | Default | Description |
|---|---|---|---|
conflict_resolution | ConflictResolutionConfig | — | LLM-assisted conflict resolution settings |
Configures the OpenAI Codex CLI when any agent role is set to engine: codex. All fields are optional.
| Field | Type | Default | Description |
|---|---|---|---|
timeout | positive integer | 600 | Overall Codex CLI invocation timeout in seconds |
max_retries | non-negative integer | 1 | Number of times to retry a failed Codex invocation |
inactivity_timeout | positive integer | — | Seconds without output before the process is killed |
binary_path | string | codex (looked up on PATH) | Path to the Codex CLI binary. Only set if using a custom binary location |
api_key_env | string | 'OPENAI_API_KEY' | Name of the environment variable holding the OpenAI API key |
models | CodexModelsConfig | — | Per-role Codex model overrides |
CodexModelsConfig
Section titled “CodexModelsConfig”Used by codex.models. Values must be valid OpenAI or Codex model IDs (e.g. codex-1, o4-mini, gpt-4o). An omitted role uses Colony’s default: codex-1 for the developer and o4-mini for every other role.
| Field | Type | Description |
|---|---|---|
developer | string | Model for the developer agent when running on Codex |
reviewer | string | Model for the reviewer agent when running on Codex |
analyzer | string | Model for the analyzer agent when running on Codex |
planner | string | Model for the planner agent when running on Codex |
merger | string | Model for the merger agent when running on Codex |
conversation | string | Model for the Mayor’s replies when running on Codex |
Credential File Convention
Section titled “Credential File Convention”Colony Workers support an optional operator-mounted credential file at /colony/keys/credentials.yaml for authenticating against private package feeds.
Schema
Section titled “Schema”| Field | Type | Required | Description |
|---|---|---|---|
schema | number | required | Schema version. Must be 1 |
credentials.azure_devops.pat | string | required | Azure DevOps Personal Access Token with Packaging read scope |
credentials.azure_devops.organization | string | — | Azure DevOps organization name (informational only) |
credentials.azure_devops.feeds | array | — | List of feed entries |
feeds[].kind | 'npm' | 'nuget' | required | Package manager for this feed |
feeds[].url | string | required | Full registry/feed URL |
feeds[].scope | string | — | npm scope to bind (e.g. "@acme"). For kind: npm only |
Enterprise Networks
Section titled “Enterprise Networks”For networks that perform TLS interception, mount PEM-format root CA certificates as .crt files under /colony/keys/ca-certs/. Files with other extensions are ignored. The entrypoint propagates trust to the system trust store, Node.js (NODE_EXTRA_CA_CERTS), dotnet, and standard CLI tools before starting any agent.
Multi-Repo (Colony Cloud)
Section titled “Multi-Repo (Colony Cloud)”This section documents how repositories and tenants are expressed in the config. Colony Cloud provisions these keys for you; you manage the settings in the web UI, not in YAML. Self-hosted Colony supports a single repository: a config with more than one repository fails at startup unless you set COLONY_MULTI_REPO=true, which is unsupported. Single-repo deployments do not need these sections.
repos[] (RepoConfig)
Section titled “repos[] (RepoConfig)”| Field | Type | Default | Description |
|---|---|---|---|
owner | string | required | GitHub organization or user |
repo | string | required | Repository name |
token_env | string | — | PAT for this repo. Either token_env or app is required |
app | GitHubAppConfig | — | Per-repo GitHub App credentials for the coder identity |
ops_app | GitHubAppConfig | — | Per-repo GitHub App credentials for the ops identity |
ops_token_env | string | — | PAT for the ops identity |
bot_username | string | — | Display name for bot-authored content for this repo |
workspace | RepoWorkspaceConfig | required | Per-repo workspace settings |
review | RepoReviewConfig | — | Per-repo review overrides |
self_improvement | SelfImprovementConfig | — | Per-repo self-improvement override |
intake_mode | 'all' | 'tagged' | — | Overrides global Mayor intake mode for this repo |
pattern_memory | PatternMemoryConfig | — | Per-repo pattern memory settings |
sla | SlaConfig | — | Per-repo SLA thresholds |
workers | WorkerPoolConfig | — | Per-repo Worker pool settings |
dependabot | DependabotConfig | — | Per-repo override of the top-level dependabot settings in self-hosted colony.config.yaml. In Colony Cloud, these are set in the web UI: an organization-wide default in pipeline settings, with a per-repository override under Autonomy › Settings. |
pattern_memory
Section titled “pattern_memory”| Field | Type | Default | Description |
|---|---|---|---|
enabled | boolean | required | Enable pattern memory for this repo |
max_results | number (≥1) | required | Maximum pattern results to include in prompts |
lookback_days | number (≥1) | required | Days of history to search for patterns |
| Field | Type | Default | Description |
|---|---|---|---|
warn_after_minutes | Record<string, number> | — | Map of pipeline state name to warning threshold in minutes |
workers (WorkerPoolConfig)
Section titled “workers (WorkerPoolConfig)”| Field | Type | Default | Description |
|---|---|---|---|
pool_size | number (integer ≥1) | — | Number of Worker processes to run for this repo |
memory | string | — | Container memory limit (e.g. '4g') |
health_port_start | number | — | Starting port for health check endpoint allocation |
dependabot
Section titled “dependabot”| Field | Type | Default | Description |
|---|---|---|---|
auto_review | boolean | false | Automatically trigger a review cycle for Dependabot PRs |
auto_merge_patch | boolean | false | Auto-merge patch updates after deterministic checks pass |
auto_merge_minor | boolean | false | Require LLM review for minor updates before merging |
auto_migrate_breaking | boolean | false | Automatically create migration issues for breaking major updates |
bot_usernames | string[] | ['dependabot[bot]'] | GitHub usernames to treat as Dependabot |
Per-Repo Workspace (RepoWorkspaceConfig)
Section titled “Per-Repo Workspace (RepoWorkspaceConfig)”| Field | Type | Default | Description |
|---|---|---|---|
repo_dir | string | required | Path to the local git clone for this repo |
base_dir | string | required | Base directory for this repo’s worktrees |
branch | string | 'main' | Default branch name for this repo |
setup_command | string | — | Command to run after creating a worktree |
setup_timeout | number | 300 | Seconds to allow the setup command to run |
prebuild_command | string | — | Command to run after setup_command |
review_workspace_base | string | — | Container-local path for ephemeral reviewer worktrees |
skip_pre_push_hook | boolean | — | Pass --no-verify to git push for this repo |
secret_env_vars | string[] | — | Names of environment variables to inject into Worker processes for this repo. On Colony Cloud, set them per repository under Secrets → Repository secrets; only workers in a tenant-wide pool receive them today, not single-repo workers. See Repository secrets |
timeouts | TimeoutsConfig | — | Fine-grained clone and tooling timeouts |
Timeouts (TimeoutsConfig)
Section titled “Timeouts (TimeoutsConfig)”| Field | Type | Default | Description |
|---|---|---|---|
clone | number | 600 | Seconds before git clone is timed out |
mise_install | number | 600 | Seconds before mise install is timed out |
mise_reshim | number | 30 | Seconds before mise reshim is timed out |
submodule_init | number | 120 | Seconds before git submodule update --init is timed out |
Per-Repo Review (RepoReviewConfig)
Section titled “Per-Repo Review (RepoReviewConfig)”The following review fields can be overridden per-repo. Fields not listed here are global-only.
| Field | Type | Description |
|---|---|---|
checks | Record<string, string | { command, blocking }> | Override review check commands for this repo |
timeout_per_check | number | Seconds to allow each check to run |
require_ci_pass | boolean | Require all CI checks to pass before merging |
ci_check_timeout | number | Seconds to wait for CI checks |
ci_required_checks | string[] | Names of CI checks that must pass |
format_command | string | Command to auto-format code before review |
auto_merge_on_approval | boolean | Auto-merge the PR when the reviewer approves |
external_prs | ExternalPrReviewConfig | External PR review settings |
ci_absent_check_grace | number | Seconds auto-merge waits for a required CI check to appear before treating it as absent |
clean_verification | string | Clean-verification command for this repo |
ci_repair | object | CI repair limits and check filters (max_cycles, deny_checks, allow_checks) |
max_review_cycles | number | Maximum LLM review rounds |
flaky_reruns | number | Times a failed blocking check is re-run before the baseline step |
ci_flaky_reruns | number | Times a failed CI check run is re-run on the same head commit |
flaky_quarantine_threshold | number | Flake count at which a blocking check is quarantined |
tenants[] (TenantConfig)
Section titled “tenants[] (TenantConfig)”Groups repositories by tenant. Cannot coexist with top-level repos[].
| Field | Type | Default | Description |
|---|---|---|---|
id | string | required | Unique identifier for this tenant |
name | string | — | Human-readable tenant name |
app | GitHubAppConfig | — | Tenant-level GitHub App credentials for the coder identity |
ops_app | GitHubAppConfig | — | Tenant-level GitHub App credentials for the ops identity |
anthropic_api_key_env | string | — | Environment variable containing the Anthropic API key for this tenant |
cost_budget | object | — | Cost budget settings (monthly_usd: number). This is an enforced monthly ceiling that stops Workers when reached — see Cost & Budget concepts — the three budget controls. |
defaults | object | — | Default settings cascaded to repos in this tenant (currently supports timeouts) |
repos | RepoConfig[] | required | List of repositories belonging to this tenant |
Deprecated Configuration
Section titled “Deprecated Configuration”The following fields are still accepted but will be removed in a future release.
Fields: llm.analyzer_max_turns, llm.reviewer_max_turns, llm.developer_max_turns
Migration: Each field has its own replacement:
llm.analyzer_max_turns→executors.analyzer.max_turnsllm.reviewer_max_turns→executors.reviewer.max_turnsllm.developer_max_turns→claude.scaling.<tier>.developer_max_turns, keyed by complexity (small,medium,large)
# Before (deprecated)llm: analyzer_max_turns: 80 reviewer_max_turns: 300 developer_max_turns: 150
# Afterexecutors: analyzer: max_turns: 80 reviewer: max_turns: 300claude: scaling: medium: developer_max_turns: 150monitoring.*
Section titled “monitoring.*”Migration: Move all fields under agents.monitor. The loader still accepts monitoring: as a top-level key for backward compatibility.
self_improvement.tracks
Section titled “self_improvement.tracks”Migration: Manage tracks via the Colony Cloud dashboard (SI Tracks page), the monitor REST API (POST /api/tracks, self-hosted) or the Colony Cloud API (POST /api/repos/{owner}/{repo}/si-tracks). YAML track definitions are accepted with a deprecation warning and ignored at runtime when a TrackStore is available; colony config migrate removes them.
Removal timeline:
self_improvement.tracksin YAML is scheduled for removal in the next major release. Runcolony config migratenow to clean up your config.