Configuration Schema

This page is the flat reference for every colony.config.yaml field. For a narrative guide that explains when and why to use each section, see Self-Host — Configuration.

Note

This reference tracks the colony submodule. Field descriptions that drift from the submodule’s colony/docs/user-guide/configuration.md should be corrected there — that file is the canonical source.

---

Config File Location

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.

---

Environment Variables

Variable	Required	Description
GITHUB_TOKEN	required	Personal Access Token for GitHub API access
ANTHROPIC_API_KEY	required	Anthropic API key for Claude Code invocations
DATABASE_URL	required	Postgres connection string

---

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

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

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

---

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 default npm install
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

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

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

Top-level scalar. Caps aggregate spend across all issues and repos for the current UTC day.

Field	Type	Default	Description
max_daily_usd	number | null	50	Maximum USD per UTC day. Set to null to disable the ceiling entirely

max_daily_usd is an enforced runtime ceiling. It differs from cost_budget.monthly_usd (tenant-level monthly enforcement) and budget_cap_usd (per-repo reporting target only). See Cost & Budget concepts — the three budget controls.

---

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

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

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

Controls the local event log written by Colony agents.

Field	Type	Default	Description
enabled	boolean	—	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

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

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'	'api-key'	Claude Code authentication mode. api-key uses Anthropic/Foundry API keys; oauth-token uses a Claude subscription OAuth token
api_key_env	string	'ANTHROPIC_API_KEY'	Name of the environment variable holding the Anthropic API key
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

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

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

ClaudeModelsConfig

Used by claude.models.

Field	Type	Default	Description
developer	string	'claude-opus-5'	Model used for the developer agent
reviewer	string	'claude-opus-5'	Model used for the reviewer agent
analyzer	string	'claude-sonnet-4-6'	Model used for the analyzer agent
planner	string	'claude-opus-5'	Model used for the planner agent
merger	string	'claude-sonnet-4-6'	Model used for the merger agent

ClaudeScalingConfig

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

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-4-6 (small) / claude-opus-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

Caution

model_routing is opt-in and disabled by default (enabled: false). Enable it only after reviewing the field descriptions and confirming the routing table matches your cost/quality goals. Setting override applies unconditionally — even when enabled: false.

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	false	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

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-4-6
      medium: claude-sonnet-4-6
      large: claude-sonnet-4-6
    develop:
      small: claude-sonnet-4-6
      medium: claude-opus-4-8
      large: claude-opus-4-8
    review:
      small: claude-sonnet-4-6
      medium: claude-opus-4-8
      large: claude-opus-4-8
    merge:
      small: claude-sonnet-4-6
      medium: claude-sonnet-4-6
      large: claude-sonnet-4-6
    plan:
      small: claude-opus-4-8
      medium: claude-opus-4-8
      large: claude-opus-4-8

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

Precedence chain

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

1. override — when set, applies unconditionally regardless of enabled or routes
2. routes[taskType][tier] — when enabled is not false and a matching route entry exists
3. claude.models.<agent> — fallback when routing is absent, disabled, or has no matching entry
4. Foundry pin_models — backstop when claude.provider: foundry; maps model family names (opus/sonnet/haiku) to deployment identifiers

Note

override is evaluated before the enabled flag. Setting enabled: false disables route lookups but does not disable override. To pause routing without clearing the routes table, set enabled: false and leave override unset.

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

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

Field	Type	Default	Description
checks	Record<string, string>	{}	Named shell commands to run as deterministic review checks (e.g. test: 'npm test'). 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	—	Maximum LLM review rounds before giving up. Unlimited if unset
max_reimplement_cycles	number	—	Maximum re-implement cycles after a review rejection. Unlimited if unset
max_diff_lines	number	3000	Truncate the PR diff at this many lines when sending to the LLM reviewer
rebase_before_check	boolean	true	Rebase the PR branch onto the base branch before running checks
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

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	Reserved for future use — only valid with mode: auto

---

agents

Configures the Colony agent processes.

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

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

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

agents.analyzer

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

agents.reviewer

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

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)	—	Fraction of plan files overlapping with open PRs to trigger block
max_tooling_retries	number	2	Poll-level retries for transient push failures
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

Field	Type	Default	Description
enabled	boolean	—	Enable repository context injection
max_tokens	number	—	Maximum tokens for the context payload
tree_depth	number	—	Depth of the directory tree to include

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

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

Field	Type	Default	Description
Common fields		health_port: 9104	See Common AgentConfig Fields
conflict_resolution	ConflictResolutionConfig	—	Automated merge conflict resolution settings

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

Pipeline observability, self-healing, and Prometheus metrics. Disabled by default.

Field	Type	Default	Description
Common fields		enabled: false, 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

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

Field	Type	Default	Description
username	string	required	Username for basic auth
password_env	string	required	Name of the environment variable containing the password

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 (literal value, not an env var name)

SelfHealingConfig

Field	Type	Default	Description
auto_relabel_orphans	boolean	false	Automatically relabel issues that have fallen out of the state machine
worktree_cleanup_interval_hours	number	6	Hours between worktree cleanup sweeps
auto_unblock_transient	boolean	false	Automatically unblock issues blocked by transient failures
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
work_task_retention_days	number	31	Days to retain completed work tasks before pruning

agents.workers

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

Field	Type	Default	Description
heartbeat_interval	number	—	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

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

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

---

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

Field	Type	Default	Description
lookback_days	number	7	Days of historical issues to consider when calibrating complexity estimates

---

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

Field	Type	Default	Description
effort	'low' | 'medium' | 'high'	—	Claude effort level for the analyzer

executors.developer

Field	Type	Default	Description
repo_context	RepoContextConfig	—	Repository context injection settings
pr_overlap_threshold	number	—	Number of overlapping files with another open PR before blocking development
max_tooling_retries	number	—	Maximum retries for transient tooling errors
effort	'low' | 'medium' | 'high'	—	Claude effort level for the developer
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

Field	Type	Default	Description
effort	'low' | 'medium' | 'high'	—	Claude effort level for the reviewer

executors.planner

Field	Type	Default	Description
max_turns	number	—	Maximum turns for the planner’s Claude session
effort	'low' | 'medium' | 'high'	—	Claude effort level for the planner
model	string	—	Override the Claude model used by the planner

executors.merger

Field	Type	Default	Description
conflict_resolution	ConflictResolutionConfig	—	LLM-assisted conflict resolution settings

---

codex

Note

The codex section is only active when at least one agents.<role>.engine: codex is set. See Engine selection above.

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	—	Overall Codex CLI invocation timeout in seconds
max_retries	non-negative integer	—	Number of times to retry a failed Codex invocation
inactivity_timeout	positive integer	—	Seconds without output before the process is killed
binary_path	string	/usr/local/bin/codex	Absolute path to the Codex CLI binary on the managed Worker. 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

Used by codex.models. Values must be valid OpenAI or Codex model IDs (e.g. codex-1, o4-mini, gpt-4o). Omitting a role passes no --model flag to the Codex CLI, using its built-in default.

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

Caution

codex.models.* values are OpenAI model IDs, not Anthropic model IDs. claude.models.* and claude.scaling apply only to Claude Code-engine roles and are ignored for Codex-engine roles. Configure both sections independently when mixing engines.

---

Credential File Convention

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

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

For networks that perform TLS interception, mount PEM-format root CA certificates under /colony/keys/ca-certs/. 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)

For multi-repo and multi-tenant deployments. Single-repo deployments do not need these sections.

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
budget_cap_usd	number	—	Per-repo reporting budget cap in USD. Summed across repos to produce the aggregate monthly limit used for burn-rate and projected-exhaustion reporting. This is a reporting target, not a runtime enforcement gate — see Cost & Budget concepts — the three budget controls.
dependabot	DependabotConfig	—	Per-repo Dependabot integration settings

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

sla

Field	Type	Default	Description
warn_after_minutes	Record<string, number>	—	Map of pipeline state name to warning threshold in minutes

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

Field	Type	Default	Description
auto_review	boolean	—	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)

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
timeouts	TimeoutsConfig	—	Fine-grained clone and tooling timeouts

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)

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

Field	Type	Description
checks	Record<string, string>	Override review check commands for this repo
timeout_per_check	number	Seconds to allow each check to run
rebase_before_check	boolean	Rebase before running checks
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

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

The following fields are still accepted but will be removed in a future release.

llm.*

Fields: llm.analyzer_max_turns, llm.reviewer_max_turns, llm.developer_max_turns

Migration: Use claude.scaling instead.

monitoring.*

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

self_improvement.tracks

Migration: Manage tracks via the Colony Cloud dashboard or the monitor REST API (POST /api/si/tracks). YAML track definitions in the config file are ignored.