Skip to content

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.


Colony loads config from the first location found:

  1. Path passed via the --config CLI flag
  2. ./colony.config.yaml (current working directory)
  3. ~/.colony/config.yaml (user home directory)

Call resolveConfig() before any GitHub operations. It validates the config and resolves credentials from environment variables.


VariableRequiredDescription
GITHUB_TOKEN (or the variable named by github.token_env)Required unless github.app is configuredPersonal Access Token for GitHub API access. Only needed for PAT auth
ANTHROPIC_API_KEYRequired with the default anthropic provider and api-key auth modeAnthropic 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: codexOpenAI API key for Codex invocations; see codex
DATABASE_URL (or the variable named by database.url_env)requiredPostgres connection string, read via database.url_env

Authentication and identity settings for the target repository.

FieldTypeDefaultDescription
ownerstringrequiredGitHub organization or user that owns the target repository
repostringrequiredTarget repository name
token_envstring'GITHUB_TOKEN'Name of the environment variable containing the Personal Access Token
appGitHubAppConfig—GitHub App credentials for the coder identity (Analyzer, Developer). Use instead of token_env for App-based auth
ops_appGitHubAppConfig—Separate GitHub App credentials for the ops identity (Mayor, Reviewer, Merger)
ops_token_envstring—Name of the environment variable containing the PAT for the ops identity
bot_usernamestring—Display name shown for bot-authored comments and labels

Used by github.app and github.ops_app.

FieldTypeDefaultDescription
app_idnumberrequiredGitHub App ID (found in the App settings page)
private_key_pathstringrequiredPath to the .pem private key file for this App
installation_idnumberrequiredInstallation ID for this App on the target organization or repo

FieldTypeDefaultDescription
prefixstring'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

Controls operator slash commands posted as issue comments.

FieldTypeDefaultDescription
rootstring'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

Controls how Colony creates and manages git worktrees for each issue.

FieldTypeDefaultDescription
repo_dirstring'.'Path to the local git clone of the target repository. Not required for Docker Compose deployments — Workers clone automatically
base_dirstring'~/.colony/workspaces/{owner}/{repo}'Base directory for worktrees. Supports {owner} and {repo} template tokens
branchstring'main'Default branch name. Override when the repo’s default branch is not main
setup_commandstring—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_timeoutnumber300Seconds to allow the setup command to run before timing out
prebuild_commandstring—Command to run after setup_command to pre-build workspace packages
cleanup_after_mergebooleantrueRemove the worktree after a PR is merged
prune_blocked_after_daysnumber7Days before worktrees for blocked issues are automatically pruned
review_workspace_basestring—Container-local path for ephemeral reviewer worktrees
skip_pre_push_hookboolean—When true, passes --no-verify to git push

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.

FieldTypeDefaultDescription
url_envstring'DATABASE_URL'Name of the environment variable containing the Postgres connection string
max_connectionsnumber10Maximum connections in the pg connection pool
idle_timeoutnumber10000idleTimeoutMillis for the pg pool (milliseconds)
sslbooleanfalseEnable SSL for Postgres connections. Required for most cloud-hosted Postgres instances

FieldTypeDefaultDescription
levelstring'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

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.

FieldTypeDefaultDescription
max_daily_usdnumber50Maximum USD per UTC day
budget_headroom_pctnumber (0–100)10Percentage 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_usd is 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_pct lowers 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.


FieldTypeDefaultDescription
enabledbooleantrueWhen false, no disclosure footer is appended. Disabling weakens EU AI Act Article 50(1) compliance — only disable after legal review
textstring'Orchestrated by [Colony](https://runcolony.com) — autonomous software development pipeline.'Disclosure text appended after a horizontal rule

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.

FieldTypeDefaultDescription
enabledbooleanfalseWhen true, Colony automatically promotes intelligence candidates that meet the confidence and observation thresholds
confidence_thresholdnumber (0–1)0.8Minimum confidence score a candidate must reach before auto-promotion. Raise to require stronger evidence; lower to promote sooner
min_observation_countpositive integer2Minimum 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

Controls the local event log written by Colony agents.

FieldTypeDefaultDescription
enabledbooleantrueEnable or disable event logging
dirstring'~/.colony/events'Directory where event log files are written
retention_daysnumber30Days to retain event log files before pruning

Configures the webhook receiver that listens for incoming GitHub webhook events. Omit if not running the webhook receiver.

FieldTypeDefaultDescription
enabledbooleanrequiredEnable the webhook receiver
portnumber (1–65535)requiredPort for the webhook receiver HTTP server
secret_envstring—Name of the environment variable containing the HMAC secret for verifying GitHub webhook payloads

Controls Claude CLI invocation behavior and model selection for all agents.

FieldTypeDefaultDescription
timeoutnumber1800Overall Claude CLI invocation timeout in seconds
max_retriesnumber1Number of times to retry a failed Claude invocation
inactivity_timeoutnumber300Seconds without output before the process is killed with SIGKILL
max_cost_per_issuenumber—USD cost cap per issue. When reached, the issue moves to failure-blocked. Omit for no limit
binary_pathstring'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)
foundryClaudeFoundryConfig—Azure Foundry settings. Only used when provider: 'foundry'
gatewayClaudeGatewayConfig—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_envstring'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_envstring'CLAUDE_CODE_OAUTH_TOKEN'Environment variable containing the OAuth token. Used when auth_mode: oauth-token
modelsClaudeModelsConfig—Per-agent model overrides
scalingClaudeScalingConfig—Per-complexity turn limits and model overrides

Used by claude.foundry.

FieldTypeDefaultDescription
resourcestring—Azure resource name. URL constructed as https://{resource}.services.ai.azure.com/anthropic. Mutually exclusive with base_url
base_urlstring—Full Foundry base URL. Mutually exclusive with resource
api_key_envstring'ANTHROPIC_FOUNDRY_API_KEY'Environment variable holding the Foundry API key
pin_models.opusstring—Pin the Opus deployment name
pin_models.sonnetstring—Pin the Sonnet deployment name
pin_models.haikustring—Pin the Haiku deployment name

Used by claude.gateway. Only used when provider: 'gateway'.

FieldTypeDefaultDescription
base_urlstringrequiredBase URL for the gateway
auth_token_envstring'ANTHROPIC_AUTH_TOKEN'Environment variable holding the gateway auth token. Gateway traffic uses this token rather than ANTHROPIC_API_KEY
custom_headersstring—Custom headers, injected as ANTHROPIC_CUSTOM_HEADERS
disable_experimental_betasboolean—When true, sets CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1
pin_models.opusstring—Pin the Opus model identifier
pin_models.sonnetstring—Pin the Sonnet model identifier
pin_models.haikustring—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.headerstring—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 fiveNon-empty, unique subset of attribution fields

Used by claude.models.

FieldTypeDefaultDescription
developerstring'claude-opus-5-5'Model used for the developer agent
reviewerstring'claude-opus-5-5'Model used for the reviewer agent
analyzerstring'claude-sonnet-5'Model used for the analyzer agent
plannerstring'claude-opus-5-5'Model used for the planner agent
mergerstring'claude-opus-5-5'Model used for the merger agent
conversationstring'claude-haiku-4-5'Model used for conversational replies
strategiststring'claude-opus-5-5'Model used for the strategist

Used by claude.scaling. A map with keys small, medium, and large, each a ClaudeScalingEntry.

FieldTypeDefault (built-in)Description
developer_max_turnsnumber80 / 150 / 250 (small/medium/large)Maximum Claude turns for a developer invocation at this complexity
modelstringclaude-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_turnsnumber500Maximum turns for planning sub-tasks at this complexity
no_progress_windownumber— (75 for large only)Turns without measurable progress before aborting
backstop_max_turnsnumber500Hard turn ceiling regardless of other limits

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.

FieldTypeDefaultDescription
enabledbooleantrue when the block is presentMaster switch. When false, routes are ignored and resolution falls back to claude.models.*
overridestring—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
routesmap: task → tier → model—Per-task-type, per-tier model map (see 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-5

Task-type mapping notes: The sweep internal task maps to the analyze route key; review-external maps to review.

Model resolution evaluates sources in this order (highest priority first):

  1. override — when set, applies unconditionally regardless of enabled or routes
  2. A model declared on the workflow state — beats the route table and the per-role settings
  3. routes[taskType][tier] — when enabled is not false and a matching route entry exists
  4. repos[].claude.models.<agent> — for the analyzer, developer and reviewer in that repository
  5. claude.models.<agent> — fallback when routing is absent, disabled, or has no matching entry
  6. Foundry pin_models — backstop when claude.provider: foundry; maps model family names (opus/sonnet/haiku) to deployment identifiers

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.


Controls PR review behavior — deterministic check commands, LLM review rounds, CI gating, and merge policy.

FieldTypeDefaultDescription
checksRecord<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_checknumber120Seconds allowed for each check command before it is killed
max_review_cyclesnumber5Maximum LLM review rounds before Colony stops and escalates
max_reimplement_cyclesnumber3Maximum re-implement cycles after a review rejection
ci_flaky_rerunsnumber1Times 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_rerunsnumber1Times a failed blocking check is re-run before the baseline step. 0 disables reruns; maximum 5
flaky_quarantine_thresholdnumber—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_linesnumber—Removed. Reviews now see the whole diff, up to a shared size ceiling. The key is still accepted and ignored.
auto_merge_on_approvalbooleanfalseAutomatically merge the PR after the reviewer approves it
require_ci_passbooleantrueWait for all required CI checks to pass before merging
ci_check_timeoutnumber300Seconds to wait for CI checks to complete
ci_required_checksstring[][]Names of CI checks that must pass. When empty, all checks must pass
format_commandstring—Formatting command to run before review checks (e.g. 'npm run format:fix')
empty_verdict_auto_approvebooleantrueAuto-approve when the LLM returns an empty or unparseable verdict and all deterministic checks passed
external_prsExternalPrReviewConfigmode: offExternal PR review settings

Used by review.external_prs. Controls how Colony handles PRs not part of its own pipeline.

FieldTypeDefaultDescription
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_filterstring[]['*']Allowlist of GitHub usernames to review. ['*'] means any author
label_filterstring[][]Require all listed labels to be present on the PR before reviewing
exclude_botsbooleantrueSkip PRs authored by bot accounts
exclude_draftsbooleantrueSkip draft PRs
auto_approvebooleanfalseOnly 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

Configures the Colony agent processes.

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.

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

All agent types share these base fields:

FieldTypeDefaultDescription
enabledbooleantrueWhether the agent runs
poll_intervalnumber30Seconds between poll cycles (minimum 5)
health_portnumber(per agent)HTTP health check port
effort'low' | 'medium' | 'high' | 'max'—Claude effort level for this agent
FieldTypeDefaultDescription
Common fieldshealth_port: 9100See Common AgentConfig Fields
intake_mode'all' | 'tagged''tagged''all' picks up every new issue automatically; 'tagged' requires the colony:enqueue label
heartbeat_timeout_minutesnumber5Minutes before reclaiming stale tasks from Workers that stopped heartbeating
sweep_cooldown_minutesnumber10Minutes to suppress re-enqueueing a sweep task after completion
label_sync_limitnumber25Max issues to reconcile labels for per poll cycle
projection_drain_limitnumber50Max queued VCS write projections to drain per poll cycle
auto_unblock_transientbooleantrueAutomatically unblock issues blocked by transient infrastructure failures
work_task_retention_daysnumber31Days to retain terminal work tasks before pruning

Uses bare AgentConfig with no additional fields. health_port: 9101.

Uses bare AgentConfig with no additional fields. health_port: 9103.

FieldTypeDefaultDescription
Common fieldshealth_port: 9102See Common AgentConfig Fields
repo_contextRepoContextConfig—Controls repository context injection into prompts
pr_overlap_thresholdnumber (0–1)0.5Fraction of plan files overlapping with open PRs to trigger block
forbidden_pathsstring[]—Glob patterns the agent may not read or write
read_only_pathsstring[]—Glob patterns the agent may read but not write
FieldTypeDefaultDescription
enabledbooleantrueEnable repository context injection
max_tokensnumber2000 / 4000 / 7000 (small/medium/large)Maximum tokens for the context payload
tree_depthnumber3 / 4 / 5 (small/medium/large)Depth of the directory tree to include

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/**).
FieldTypeDefaultDescription
Common fieldshealth_port: 9105See Common AgentConfig Fields
max_turnsnumber200Max Claude turns for planning
modelstring—Override model for the planner
FieldTypeDefaultDescription
Common fieldshealth_port: 9104See Common AgentConfig Fields
conflict_resolutionConflictResolutionConfig—Automated merge conflict resolution settings
FieldTypeDefaultDescription
enabledboolean—Enable automated conflict resolution
max_conflict_filesnumber—Maximum number of conflicting files to attempt resolution on
max_conflict_regionsnumber—Maximum number of conflict regions to attempt resolution on
timeoutnumber—Timeout in seconds for conflict resolution
modelstring—Override model for conflict resolution
auto_merge_high_confidence_resolutionsboolean—Automatically merge when conflict resolution has high confidence

Pipeline observability, self-healing, and Prometheus metrics. Enabled by default. Colony Cloud does not run this agent and has its own monitoring.

FieldTypeDefaultDescription
Common fieldsenabled: true, health_port: 9106See Common AgentConfig Fields
agent_down_timeoutnumber120Seconds before alerting that an agent is down
pipeline_stall_timeout_minutesnumber60Minutes before alerting a pipeline stall
error_rate_thresholdnumber (0–1)0.5Alert if error rate exceeds this fraction
error_rate_windownumber30Minutes, rolling window for error rate calculation
cost_alert_thresholdCostAlertThreshold—Cost alerting thresholds
alert_cooldownnumber30Minutes, deduplication window for alerts
alert_channelsMonitoringAlertChannel[][]Alert delivery channels
metrics_refresh_minutesnumber10How often to refresh pipeline metrics
sweep_cooldown_minutesnumber10Minutes to suppress re-enqueueing a sweep task
agent_health_hoststring'localhost'Host for polling agent health endpoints
authMonitorAuth—Basic auth for the monitor HTTP API
self_healingSelfHealingConfig(see below)Self-healing automation settings
FieldTypeDefaultDescription
daily_usdnumber—Alert when daily cost exceeds this USD amount
monthly_usdnumber—Alert when monthly cost exceeds this USD amount
FieldTypeDefaultDescription
usernamestringrequiredUsername for basic auth
password_envstringrequiredName of the environment variable containing the password
FieldTypeDefaultDescription
type'github_issue' | 'webhook' | 'slack' | 'pagerduty'requiredAlert channel type
urlstring—Endpoint URL for webhook/slack/pagerduty
url_envstring—Name of the environment variable containing the endpoint URL
routing_keystring—PagerDuty integration routing key: the name of an environment variable holding the key, or the key itself
FieldTypeDefaultDescription
max_auto_unblocks_per_issuenumber—Maximum automatic unblocks per issue before requiring manual intervention
auto_restartbooleanfalseEnable automatic agent restart on failure
restart_strategy'pid' | 'systemd' | 'pm2''pid'Process restart mechanism
restart_cooldownnumber300Seconds between restart attempts
max_restart_attemptsnumber3Maximum restart attempts before giving up
restart_dry_runbooleanfalseLog restart actions without executing them

Per-repo Worker pool configuration. Workers claim tasks from the Postgres work_tasks queue.

FieldTypeDefaultDescription
heartbeat_intervalnumber30Seconds between task heartbeats
max_task_retriesnumber3Max failures for a repo+issue+taskType combination within 60 minutes before dropping re-enqueue

When a field can be set both globally and per-repo, Colony resolves the value using this fallback chain:

repoConfig.<field> ?? config.<field> ?? default

FieldTypeDefaultDescription
enabledbooleanfalseEnable the self-improvement feature
labelstring'colony:self-improvement'GitHub label used to tag self-improvement issues
cooldown_minutesnumber (≥1)30Minimum minutes between self-improvement issue filings

FieldTypeDefaultDescription
lookback_daysnumber7Days of historical issues to consider when calibrating complexity estimates

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.

FieldTypeDefaultDescription
effort'low' | 'medium' | 'high' | 'max'—Claude effort level for the analyzer
max_turnsnumber—Maximum turns for the analyzer’s Claude session
FieldTypeDefaultDescription
repo_contextRepoContextConfig—Repository context injection settings
pr_overlap_thresholdnumber (0–1)0.5Fraction of plan files overlapping with open PRs to trigger block
max_plan_filesnumber—Override the complexity gate threshold for planned files. Runtime default is floor(maxTurns / 10); set 0 to disable
auto_decompose_on_exhaustionbooleantrueRoute oversized issues to planner after developer turn-limit exhaustion
forbidden_pathsstring[]—Glob patterns the agent may not read or write
read_only_pathsstring[]—Glob patterns the agent may read but not write
self_validation_max_cyclesnumber (1–10)3Maximum self-validation repair cycles before escalating to human review
ci_repair_max_cyclesnumber (1–10)2Maximum CI repair cycles before escalating to human review
FieldTypeDefaultDescription
effort'low' | 'medium' | 'high' | 'max'—Claude effort level for the reviewer
max_turnsnumber—Maximum turns for the reviewer’s Claude session
FieldTypeDefaultDescription
max_turnsnumber—Maximum turns for the planner’s Claude session
effort'low' | 'medium' | 'high' | 'max'—Claude effort level for the planner
modelstring—Override the Claude model used by the planner
FieldTypeDefaultDescription
conflict_resolutionConflictResolutionConfig—LLM-assisted conflict resolution settings

Configures the OpenAI Codex CLI when any agent role is set to engine: codex. All fields are optional.

FieldTypeDefaultDescription
timeoutpositive integer600Overall Codex CLI invocation timeout in seconds
max_retriesnon-negative integer1Number of times to retry a failed Codex invocation
inactivity_timeoutpositive integer—Seconds without output before the process is killed
binary_pathstringcodex (looked up on PATH)Path to the Codex CLI binary. Only set if using a custom binary location
api_key_envstring'OPENAI_API_KEY'Name of the environment variable holding the OpenAI API key
modelsCodexModelsConfig—Per-role Codex model overrides

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.

FieldTypeDescription
developerstringModel for the developer agent when running on Codex
reviewerstringModel for the reviewer agent when running on Codex
analyzerstringModel for the analyzer agent when running on Codex
plannerstringModel for the planner agent when running on Codex
mergerstringModel for the merger agent when running on Codex
conversationstringModel for the Mayor’s replies when running on Codex

Colony Workers support an optional operator-mounted credential file at /colony/keys/credentials.yaml for authenticating against private package feeds.

FieldTypeRequiredDescription
schemanumberrequiredSchema version. Must be 1
credentials.azure_devops.patstringrequiredAzure DevOps Personal Access Token with Packaging read scope
credentials.azure_devops.organizationstring—Azure DevOps organization name (informational only)
credentials.azure_devops.feedsarray—List of feed entries
feeds[].kind'npm' | 'nuget'requiredPackage manager for this feed
feeds[].urlstringrequiredFull registry/feed URL
feeds[].scopestring—npm scope to bind (e.g. "@acme"). For kind: npm only

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.


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.

FieldTypeDefaultDescription
ownerstringrequiredGitHub organization or user
repostringrequiredRepository name
token_envstring—PAT for this repo. Either token_env or app is required
appGitHubAppConfig—Per-repo GitHub App credentials for the coder identity
ops_appGitHubAppConfig—Per-repo GitHub App credentials for the ops identity
ops_token_envstring—PAT for the ops identity
bot_usernamestring—Display name for bot-authored content for this repo
workspaceRepoWorkspaceConfigrequiredPer-repo workspace settings
reviewRepoReviewConfig—Per-repo review overrides
self_improvementSelfImprovementConfig—Per-repo self-improvement override
intake_mode'all' | 'tagged'—Overrides global Mayor intake mode for this repo
pattern_memoryPatternMemoryConfig—Per-repo pattern memory settings
slaSlaConfig—Per-repo SLA thresholds
workersWorkerPoolConfig—Per-repo Worker pool settings
dependabotDependabotConfig—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.
FieldTypeDefaultDescription
enabledbooleanrequiredEnable pattern memory for this repo
max_resultsnumber (≥1)requiredMaximum pattern results to include in prompts
lookback_daysnumber (≥1)requiredDays of history to search for patterns
FieldTypeDefaultDescription
warn_after_minutesRecord<string, number>—Map of pipeline state name to warning threshold in minutes
FieldTypeDefaultDescription
pool_sizenumber (integer ≥1)—Number of Worker processes to run for this repo
memorystring—Container memory limit (e.g. '4g')
health_port_startnumber—Starting port for health check endpoint allocation
FieldTypeDefaultDescription
auto_reviewbooleanfalseAutomatically trigger a review cycle for Dependabot PRs
auto_merge_patchbooleanfalseAuto-merge patch updates after deterministic checks pass
auto_merge_minorbooleanfalseRequire LLM review for minor updates before merging
auto_migrate_breakingbooleanfalseAutomatically create migration issues for breaking major updates
bot_usernamesstring[]['dependabot[bot]']GitHub usernames to treat as Dependabot
FieldTypeDefaultDescription
repo_dirstringrequiredPath to the local git clone for this repo
base_dirstringrequiredBase directory for this repo’s worktrees
branchstring'main'Default branch name for this repo
setup_commandstring—Command to run after creating a worktree
setup_timeoutnumber300Seconds to allow the setup command to run
prebuild_commandstring—Command to run after setup_command
review_workspace_basestring—Container-local path for ephemeral reviewer worktrees
skip_pre_push_hookboolean—Pass --no-verify to git push for this repo
secret_env_varsstring[]—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
timeoutsTimeoutsConfig—Fine-grained clone and tooling timeouts
FieldTypeDefaultDescription
clonenumber600Seconds before git clone is timed out
mise_installnumber600Seconds before mise install is timed out
mise_reshimnumber30Seconds before mise reshim is timed out
submodule_initnumber120Seconds before git submodule update --init is timed out

The following review fields can be overridden per-repo. Fields not listed here are global-only.

FieldTypeDescription
checksRecord<string, string | { command, blocking }>Override review check commands for this repo
timeout_per_checknumberSeconds to allow each check to run
require_ci_passbooleanRequire all CI checks to pass before merging
ci_check_timeoutnumberSeconds to wait for CI checks
ci_required_checksstring[]Names of CI checks that must pass
format_commandstringCommand to auto-format code before review
auto_merge_on_approvalbooleanAuto-merge the PR when the reviewer approves
external_prsExternalPrReviewConfigExternal PR review settings
ci_absent_check_gracenumberSeconds auto-merge waits for a required CI check to appear before treating it as absent
clean_verificationstringClean-verification command for this repo
ci_repairobjectCI repair limits and check filters (max_cycles, deny_checks, allow_checks)
max_review_cyclesnumberMaximum LLM review rounds
flaky_rerunsnumberTimes a failed blocking check is re-run before the baseline step
ci_flaky_rerunsnumberTimes a failed CI check run is re-run on the same head commit
flaky_quarantine_thresholdnumberFlake count at which a blocking check is quarantined

Groups repositories by tenant. Cannot coexist with top-level repos[].

FieldTypeDefaultDescription
idstringrequiredUnique identifier for this tenant
namestring—Human-readable tenant name
appGitHubAppConfig—Tenant-level GitHub App credentials for the coder identity
ops_appGitHubAppConfig—Tenant-level GitHub App credentials for the ops identity
anthropic_api_key_envstring—Environment variable containing the Anthropic API key for this tenant
cost_budgetobject—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.
defaultsobject—Default settings cascaded to repos in this tenant (currently supports timeouts)
reposRepoConfig[]requiredList of repositories belonging to this tenant

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_turns
  • llm.reviewer_max_turns → executors.reviewer.max_turns
  • llm.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
# After
executors:
analyzer:
max_turns: 80
reviewer:
max_turns: 300
claude:
scaling:
medium:
developer_max_turns: 150

Migration: Move all fields under agents.monitor. The loader still accepts monitoring: as a top-level key for backward compatibility.

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.tracks in YAML is scheduled for removal in the next major release. Run colony config migrate now to clean up your config.