This document is the Colony configuration reference. It covers global infrastructure sections, agent configuration, and the config resolution chain. For multi-repo and multi-tenant configuration (Colony Cloud), see the Multi-Repo (Colony Cloud) section at the bottom.
Colony uses YAML configuration files. The config is loaded from the first location found in this order:
Path passed via the --config CLI flag
./colony.config.yaml (current working directory)
~/.colony/config.yaml (user home directory)
If no config file is found, Colony exits with No colony.config.yaml found. Searched: followed by the absolute paths of the two default locations. A --config path that doesn’t exist fails with Config file not found: <path> and is never followed by a search of the defaults. Once a config file is found and loaded, omitted fields use built-in defaults where available.
Colony ships a machine-readable JSON Schema for colony.config.yaml at schema/colony.config.schema.json in the repository root. The schema uses the Draft 2020-12 dialect and is identified by:
The $id URL is the schema’s canonical version identifier — there is no separate version field. When Colony releases a new schema version, the $id changes.
Note: The schema is generated with additionalProperties: true at the root level, which means unknown top-level keys are not flagged as errors. This keeps the schema forward-compatible with config files written against older Colony versions. Typos in key names will not produce schema validation errors — use colony check --stage config for semantic validation.
Most YAML editors (VS Code with the YAML extension, JetBrains IDEs, Neovim with yaml-language-server) honour the yaml-language-server modeline. The canonical header uses the hosted schema URL and works from any config file location (~/.colony/config.yaml, a target repo, or anywhere else):
This header is already included as the first line of colony.config.example.yaml and in configs generated by colony init --generate, so if you started from either of those you do not need to add it manually.
In-repo alternative: if your config is committed alongside the Colony repository’s schema/ directory, you can use a relative path instead:
Use colony check --stage config to run semantic validation on your config file. This performs the same checks that Colony runs at startup — credential resolution, required-field presence, and value-range enforcement — and reports actionable errors with field paths.
The schema marks some fields as required that Colony’s runtime fills in automatically from built-in defaults when the parent block is omitted entirely. The schema reflects what is structurally required if you provide the parent block, not what you must write in every config file.
Worked example: claude.scaling.*.developer_max_turns
In ClaudeScalingEntry, developer_max_turns is the only required field — model, effort, planning_max_turns, no_progress_window, and backstop_max_turns are all optional:
# OK — claude.scaling is omitted entirely; Colony substitutes DEFAULT_SCALING for all three tiers
# (no claude.scaling block needed)
# OK — partial entry; only developer_max_turns is required per tier
claude:
scaling:
small:
developer_max_turns: 100
medium:
developer_max_turns: 200
large:
developer_max_turns: 300
However, ClaudeScalingConfig itself requires all three tier keys (small, medium, large) once you provide the claude.scaling block at all. Providing only small is a schema error:
# ERROR — claude.scaling is present but missing medium and large
claude:
scaling:
small:
developer_max_turns: 100
# medium and large are required once claude.scaling is set
The general rule: omit a block entirely to get Colony’s defaults for the whole block; provide it to take full ownership of that block’s required fields. See ClaudeScalingEntry for the full field table and built-in defaults per tier.
After changing config types in packages/core/src/config-types.ts, regenerate the schema artifact by running:
Terminal window
npmrungenerate:schema
This invokes scripts/generate-schema.mjs and overwrites schema/colony.config.schema.json. Commit the updated schema alongside the type change so the artifact stays in sync with the types.
Call resolveConfig() before any GitHub operations. This function validates the config and resolves credentials from environment variables — reading GITHUB_TOKEN (or the value of token_env) into github.token, reading GitHub App private keys from disk, and resolving per-repo secrets.
Never use the raw parsed config object directly for GitHub operations; always go through resolveConfig().
Fields you must set to get Colony running on a single repository. Copy the snippet below, fill in the placeholders, then move to Tier 2 to tune cost and model settings.
Path to the local git clone of the target repository. Colony creates worktrees under this directory. Not required for Docker Compose deployments — workers clone the repo automatically inside their container
For all workspace settings (base directory, setup command, branch, cleanup, etc.), see the full workspace reference in Tier 3.
Warning: Leaving review.checks empty means Colony uses LLM judgement alone — no build, test, or lint validation. The LLM reviewer may approve PRs that break your build or fail your test suite. Always configure at least one check.
Named shell commands to run as deterministic review checks (e.g. test: 'npm test', lint: 'npm run lint'). Keys are check names; a value is either a bare shell command (blocking) or { command, blocking? }
Example:
review:
checks:
test: npm test
lint: npm run lint
build: npm run build
A check declared with the object form and blocking: false runs like any other check, but its
failure is reported (a report-only comment, a status line, and an agent_findings record) and
never gates the review, the developer’s self-checks, or the merger. This lets a new rule roll out
in observe-only mode before it starts blocking PRs:
review:
checks:
build: npm run build# blocking (unchanged) — a bare string always means blocking: true
lint:
command: npm run lint
blocking: false# report-only while the team fixes existing lint debt
For all review settings (CI gating, auto-merge, LLM review rounds, etc.), see the full review reference in Tier 3.
Settings most users want to tune after their first issue. The essentials already got Colony running — these fields control cost, quality, and workflow preferences.
A top-level scalar field that caps each tenant’s spend since UTC midnight. It is compared against that tenant’s spend, not summed across all tenants, and the halt trips at the effective cap (after budget_headroom_pct).
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 — up to (pool_size − 1) in-flight tasks may complete past the cap. Use budget_headroom_pct (default 10%) to lower the effective ceiling and absorb this overage.
Cost snapshot staleness: the sprint-master evaluates max_daily_usd, the tenant monthly budget and per-repo budget caps against one per-tenant cost snapshot shared by all of that tenant’s repos and refreshed at most once per 30 seconds (or once per agents.sprint_master.poll_interval, if shorter), and again at UTC-day and budget-month rollover. A gate can therefore act on a spend figure up to one refresh interval old. If a refresh fails, each check behaves as it does when its own cost read fails. The worker’s claim-time checks are unaffected.
Field
Type
Default
Description
max_daily_usd
number
50
Maximum USD a tenant may spend in a single UTC day (its spend since UTC midnight; not across all tenants). The halt compares against the effective cap after headroom. When the ceiling is hit, Colony logs a warning and skips repo polling for the rest of the day — issues already running are not interrupted, but no new work is started. Resets at midnight UTC. The default config enables this ceiling; do not set this field to null.
budget_headroom_pct
number
10
Percentage of max_daily_usd reserved as headroom to absorb concurrent-worker overage (0–100). The effective ceiling is max_daily_usd × (1 − budget_headroom_pct / 100). Set to 0 to disable headroom and restore the exact max_daily_usd value as the ceiling. Increase for high pool_size deployments where more tasks may be in flight simultaneously.
daily_ceiling_comment
boolean
false
When true, a halt on the daily cost ceiling also posts one bot comment per UTC day on the most recently updated open item, stating the spend and the effective cap. Off by default; the daily_cost_ceiling alert is the primary signal. The alert reads persisted spend only, while the worker halt also counts cost it has not yet written. If cost-event writes lag or fail, a worker can halt before the alert fires; the worker’s Tenant daily cost ceiling exceeded warning log is then the only signal. Hot-reloadable.
Example — raise the ceiling to $200 with 5% headroom (effective cap $190):
max_daily_usd: 200
budget_headroom_pct: 5
Example — disable headroom (exact cap, prior behavior):
max_daily_usd: 200
budget_headroom_pct: 0
Note:max_daily_usd and budget_headroom_pct are top-level fields, not nested under claude: or agents:. When the ceiling is hit you will see a log line like Tenant daily cost ceiling exceeded — skipping repo until next UTC day. Issues will remain in whatever state they are in and resume processing automatically once daily spend resets at midnight UTC — no label changes or manual intervention are required. Runtime checks are skipped only when the resolved value is undefined; the standard loaded config defaults this field to 50.
USD cost cap per issue. When the accumulated cost for an issue reaches this limit, the Claude invocation is aborted, the issue is moved to colony:blocked, and Colony posts a comment with the cost breakdown. To unblock: raise this value in config, then comment /colony:retry on the GitHub issue to re-trigger processing. Omit for no limit.
Example:
claude:
max_cost_per_issue: 10
For all claude settings (timeout, model overrides, Foundry, scaling), see the full claude reference in Tier 3.
A repo may pin its own analyzer, developer and/or reviewer model with repos[].claude.models.<role>. For database-backed deployments, repo_configs.model_selection ({"analyzer": "...", "developer": "...", "reviewer": "..."}, any subset, {} for none) maps to the same key. Only these three roles are honoured; other keys, empty strings and non-strings are ignored. The override applies only when the agent’s engine is claude-code; it is ignored for codex. Hot-reloading it through ReloadableConfig.repos is supported; YAML edits need a restart. A reloaded repos[key].claude.models replaces the repo’s models rather than merging into them. Roles missing from it are removed, and {} clears them all so the tenant models apply again. A reload that carries no claude for a repo leaves its models unchanged.
Model precedence for a task, highest first:
#
Source
1
model_routing.override (global kill-switch)
2
Workflow state-declared model:
3
model_routing.routes[task][tier] when routing is enabled and a route matches
4
Repo claude.models.<role>
5
claude.scaling[tier].model, including the built-in defaults (developer only)
6
Tenant/global claude.models.<role>
A repo developer pin replaces tier-based model choice for that repo; effort and max-turns still scale by tier.
Rollout note: this is a behaviour change for any integrator that already writes repo_configs.model_selection. Values that were stored but never took effect start to apply. Audit stored values before upgrading.
Colony agents make different demands on the model. The table below shows approximate pricing and recommended use cases to help you balance cost against quality.
Model
Approx. pricing (input / output per M tokens)
Recommended use
claude-opus-5-5
~$4 / $20 (confirmed)
Developer, Reviewer, Planner, and Merger — frontier model with lowest fake-validation rate. Reference default for developer, reviewer, planner, and merger.
claude-opus-5
~$5 / $25 (confirmed; training cutoff May 2026)
Previous Opus generation — a valid fallback for users running existing workflows.
claude-opus-4-8
~$5 / $25
Older Opus generation — same pricing as Opus 5; a valid fallback for users running existing workflows.
claude-opus-4-7
~$5 / $25
Older Opus generation — same pricing; useful for users already running 4-7 in existing workflows.
claude-opus-4-6
~$5 / $25
Older Opus generation — still capable for complex tasks.
claude-sonnet-5
~$3 / $15 (placeholder — official rate TBD)
Analyzer — good balance of speed and quality for code triage. Reference default for analyzer. Also preferred over Opus for small dev tasks (better cost-for-quality).
claude-sonnet-4-6
~$3 / $15
Previous Sonnet generation — still a valid choice, no longer the shipped default.
claude-haiku-4-5-20251001
~$1 / $5
The role Haiku is meant for is conversation (the Mayor’s fast, single-turn replies to addressed messages). Not suitable for analyzer, developer, reviewer, planner, or merger — too small for reliable code triage or implementation. May also be used for non-pipeline tooling (e.g. credential validation).
claude-fable-5
~$10 / $50
Optional premium model for the Planner and/or Analyzer only — NOT a default; opt in explicitly. Not recommended for Developer or Reviewer due to cost at scale.
Pricing figures are approximate and may change. Use hedged budget estimates when planning spend.
Opus 5.5 is Anthropic’s current frontier model and, like Opus 5 before it, makes significantly fewer fake validations than earlier generations. Older Opus versions would sometimes tweak acceptance criteria or game tests so that everything appeared green while still shipping bugs. This failure mode is particularly costly in two roles:
Reviewer: rubber-stamping spec gaps, approving PRs that satisfy the letter of the criteria but miss the intent
Developer: writing code that games the test rather than satisfying the spec
Opus 5.5 reduces this behaviour, making it the right choice for correctness-critical roles even though it is slower at high thinking effort (high/max).
Colony uses thinking effort hints (effort field in claude.scaling) to control how deeply the model reasons per turn. The cost-quality tradeoffs:
max (extended thinking): worth it only for multi-file / cross-cutting work. ~4x token spend; negligible quality gain on single-file tasks. Default for large complexity developer tasks.
high: the right default for non-trivial work. Used by medium dev tasks and by the reviewer and planner.
medium: suboptimal — if you want balance plus cheap tokens, use Sonnet on high instead of Opus on medium.
low: very fast but poor at non-trivial tasks. Only suitable for mechanical renames or tiny edits.
Override any agent’s model via claude.models.<agent>:
merger: claude-sonnet-4-6# conflict resolution is bounded; sonnet sufficient
Note: The annotated example config (colony.config.example.yaml) sets all agents to claude-sonnet-4-6 as a cost-conscious starting point for evaluation, and also ships with a claude.scaling block that pins all three complexity tiers (small/medium/large) to Sonnet. This makes the example internally consistent: it will not trigger the colony check model-scaling-conflict warning, and all developer spend stays at Sonnet rates regardless of issue complexity. To re-enable auto-escalation to Opus 5.5 for medium and large issues, delete the claude.scaling block. This differs from the reference defaults above (Opus 5.5 for developer, reviewer, planner, and merger) — adjust those once you are comfortable with Colony’s output.
Note on opusplan alias: The opusplan alias in pricing configuration is frozen at claude-opus-4-6 for backward compatibility with existing user configs. Users who want the new default should use claude-opus-5-5 explicitly.
Each executor agent (analyzer, developer, reviewer, merger, planner) can run on either Claude Code (the default) or Codex. Set agents.<agent>.engine to switch the engine for a specific agent. Agents without an explicit engine field continue to use Claude Code — existing behavior is unchanged.
Redeploy required: The engine field is not hot-reloadable. Changing an agent’s engine requires a container restart or redeploy (see Config Hot-Reload Matrix).
Field
Type
Default
Description
engine
'claude-code' | 'codex'
'claude-code'
LLM engine backend for this agent. Applies to the five executor agents: analyzer, developer, reviewer, merger, planner. Omitted means Claude Code.
agents:
developer:
engine: codex# run the developer on Codex; all other agents stay on Claude
When any agent uses engine: codex, add a top-level codex: block to configure the Codex CLI. All fields have built-in defaults — the block is optional for Claude-only deployments.
Field
Type
Default
Description
timeout
number
600
Overall Codex CLI invocation timeout in seconds
max_retries
number
1
Number of times to retry a failed Codex invocation
inactivity_timeout
number
—
Seconds without output before the process is killed. Optional — omit for no inactivity cap
binary_path
string
codex (from PATH)
Path to the Codex binary. Override when codex is not on PATH
api_key_env
string
'OPENAI_API_KEY'
Name of the environment variable containing the OpenAI API key for Codex invocations
models
object
(see table below)
Per-agent model overrides for Codex engine invocations
Per-agent model overrides when using the Codex engine. Mirrors claude.models but uses OpenAI/Codex model identifiers. Omit the whole block to use the built-in Codex defaults.
Field
Type
Default
Description
developer
string
'codex-1'
Model used when the developer agent runs on Codex
reviewer
string
'o4-mini'
Model used when the reviewer agent runs on Codex
analyzer
string
'o4-mini'
Model used when the analyzer agent runs on Codex
planner
string
'o4-mini'
Model used when the planner agent runs on Codex
merger
string
'o4-mini'
Model used when the merger agent runs on Codex
conversation
string
'o4-mini'
Model used for the Mayor’s single-turn replies to addressed messages
Fallback keys:merger falls back to codex.models.reviewer when codex.models.merger is unset; planner falls back to codex.models.analyzer. This mirrors the fallback behavior in claude.models.
Colony validates the (engine, model) pair for each executor agent at config load time (colony check / startup). Incompatible pairs are rejected with a clear error — not a runtime failure.
codex.models.<key> '<model>' is not a Codex/GPT model — codex.models entries must be OpenAI/Codex model ids (e.g. codex-1, o4-mini, gpt-4o)
Per-agent engine/model mismatch:
agents.<agent>.engine: <engine> but resolved model '<model>' is not a <Claude|Codex/GPT> model — set <claude|codex>.models.<agent> to a … model
Missing OPENAI_API_KEY: When any agent is configured with engine: codex and the environment variable named by codex.api_key_env (default OPENAI_API_KEY) is absent, Colony emits a warning at config load and colony check — not a fatal error:
agents.<agent>[, ...] use engine: codex but OPENAI_API_KEY is not set — set this environment variable for Codex invocations
Worked example: developer on Codex, all other agents on Claude
Four overlapping knobs control what model is used and how much you spend. This section explains how they interact so you can predict spend before you hit a ceiling.
claude.scaling[complexity].model always wins over claude.models.developer for the developer agent. The claude.models.developer value is only used when the matching scaling entry has no model field.
All other agents (analyzer, reviewer, merger, planner) read directly from claude.models.<agent> — they are not affected by claude.scaling.
Built-in scaling defaults (used when claude.scaling is not set):
Tier
Model
Max turns
small
claude-sonnet-5
80
medium
claude-opus-5-5
150
large
claude-opus-5-5
250
Common gotcha: If you set claude.models.developer: claude-sonnet-4-6 to cap developer spend, medium and large issues will still use claude-opus-5-5 via the built-in scaling defaults. To force all tiers to Sonnet, you must also set claude.scaling.medium.model and claude.scaling.large.model. The shipped colony.config.example.yaml already implements this pattern — if you copied from that file, no additional changes are needed:
claude:
models:
developer: claude-sonnet-4-6# only affects tiers without a scaling.model override
Run colony check to detect this conflict — it emits a warning when claude.models.developer is set to a model that differs from the effective scaling models for any tier. Run colony estimate to see which model each complexity tier actually uses in the cost projection.
Opt-in feature:model_routing is disabled by default (enabled: false). Enable it only after reviewing the worked example and confirming the routing table matches your cost/quality goals.
Model routing lets Colony automatically select a model per task based on the task type and the issue’s assessed complexity tier. This is the primary lever for cutting cost on simple issues without sacrificing quality on complex ones.
enabled: true# master switch; false (default) → fall through to claude.models.*
override: ''# optional global force-model; applies regardless of enabled/routes
quota_fallback: true# optional; set false to decline quota-model fallback substitution entirely
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
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. Useful as a kill-switch
routes
object
—
Per-task-type, per-tier model map. Task keys: analyze, develop, review, merge, plan. Tier keys: small, medium, large
quota_fallback
boolean
true
When false, a model-specific quota 429 (quota_model_specific) never substitutes a replacement model — the task waits for the quota window instead of running on an unrequested model
Task-type mapping: The sweep task type maps to the analyze route key; review-external maps to review.
Model resolution follows this order (highest priority first):
override — when set, applies unconditionally regardless of enabled or routes
Station-declared model — a model on the workflow state itself (see the paragraph below)
routes[taskType][tier] — when enabled !== false and a matching route entry exists
claude.models.<agent> — fallback when routing is absent, disabled, or has no matching route. For the developer, claude.scaling[tier].model comes first (see Interaction with claude.scaling). A repo-scoped repos[].claude.models replaces the tenant-wide value
pin_models — backstop when claude.provider: foundry or claude.provider: gateway is set; maps model family names (opus/sonnet/haiku) to deployment identifiers
Important:override is checked before the enabled flag. Setting enabled: false disables route lookups but does not disable override. If you want to temporarily stop routing without clearing your routes table, set enabled: false and leave override unset.
Where a station-declared model sits: a workflow state may declare its own model (see Workflows). It outranks routes, the per-role key and the complexity tier, so an authored station value is not silently displaced by the route table. It does not outrank override: that is a global kill-switch for a deprecated or unavailable model, and an operator setting it must be able to move every task without editing and republishing workflow definitions. The full order is override > station-declared model > routes > per-role > tier.
One exception, at call sites with no complexity tier. The planner and the reviewer resolve a model without one — the tier is scored per issue by the analyzer, and recomputing it at those sites would risk diverging from the worker’s own result. A route table is indexed by tier, so it cannot be evaluated there. Rather than discard an explicitly configured executors.<role>.model in favour of a table entry that may not exist for this issue’s tier, those sites use the per-role value when one is set: the effective order becomes override > station-declared > per-role > routes. override is unaffected, so the kill-switch behaves identically everywhere. Set a model on the state itself if you want it to win at every call site.
When a model-specific 429 is reported (the quota_model_specific failure class — one Claude model family is rate-limited, not all of them), Colony retries once against a substitute model. That substitute is resolved through the same precedence chain described above, not a fixed lookup table:
If model_routing.override is set, or model_routing.quota_fallback: false is set, the retry is declined — the task is left to wait for the quota window instead of running on an unrequested model. This guarantees override can never be silently defeated by a quota fallback.
Otherwise, a one-step substitute family is chosen (sonnet → opus, haiku → sonnet, opus → sonnet), then resolved to a concrete model via model_routing.routes[taskType][tier] (if its family matches the substitute) and, for the developer agent only, claude.scaling[tier].model (if its family matches) — falling back to the bare family name (e.g. 'opus') when neither matches.
The substitution is traced as a second model_resolved phase with source: 'quota_fallback', so the task trace records the model that actually ran, not only the model originally resolved. Under claude.provider: foundry or claude.provider: gateway, a bare family-name substitute is still resolved via the pin_models backstop (see below) exactly as the primary dispatch model is.
This precedence-aware resolution applies to worker-dispatched tasks (analyze, develop, review, merge, plan), which is where model_routing is evaluated. A handful of ClaudeCodeCLI invocations outside the worker’s task dispatch — merge conflict resolution’s LLM assist, semantic-conflict assessment, the sprint-master, and the strategize/scan-conventions/colonize CLI commands — do not consult model_routing at all (they run outside a routed task) and always fall back to the bare one-step family ladder (sonnet → opus, haiku → sonnet, opus → sonnet) on a quota_model_specific 429, regardless of model_routing.override or quota_fallback.
For the developer agent only, claude.scaling[complexity].model (see Developer model precedence) is a separate override that applies after routing resolves the model for the develop route. In practice:
If model_routing is disabled, the developer agent uses claude.scaling[tier].model → claude.models.developer (existing behaviour).
If model_routing is enabled, routes.develop[tier] is resolved first. When no matching route entry exists, resolution falls back to claude.scaling[tier].model, then to claude.models.developer — i.e. routes.develop[tier] → claude.scaling[tier].model → claude.models.developer. Set routes.develop.* for every tier where you want routing to take precedence over claude.scaling.
When an issue is retried via /colony:retry after being blocked for a capability-attributable reason, Colony automatically escalates the complexity tier by one step before enqueueing the next task:
Block reason
Escalates?
review_cycle_limit
Yes
build_failure
Yes
ci_hard_failure
Yes
All others
No
The escalated tier is stored in task_inputs.model_tier and used by the worker when resolving the model for the retried task. This ensures that cost savings never trap an issue in a failure loop — if the cheaper model cannot solve the problem, the next attempt uses the next tier up.
The worker traces the resolution as model_resolved (with model, tier, and source fields) and, when a tier override is in effect, as model_escalated (with from_tier, to_tier, and reason).
override and routes return the literal model string from the configuration table — they are not engine-aware and apply regardless of an agent’s configured engine. If an agent uses engine: codex and a routing entry resolves a model for it, that literal model string is passed to the Codex CLI exactly as written.
Engine-scoped behavior operates at the fallback layer only: when routing is disabled or no route matches a given task type and tier, resolveModelForTaskType falls back to config.<engine>.models.<agent> — codex.models.* for Codex agents and claude.models.* for Claude agents. In a mixed-engine deployment, ensure that any override or route model string is valid for the target agent’s engine.
V1 scope: Per-complexity and dynamic engine routing (choosing the engine per task type or complexity tier) are out of scope for V1. Per-agent engine is a static configuration setting — all tasks for a given agent type use the same engine.
Route all tasks to a cost-conscious model by default, but use the capable model for large development and planning tasks:
# Force all agents to Sonnet at the claude.models level (the routing fallback)
claude:
models:
developer: claude-sonnet-4-6
reviewer: claude-sonnet-4-6
analyzer: claude-sonnet-4-6
planner: claude-sonnet-4-6
merger: claude-sonnet-4-6
# Enable routing to pin large dev/plan tasks to Opus
model_routing:
enabled: true
# no override — allow per-route resolution
routes:
develop:
large: claude-opus-4-8# complex multi-file work gets the capable model
plan:
large: claude-opus-4-8# epic decomposition for large issues uses Opus
With this config:
analyze (all tiers), review (all tiers), merge (all tiers), and develop/plan for small/medium → claude-sonnet-4-6 (from claude.models.* fallback)
develop.large and plan.large → claude-opus-4-8 (from routes)
Any retry after review_cycle_limit, build_failure, or ci_hard_failure → the scored tier is escalated one step, potentially promoting a medium issue to large routing on retry
Claude invocation is aborted; issue moves to colony:blocked; comment posted with cost breakdown. Resume with /colony:retry after raising the limit.
max_daily_usd
Per-tenant/daily
No new work is started for the rest of the UTC day. Issues already running are not interrupted. Resets at midnight UTC automatically — no manual action needed.
budget_headroom_pct
Modifier
Lowers the effective daily ceiling to max_daily_usd × (1 − pct/100) to absorb concurrent-worker overage. Default 10%. Set to 0 to use the exact max_daily_usd value.
The two ceilings are independent and additive. An issue can be blocked by max_cost_per_issue while the daily ceiling has not yet been reached, or vice versa.
Colony appends a short disclosure footer to every agent-authored GitHub artifact — issue comments, PR descriptions, review bodies, and created issue bodies. This satisfies the EU AI Act Article 50(1) obligation, which requires AI systems that interact directly with natural persons to disclose that interaction. The deadline is 2 August 2026 and was not deferred by the May 2026 Digital Omnibus agreement.
attribution:
enabled: true# default true
text: 'Orchestrated by [Colony](https://runcolony.com) — autonomous software development pipeline.'
Field
Type
Default
Description
enabled
boolean
true
When false, no disclosure footer is appended. Disabling this weakens the operator’s own Article 50(1) compliance posture — only disable after legal review.
text
string
See above
The disclosure text appended after a horizontal rule (---). Self-hosted operators may substitute their own deployment name.
Controls whether operator-internal comments are suppressed on customer-facing issue threads. When customer_facing is true, comments tagged with audience: 'operator' are redirected to operator logs instead of being posted to the public issue thread. Untagged comments and audience: 'customer' / audience: 'both' comments always dispatch regardless of this setting.
comment_policy:
customer_facing: false# default false — no suppression
Field
Type
Default
Description
customer_facing
boolean
false
When true, audience: 'operator' comments are suppressed from issue threads (redirected to logs)
Colony’s config-watcher polls your colony.config.yaml every 2 seconds and applies changes live for the blocks below — no container restart needed. Blocks listed as Needs redeploy require a docker compose restart (or equivalent) to take effect.
Block
Status
Singleton(s) consumed by
claude
Reloads live
worker, sprint-master, monitor
codex
Reloads live — Codex engine settings; per-agent engine field is NOT reloadable (requires redeploy)
worker
review
Reloads live
worker
dependabot
Reloads live — the worker’s approve and merge decisions and sprint-master intake
worker, sprint-master
max_daily_usd
Reloads live
worker, sprint-master, monitor
daily_ceiling_comment
Reloads live
worker
budget_headroom_pct
Reloads live
worker, sprint-master, monitor
agents
Partial — selected workers, sprint_master, and monitor sub-keys reload live; agent identity/startup settings need redeploy
worker, sprint-master, monitor
llm
Reloads live (deprecated — prefer claude.scaling)
worker
attribution
Reloads live
worker, sprint-master
comment_policy
Reloads live (worker, sprint-master); monitor requires restart (caches write-services)
worker, sprint-master
intelligence
Reloads live
worker
model_routing
Reloads live
worker
intake_rules
Reloads live (deprecated — use repos[].workflows)
sprint-master
default_workflow
Reloads live (deprecated — use repos[].workflows)
sprint-master
strategy
Reloads live — all keys, including cadence (read every scheduler tick)
sprint-master
merge
Reloads live
worker
mailbox
Reloads live
worker
overlap
Reloads live
worker, sprint-master
max_cost_per_issue
Reloads live (top-level alias for claude.max_cost_per_issue)
worker
logging
Partial — level reloads live; format needs redeploy
worker, sprint-master, monitor
workspace
Partial — safe sub-keys reload live; identity/path sub-keys need redeploy
worker
repos
Partial — per-repo review.*, dependabot.*, default_stewards and safe workspace.* sub-keys reload live; adding/removing repos is live for the sprint-master and webhook-receiver (workers and the monitor need a redeploy); changing identity fields needs redeploy
Authoritative source: The classifications above reflect RELOADABLE_KEYS, PARTIAL_RELOADABLE_KEYS, REPO_REVIEW_RELOADABLE_KEYS, and REPO_WORKSPACE_RELOADABLE_KEYS in packages/core/src/config-watcher.ts. Keep this matrix in sync when adding new reloadable keys.
Each entry in repos[] is identified by its owner/repo slug. Adding or removing a repo entry (under repos[] or tenants[].repos[], within the tenants and shape the process booted with) is live for the sprint-master and the webhook-receiver, except that ADO webhook GUID routing in the receiver is built only at boot (events for an ADO repo added live do not route until a restart). Workers and the monitor still need a redeploy; until then, tasks the sprint-master enqueues for a live-added repo can wait or fail and use up retry attempts. Changing an existing repo’s identity (credentials, app, workspace paths), adding or removing a tenant, and moving a repo between tenants or out of repos[] always require a redeploy. For existing repos:
Controls deployment-mode-specific path handling. This section is optional.
Field
Type
Default
Description
mode
'docker-compose' | 'native' | 'apple-container'
(inferred)
Deployment mode. If omitted, Colony infers docker-compose inside containers or when docker-compose.yml exists, otherwise native. apple-container must be set explicitly.
Azure DevOps single-repo configuration. When top-level repos[] is omitted and ado is present, Colony synthesizes an ADO repo entry from this block and the top-level workspace settings.
Field
Type
Default
Description
organization
string
required
Azure DevOps organization name
project
string
required
Azure DevOps project name
repo
string
required
Azure DevOps repository name
token_env
string
required
Environment variable containing the ADO Personal Access Token for the coder identity
ops_token_env
string
—
Environment variable containing a separate ADO PAT for ops actions
closed_state
string
'Closed'
Work item state that represents a closed/done issue
Separate GitHub App credentials for the ops identity (Sprint Master, Reviewer, Merger). Allows two distinct bot identities
ops_token_env
string
—
Name of the environment variable containing the PAT for the ops identity. Alternative to ops_app
bot_username
string
—
Display name shown for bot-authored comments and labels
rate_limit_jitter_ms
integer (≥ 0)
30000
Upper bound in ms of the random jitter added to rate-limit recovery: worker re-enqueues after a rate-limit reset become claimable between the reset and the reset plus this bound, and the sprint-master failure backoff gains up to this much random delay, so callers don’t all resume at the same instant. 0 disables jitter. GitHub clients also hold requests made while a primary-limit reset is pending and release each one at the reset plus up to this bound; that client-side spread is fixed when the clients are built and needs a restart to change (the worker re-enqueue jitter and sprint-master backoff read the current config). The one-shot colony check / generate-config clients always use the default
request_budget
object
— (unlimited)
Per-process budget of requests and content-generating writes sent to each installation. Keys default, sprint_master, monitor, webhook_receiver, worker, mcp, each with requests_per_minute, content_writes_per_minute and content_writes_per_hour (positive integers; a process uses { ...default, ...<its role> }). Unset means unlimited: requests flow as today apart from the secondary-limit pause. Writes are every request other than GET/HEAD (GraphQL included), counted when sent; requests count every send, 304s included. Waiting requests go out essential first, then optional (untagged requests are essential). Size the shares so their sum across processes stays under GitHub’s 900 points/min, 80 content writes/min and 500/h. The MCP server applies its mcp share to all its GitHub requests, including in the env-only container (DATABASE_URL and GITHUB_TOKEN set), where the budget is read from the config file. Restart required
Secondary rate limits. After a secondary-limit response, or any response carrying a retry-after header, a process sends no request to that installation for retry-after seconds, or 60 seconds when the header is absent or unusable. The throttling plugin’s own retries are disabled so they cannot bypass the pause; requests waiting on it resume after it ends (spread by rate_limit_jitter_ms). Limits that arrive while the pause is pending (other in-flight requests from the same burst) do not lengthen the backoff. If the limit recurs within 60 seconds after the pause ends, the pause doubles each time (60, 120, 240 seconds, …) up to a cap of 15 minutes. A recurrence after that window starts again at the base pause. A request whose task deadline ends before the pause fails with a secondary rate-limit error.
Controls the namespace used for every pipeline label Colony creates on GitHub issues or Azure
DevOps work items — state labels and flag labels.
Field
Type
Default
Description
prefix
string
'colony'
Namespace for every label Colony emits or recognises — state labels (colony:analyzing, colony:ready-for-dev), flag labels (colony:enqueue, colony:blocked, colony:paused, colony:needs-human, colony:stale, colony:epic, …), the self-improvement track namespace (colony:si-*), and the inbound label commands the sprint-master watches for. Change this if you need to run multiple Colony instances against the same repo with distinct label namespaces
prefix does not affect the slash-command namespace, which is configured separately by
commands.root; nor does it affect Colony’s HTML comment markers, which are bot
signatures written into issue bodies rather than labels.
See GitHub Labels for the full catalog of state, flag, and operator command labels this
prefix rewrites.
Changing prefix on a repo with existing issues. Label sync only adds and reconciles labels under the currently configured prefix — it does not remove state labels already on an issue from a previous prefix. This is deliberate: labels outside the configured prefix are treated as foreign, so two Colony instances sharing a repo under different prefixes never strip each other’s labels. After a prefix rename, issues keep their old-prefix state label alongside the new one; delete the stale labels manually (or via GitHub’s label UI) if you want a clean slate.
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. Colony creates worktrees under this directory. Not required for Docker Compose deployments — workers clone the repo automatically inside their container
base_dir
string
'~/.colony/workspaces/{owner}/{repo}'
Base directory for worktrees. Supports {owner} and {repo} template tokens which are substituted at runtime
cleanup_after_merge
boolean
true
Remove the worktree after a PR is merged. Set to false to retain worktrees for post-merge inspection
setup_command
string
—
Command to run after creating a worktree, instead of the default npm install. Use for non-TypeScript repos (e.g. 'bundle install' for Ruby/Rails). Commands run in a non-login shell and inherit the worker’s PATH (including mise shims); if you need a multi-step command, prefer bash -c '...' over bash -lc '...' to avoid login-shell PATH reset on Debian
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 (e.g. 'npm run build'). Use for monorepos with internal packages that must be built before tests can run
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. Required when the reviewer runs in an isolated container with a different filesystem layout
skip_pre_push_hook
boolean
—
When true, passes --no-verify to git push. Colony runs its own validation steps, so this is safe in containerized deployments where the local pre-push hook is not meaningful
branch
string
'main'
Default branch name for the repository. Override when the repo’s default branch is not main (e.g. 'master', 'develop')
Connection settings for the Postgres database used by the pipeline store. This section is optional for configuration — if omitted, Colony reads DATABASE_URL from the environment using built-in defaults. However, a Postgres connection is always required at runtime — colony check will always validate database connectivity regardless of whether this section is present.
Field
Type
Default
Description
url_env
string
'DATABASE_URL'
Name of the environment variable containing the Postgres connection string
listen_url_env
string
url_env
Environment variable for a direct Postgres URL used by LISTEN/NOTIFY. Set this separately when url_env points at PgBouncer transaction pooling
max_connections
number
10
Maximum number of connections in the pg connection pool. Increase for high-throughput deployments with many concurrent workers. Also the fallback for every pool_size key
pool_size
map
unset
Per-component pg pool size. Keys: sprint_master, monitor, webhook_receiver, worker, nomad. Each key falls back to max_connections, then 10. A worker process uses nomad when COLONY_TENANT is set and worker otherwise. Positive integers only. The MCP server has no key and uses max_connections
idle_timeout
number
10000
idleTimeoutMillis for the pg connection pool (milliseconds). Lower this for connection-constrained environments
connection_timeout
number
10000
connectionTimeoutMillis for establishing a pg client connection
statement_timeout
number
30000
Server-side Postgres statement timeout in milliseconds (see note below for poolers/Neon)
query_timeout
number
30000
Client-side node-postgres query timeout in milliseconds
keep_alive
boolean
true
Enable TCP keepalive for Postgres sockets. ssl, connection_timeout and keep_alive also apply to the LISTEN/NOTIFY connection (listen_url_env) of the worker and sprint-master
ssl
boolean | object
false
Enable SSL for Postgres connections. Required for most cloud-hosted Postgres instances (e.g. RDS, Cloud SQL). true verifies the server certificate; { verify: false } opts out (logs a warning)
Sizing pools against Postgres max_connections: each runtime pool can open up to its size in connections, and each worker, nomad replica and the sprint-master also hold LISTEN connections. Two tenants with four nomad replicas each, at the default of 10 plus 3 LISTEN connections per replica, use 2 × 4 × 13 = 104. The sprint-master (10 + 1), the monitor (10) and the webhook-receiver (10) add 31, about 135 in total, against Postgres’s default max_connections of 100. Each MCP server adds 10 more. Lower the idle components and keep the busy one large:
database:
max_connections: 10
pool_size:
sprint_master: 20
monitor: 4
webhook_receiver: 4
nomad: 3
A pool-acquire timeout (timeout exceeded when trying to connect) is retried once by store queries and transactions.
Database migrations: Colony runs Postgres migrations automatically at agent startup — both the sprint-master and worker call PipelineStore.initialize() which applies all pending migrations before the agent begins processing. No manual migration step is needed. If startup fails with a migration error, verify DATABASE_URL connectivity and that the Postgres user has CREATE TABLE privileges. Some migrations, such as 209 (sweep indexes), build indexes with a plain CREATE INDEX, which blocks writes to the table while it builds. On large deployments, pre-create them before upgrading with CREATE INDEX CONCURRENTLY IF NOT EXISTS under the same names (listed in the migration’s header), after dropping any INVALID leftover from a failed attempt.
statement_timeout behind poolers and Neon: node-postgres sends statement_timeout as a raw startup parameter, which Neon drops silently on both its pooled and direct endpoints. On direct URLs Colony therefore also sends options=-c statement_timeout=<ms> (merged with any options in the URL or PGOPTIONS), which is honored. Transaction-mode poolers (Neon -pooler, Supabase port 6543, PgBouncer, pgbouncer=true) drop or reject startup settings (Neon fails with unsupported startup parameter in options), so Colony does not send options there. Set a role or database default instead, which every pooled backend inherits: ALTER ROLE <colony_role> SET statement_timeout = '30s' (or ALTER DATABASE). The role default also applies to migrations run as that role; use a separate role if migrations need longer. At startup Colony checks pg_settings once and logs a database.statement_timeout not in effect warning naming the endpoint type when the value does not match (behind a pooler this samples one backend). Until it is in effect, only the client-side query_timeout bounds queries, and a timed-out statement keeps running on the server.
TLS verification: The MCP server and the webhook-receiver honor database.ssl and the other database.* settings too (see MCP database settings): with ssl: true and no SSL parameters in the URL they now connect over TLS and verify the certificate; opt out with the private-CA, ssl: { verify: false } or URL sslmode options described here. ssl: true verifies the server certificate against the system CAs plus NODE_EXTRA_CA_CERTS. For Postgres with a private-CA or self-signed certificate, mount the CA under /colony/keys/ca-certs/*.crt (see Enterprise Networks) or set NODE_EXTRA_CA_CERTS outside the image. ssl: { verify: false } disables verification and logs a warning once per process; it is not recommended. SSL parameters in the connection URL (sslmode, sslrootcert, sslcert, sslkey, ssl) override database.ssl completely, because pg spreads the parsed URL over the config. sslmode=no-verify disables verification without the Colony warning. sslmode=require, verify-ca and verify-full verify under pg’s default semantics, but uselibpqcompat=true&sslmode=require does not verify.
Controls the local event log written by Colony agents. This section is optional.
Field
Type
Default
Description
enabled
boolean
true
Enable or disable event logging for agents that use the event logger
dir
string
'~/.colony/events'
Directory where event log files are written
retention_days
number
30
Number of days to retain local event log files before pruning
agent_message_retention_days
number
14
Number of days to retain agent_messages rows before sprint-master retention sweeps prune partitions
pipeline_event_retention_days
number
unset (keep forever)
pipeline_events is Colony’s permanent audit log, so it is never pruned unless you set this. Minimum 365; a lower or non-numeric value is rejected. The sprint-master’s global sweep drops whole monthly partitions, so rows live between N and about N+31 days
Configures the webhook receiver that listens for incoming GitHub webhook events. This section is optional — omit it if you are 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 to listen on
secret_env
string
—
Name of the environment variable containing the HMAC secret used to verify webhook payloads from GitHub. Required unless ADO webhook auth is configured; if the named variable is unset at startup the receiver exits, and if omitted GitHub deliveries get 401
Controls Claude CLI invocation behaviour 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 stdout/stderr output before the process is killed with SIGKILL
max_cost_per_issue
number
—
USD cost cap per issue. When the accumulated cost for an issue reaches this limit, the Claude invocation is aborted, the issue is moved to colony:blocked, and Colony posts a comment with the cost breakdown. To unblock: raise this value in config, then comment /colony:retry on the GitHub issue to re-trigger processing. Omit for no limit.
binary_path
string
'claude'
Path to the Claude CLI binary. Override when the binary is not on PATH or you need a specific version
provider
'anthropic' | 'foundry' | 'gateway'
'anthropic'
API provider for Claude Code CLI. Use 'foundry' to route through Azure Foundry, or 'gateway' for any Anthropic-compatible AI gateway (e.g. TrueFoundry)
When auth_mode is omitted or set to api-key, Colony invokes Claude Code with API-key authentication. For the default Anthropic provider, ANTHROPIC_API_KEY must be present in the process environment; for provider: foundry, set claude.foundry.api_key_env (default ANTHROPIC_FOUNDRY_API_KEY).
When auth_mode: oauth-token, Colony injects only the OAuth token environment variable named by oauth_token_env (default CLAUDE_CODE_OAUTH_TOKEN) and intentionally does not inject ANTHROPIC_API_KEY. oauth_expires_at is optional metadata used by workers and sprint-master to detect expired tokens before invoking Claude Code.
auth_mode: wif lets workers run without a static Anthropic credential. The host provides a short-lived JWT from a trusted identity provider in a file; Claude Code exchanges it for an Anthropic token through a federation rule and refreshes it.
Experimental. Whether Claude Code re-reads the token file when it refreshes mid-session is not yet verified (JWTs with a jti are single-use). Until that has been checked against a sandbox organization with a 60-second token_lifetime_seconds and a rotating token file, do not rely on this mode for long sessions.
What the Anthropic organization configures: a service account, a federation issuer (the identity provider that signs the JWT) and a federation rule that maps the JWT to that service account. The rule, organization and service account IDs go into claude.wif. See Anthropic’s Workload Identity Federation guide.
# identity_token_file_env: ANTHROPIC_IDENTITY_TOKEN_FILE # alternative: env var holding the path
Field
Description
federation_rule_id
Required. Sent as ANTHROPIC_FEDERATION_RULE_ID
organization_id
Required. Sent as ANTHROPIC_ORGANIZATION_ID
service_account_id
Required. Sent as ANTHROPIC_SERVICE_ACCOUNT_ID
workspace_id
Optional. Sent as ANTHROPIC_WORKSPACE_ID only when set
identity_token_file
Path of the JWT file, sent as ANTHROPIC_IDENTITY_TOKEN_FILE. Wins over identity_token_file_env
identity_token_file_env
Name of an environment variable that holds the file path (the host provides the file)
One of identity_token_file or identity_token_file_env is required.
Rules:
Colony does not produce the identity token. The host or platform running the workers must provide the file and rotate it before the JWT expires.
ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, CLAUDE_CODE_OAUTH_TOKEN and apiKeyHelper all outrank federation, even when set to an empty string. Colony removes the three variables (and the variable named by oauth_token_env) from the environment of claude -p, so the child gets exactly the federation variables and no other credential variable. apiKeyHelper is a Claude Code settings key, not a variable: remove it from ~/.claude/settings.json and the repo’s .claude/settings.json. colony check warns when ~/.claude/settings.json defines it.
Colony never passes --bare to Claude Code; --bare ignores federation variables.
Only provider: anthropic is supported (not foundry or gateway), and the mode is set globally with claude.auth_mode; per-repo auth_mode values from the database cannot be wif.
colony check reports missing variables, whether the token file exists and is readable, and the token’s exp time. It never prints the token or any other claim.
Used by claude.foundry. Only applies when claude.provider is '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 endpoint root. Colony appends /v1/messages when probing credentials (a trailing /v1 on the base URL is normalised away). Custom ports, query strings, and http:// schemes are honoured. 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 (sets ANTHROPIC_DEFAULT_OPUS_MODEL)
pin_models.sonnet
string
—
Pin the Sonnet deployment name (sets ANTHROPIC_DEFAULT_SONNET_MODEL)
pin_models.haiku
string
—
Pin the Haiku deployment name (sets ANTHROPIC_DEFAULT_HAIKU_MODEL)
Example:
claude:
provider: foundry
foundry:
resource: my-azure-resource
api_key_env: ANTHROPIC_FOUNDRY_API_KEY
pin_models:
opus: claude-opus-4-6
sonnet: claude-sonnet-4-6
haiku: claude-haiku-4-5
Authentication: set the environment variable named by claude.foundry.api_key_env (default ANTHROPIC_FOUNDRY_API_KEY). See the Claude Code Foundry docs for provider-specific details.
Used by claude.gateway. Only applies when claude.provider is 'gateway'.
Field
Type
Default
Description
base_url
string
required
Gateway base URL (sets ANTHROPIC_BASE_URL)
auth_token_env
string
'ANTHROPIC_AUTH_TOKEN'
Environment variable holding the gateway auth token (sets ANTHROPIC_AUTH_TOKEN)
custom_headers
string
—
Custom headers forwarded to the gateway (sets 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 (sets ANTHROPIC_DEFAULT_OPUS_MODEL)
pin_models.sonnet
string
—
Pin the Sonnet model identifier (sets ANTHROPIC_DEFAULT_SONNET_MODEL)
pin_models.haiku
string
—
Pin the Haiku model identifier (sets ANTHROPIC_DEFAULT_HAIKU_MODEL)
budget_exhausted_match
list
—
[{ status, text }] rules; a failed result with that HTTP status whose error text contains text (case-insensitive) is a gateway budget block (gateway_budget), not a quota pause
budget_exhausted_match[].status
number
—
HTTP status the rule matches (400–599)
budget_exhausted_match[].text
string
—
Case-insensitive substring of the error text the rule matches
attribution.header
string
—
Header name (format: json) or header-name prefix (format: headers, emits <header>-<field>). Setting attribution turns it on; must not collide with custom_headers
attribution.format
string
json
json (one header holding a JSON object) or headers (one header per field)
# Colony passes --model <id> explicitly, and pin_models only rewrites the opus/sonnet/haiku
# aliases, so set the model ids to what the gateway serves.
models:
analyzer: claude-code/claude-opus
reviewer: claude-code/claude-opus
developer: claude-code/claude-opus
Authentication: set the environment variable named by claude.gateway.auth_token_env (default ANTHROPIC_AUTH_TOKEN) to the gateway’s API key or bearer token. Gateway traffic does not use ANTHROPIC_API_KEY — the gateway branch in Colony’s provider env builder intentionally omits it. That token is read from the process environment, so it must also reach the container — see Gateway / LLM Proxy below.
Colony and Claude Code both derive per-invocation cost by string-matching the model id against a known Anthropic pricing table. When traffic is routed through a gateway, model ids are typically namespaced (e.g. claude-code/claude-sonnet-4-6). Colony can still attribute cost in this case, but the namespaced id must contain a recognisable Anthropic tier token — one of opus, sonnet, fable, or haiku (case-insensitive).
Examples:
Model id in config
Resolved pricing tier
Cost attribution
acme/claude-sonnet-4-6
Sonnet ($3/$15 per M)
✓
anthropic-main/claude-opus-4-8
Opus ($5/$25 per M)
✓
claude-code/claude-haiku-4-5
Haiku ($1/$5 per M)
✓
gateway/mystery-model-v99
—
✗ (unknown tier)
Fallback when identification fails. If Colony cannot identify the tier, it operates in a “no price caps” mode:
claude.max_cost_per_issue is inoperative for that model — agents are not stopped on cost grounds.
Failed runs with zero reported cost are not classified as quota-exhausted, avoiding false retries.
Colony warns at worker startup and in colony check which model ids cannot be priced.
These warnings are best-effort — they confirm Colony’s tier matching works, but they cannot guarantee Claude Code itself resolves the same id to a price on the gateway. Verify against the gateway’s documentation if you need both Colony and Claude Code cost tracking to be accurate.
Colony also supports routing Claude Code traffic through an LLM gateway or proxy (e.g. TrueFoundry, LiteLLM, a self-hosted reverse proxy) by setting standard Claude Code environment variables in the process environment of the sprint-master and worker containers. Use this when you want gateway routing without a claude.gateway config block, or alongside it to supply the gateway auth token.
Variable
Purpose
ANTHROPIC_BASE_URL
Override the Anthropic API endpoint root. Claude Code appends /v1/messages for requests.
ANTHROPIC_AUTH_TOKEN
Bearer token forwarded to the gateway endpoint.
ANTHROPIC_CUSTOM_HEADERS
Additional HTTP headers sent with every Claude Code request, one Name: Value pair per line (use \n between pairs for multiple headers). For gateway routing or tenant headers. Credentials belong in ANTHROPIC_AUTH_TOKEN or ANTHROPIC_API_KEY, not here.
CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS
Set to true to disable Claude Code experimental beta features. Useful for gateways that do not support beta API surfaces.
These variables are passed through the Compose environment: blocks for the sprint-master and worker services. Export them in your shell before running docker compose up, or add them (uncommented) to your .env file.
Custom-named gateway token variables. If your gateway requires a custom-named API key variable (e.g. TRUEFOUNDRY_API_KEY) rather than ANTHROPIC_AUTH_TOKEN, the fixed Compose allowlist cannot cover it automatically. You must manually add that variable name to the environment: block of each affected service (sprint-master, worker) in docker-compose.yml and docker-compose.canary.yml:
worker:
environment:
# ... existing vars ...
- TRUEFOUNDRY_API_KEY
Then export the variable in your shell or add it to .env.
Symptoms: Claude Code exits at startup with a message like Unknown model or Model not available. Colony blocks the issue and posts a comment noting a model-compatibility error.
Root cause: The model id set in pin_models (or claude.models.*) does not contain a recognisable Anthropic tier token. Claude Code string-matches the model id to decide which API surface to use; a purely opaque id like gateway/mystery-model-v99 fails this check.
Fix: Update pin_models so each value contains opus, sonnet, haiku, or fable somewhere in the id — for example claude-code/claude-sonnet-4-6 or acme/claude-opus-4-8. The prefix is arbitrary; the tier token is what matters.
Symptoms: Claude Code stderr contains an HTTP 401 or invalid_api_key / Authentication failed error. Colony blocks the issue with an auth-failure note.
Root cause: One of two things:
Wrong auth_token_env name. The value of claude.gateway.auth_token_env (default ANTHROPIC_AUTH_TOKEN) doesn’t match the environment variable you actually exported. For example, if your gateway uses TRUEFOUNDRY_API_KEY but auth_token_env is still at its default, the token is never injected.
Token not reaching the container. The variable is exported in your shell but is not in the Compose environment: allowlist, so the worker container starts without it.
Fix for wrong name: Set claude.gateway.auth_token_env to the variable name you export:
claude:
provider: gateway
gateway:
auth_token_env: TRUEFOUNDRY_API_KEY
Fix for missing Compose allowlist entry: Add the variable to the environment: block of sprint-master and worker in docker-compose.yml (and docker-compose.canary.yml if used):
worker:
environment:
- TRUEFOUNDRY_API_KEY
Then re-export the variable in your shell (or add it to .env) and restart the containers.
Colony agents make different demands on the model. The table below shows approximate pricing and recommended use cases to help you balance cost against quality.
Model
Approx. pricing (input / output per M tokens)
Recommended use
claude-opus-5-5
~$4 / $20 (confirmed)
Developer, Reviewer, Planner, and Merger — frontier model with lowest fake-validation rate. Reference default for developer, reviewer, planner, and merger.
claude-opus-5
~$5 / $25 (confirmed; training cutoff May 2026)
Previous Opus generation — a valid fallback for users running existing workflows.
claude-opus-4-8
~$5 / $25
Older Opus generation — same pricing as Opus 5; a valid fallback for users running existing workflows.
claude-opus-4-7
~$5 / $25
Older Opus generation — same pricing; useful for users already running 4-7 in existing workflows.
claude-opus-4-6
~$5 / $25
Older Opus generation — still capable for complex tasks.
claude-sonnet-5
~$3 / $15 (placeholder — official rate TBD)
Analyzer — good balance of speed and quality for code triage. Reference default for analyzer. Also preferred over Opus for small dev tasks (better cost-for-quality).
claude-sonnet-4-6
~$3 / $15
Previous Sonnet generation — still a valid choice, no longer the shipped default.
claude-haiku-4-5-20251001
~$1 / $5
The role Haiku is meant for is conversation (the Mayor’s fast, single-turn replies to addressed messages). Not suitable for analyzer, developer, reviewer, planner, or merger — too small for reliable code triage or implementation. May also be used for non-pipeline tooling (e.g. credential validation).
claude-fable-5
~$10 / $50
Optional premium model for the Planner and/or Analyzer only — NOT a default; opt in explicitly. Not recommended for Developer or Reviewer due to cost at scale.
Pricing figures are approximate and may change. Use hedged budget estimates when planning spend.
Override any agent’s model via claude.models.<agent>:
merger: claude-sonnet-4-6# conflict resolution is bounded; sonnet sufficient
Note: The annotated example config (colony.config.example.yaml) sets all agents to claude-sonnet-4-6 as a cost-conscious starting point for evaluation. This differs from the reference defaults above (Opus 5.5 for developer, reviewer, planner, and merger). If you start from the example config, you will get cheaper but potentially less capable behaviour for complex issues — adjust developer, reviewer, planner, and merger to Opus 5.5 once you are comfortable with Colony’s output.
Note on opusplan alias: The opusplan alias is frozen at claude-opus-4-6 for backward compatibility. Users who want the new default should use claude-opus-5-5 explicitly.
Used by claude.scaling. The config is a map with keys small, medium, and large (matching issue complexity levels). Each entry is a ClaudeScalingEntry. For reliable runtime behavior, define all three tiers when setting claude.scaling; hot reload can merge partial tier updates into an already initialized scaling map.
Override the model for this complexity level, taking precedence over claude.models.developer
effort
'low' | 'medium' | 'high' | 'max'
high (small/medium) / max (large)
Effort level hint passed to the Claude CLI for this complexity. Use max only for large/multi-file work; see effort-mode economics above
planning_max_turns
number
500
Maximum turns for planning sub-tasks at this complexity
no_progress_window
number
— (75 for large only)
Number of turns without measurable progress before aborting
backstop_max_turns
number
500
Hard turn ceiling regardless of other limits
Validation requires developer_max_turns to be greater than 0 for any configured tier and planning_max_turns to be 0 or greater when set. Set planning_max_turns: 0 to skip planning for that tier.
Built-in default scaling (used when claude.scaling is not set):
Tier
model
effort
developer_max_turns
Rationale
small
claude-sonnet-5
high
80
Sonnet-high beats Opus-medium on cost-for-quality for 1–3 file mechanical work
medium
claude-opus-5-5
high
150
Opus-high for 3–7 file work; max not justified at this scope
large
claude-opus-5-5
max
250
The one tier where extended thinking’s 4x cost pays back on multi-file refactors
Tuning for first use: The defaults work well for evaluation. If you find issues timing out or review checks failing on slow test suites, these are the first fields to adjust:
Field
Default
Recommended starting point
claude.timeout
1800
Increase to 3600 for large repos with long build times
review.timeout_per_check
120
Raise to 300 for slow test suites
agents.sprint_master.poll_interval
30
30 is sufficient for evaluation; lower only if you need sub-30s latency and have webhooks configured
Named shell commands to run as deterministic review checks (e.g. test: 'npm test', lint: 'npm run lint'). Keys are check names; a value is either a bare shell command (blocking) or { command, blocking? } — blocking defaults to true. A blocking: false check runs like any other but its failure is reported (comment + status line + agent_findings record) and never gates the review, self-validation, or the merger — useful for rolling out a new check in report-only mode. Commands run in a non-login shell inheriting the worker’s PATH; prefer bash -c '...' over bash -lc '...' if a shell wrapper is needed
timeout_per_check
number
120
Seconds allowed for each check command before it is killed
max_review_cycles
number
5
Maximum number of LLM review rounds before giving up. Once exceeded, a cycle is still allowed to proceed if the most recently posted round’s item verdicts were all PASS (a converging loop); otherwise the issue is blocked. A hard-ceiling backstop of max(max_review_cycles * 2, 10) blocks unconditionally regardless of verdicts. Overridable per-repo via repos[].review.max_review_cycles
flaky_reruns
number
1
Times a failed blocking check is re-run on the PR’s own review worktree before the baseline comparison. A check that passes on a rerun is classified as flaky rather than failed. 0 disables reruns. Integer 0–5 (each rerun can take up to timeout_per_check seconds). Overridable per-repo via repos[].review.flaky_reruns. Hot-reloadable
ci_flaky_reruns
number
1
CI check runs that fail are re-run on the same head SHA this many times before the reviewer routes back or the merger reports a PR-introduced failure. 0 disables it. Integer 0–5. Worst-case CI wait per task is ci_check_timeout × (1 + ci_flaky_reruns), bounded by agents.workers.max_task_duration. Separate from flaky_quarantine_threshold, which only covers review.checks. Overridable per-repo via repos[].review.ci_flaky_reruns. Hot-reloadable
flaky_quarantine_threshold
number
unset
When set, a blocking check whose flake count over the rolling 14-day window is at or above this value is quarantined: its failures are treated as advisory by the reviewer (developer self-validation and merger checks still treat it as blocking). Quarantined checks are still re-run on failure so their flakes keep counting. Integer >= 1; unset means no quarantine. Overridable per-repo via repos[].review.flaky_quarantine_threshold. Hot-reloadable
max_reimplement_cycles
number
—
Maximum number of times the developer re-implements after a review rejection. Unlimited if unset
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 before timing out
ci_required_checks
string[]
[]
Names of specific CI checks that must pass. When empty, all checks must pass
ci_absent_check_grace
number
600
Seconds auto-merge waits for a required CI check with no run or status on the PR head before merging without it. Also skipped once every check suite and status on the head has finished without reporting it. A check the previous head reported stays pending for this long after a merger push
format_command
string
—
Formatting command Colony runs before review checks and commits (e.g. 'npm run format:fix'). Colony formats only when this is set; it never detects or picks a formatter itself. Optional
clean_verification
string
—
Optional raw shell command run as a final cache-defeating pre-handoff verification step (e.g. 'npm ci && npm run build:fresh && npm test' for TypeScript/React; 'dotnet clean && dotnet restore && dotnet build && dotnet test' for .NET). When absent, the clean step is skipped (backward compatible). The repo must actually provide the referenced scripts — e.g. build:fresh is not a standard npm script and must be declared in package.json. Can be overridden per-repo via repos[].review.clean_verification
empty_verdict_auto_approve
boolean
true
Auto-approve when the LLM returns an empty or unparseable verdict and all deterministic checks passed
scope_drift
object
—
Scope-drift detection settings. When absent or enabled is not true, scope-drift detection is disabled (default). Informational only — never auto-blocks. Global-only field; cannot be overridden per-repo in the first iteration
scope_drift.enabled
boolean
false
Enable plan-vs-PR scope-drift detection in the reviewer. When true, the reviewer computes and surfaces a diff between the analyzer’s planned file set and the PR’s actual changed files
Every review — per-change, external PR (review.external_prs) and epic — sees the whole change. The old review.max_diff_lines line budget and the 80,000-character cap are gone (a config that still sets review.max_diff_lines, at the top level, under repos[] or under tenants[].repos[], loads and logs one deprecation warning; the key is ignored).
Ceiling. The sanitized diff (lockfile and binary hunks collapsed to one line each, nothing cut) is inlined whole, in its original order, when it is at most 1,000,000 characters (REVIEW_INLINE_DIFF_MAX_CHARS, a code constant shared by all three review paths, not a config key).
Manifest. The prompt always carries a manifest immediately before the diff: one line per changed file with its change kind, lines added and removed, and class (production, test, docs or generated).
Above the ceiling. No diff text is inlined. The reviewer gets the manifest plus the full diff written inside the review worktree (.colony-review-diff.patch) and reads it with Read, Grep and Glob. The file is removed when the run ends. Per-change reviews put the concurrent base-branch diffs in .colony-review-concurrent.patch whenever the main diff is on disk, or whenever the change diff and the concurrent diffs together exceed the ceiling.
Other inputs. The exploration report, scope-drift file lists, parent-epic context, dependency changelog and the verdict-only fallback input are no longer truncated.
File accounting. The reviewer must list every production file of the manifest in the files array of its verdict, as reviewed or as out_of_scope with a non-empty reason. Test, docs and generated files are never required.
Coverage line. Every per-change approve and request-changes body and every external review body carries one line: accounted ÷ changed production files, whether the diff was inlined or read from disk, and any unaccounted files.
Escalation. A per-change APPROVE that leaves a production file unaccounted is not posted. The run escalates to a human (a comment naming the files, the needs-human label, escalate_human) — never an action item or REQUEST_CHANGES. A verdict the reviewer could only give in prose (natural-language fallback) carries no files and therefore escalates too whenever production files changed. Other verdicts are unchanged, and the next round accounts for the files again. An external-PR APPROVE with an unaccounted production file posts as a Comment even with auto_approve: true.
Used by review.external_prs. Controls how Colony handles PRs that are not part of its own pipeline (i.e., PRs not on colony/issue-N branches). The feature is disabled by default (mode: off). See External PR Review for a usage guide covering all three modes.
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 the PR. on_ready — automatically when a PR is opened or transitions from draft to ready. auto — same triggers as on_ready, with the auto_approve flag available
author_filter
string[]
['*']
Allowlist of GitHub usernames to review. ['*'] means any author. Set to a specific list to limit reviews to those users
label_filter
string[]
[]
Require all listed labels to be present on the PR before reviewing. Empty list means no label requirement. Multiple labels use AND semantics — all must be present
exclude_bots
boolean
true
Skip PRs authored by bot accounts (GitHub user type 'Bot')
exclude_drafts
boolean
true
Skip draft PRs
auto_approve
boolean
false
With mode: auto, a passing (APPROVE) LLM verdict posts a formal GitHub Approve review event. Otherwise (any other mode, or left false) a passing verdict posts a neutral Comment review carrying the same summary. Colony logs a startup warning if set to true without mode: auto. Independent of empty_verdict_auto_approve (auto_approve never applies when the reviewer left a changed production file unaccounted for: that APPROVE is posted as a Comment naming the file — see Diff visibility and file coverage)
Configures the Colony agent processes. Each agent type extends a common set of fields. Agents run as standalone processes (singletons) or as part of the per-repo worker pool.
Claude effort level for this agent. Not present on agents.developer — the developer resolves effort from claude.scaling[tier].effort or a workflow station-declared value instead.
Whether to pick up all new issues or only colony-tagged ones
heartbeat_timeout_minutes
number
5
Minutes before reclaiming stale tasks from workers that stopped heartbeating. Must be > 0 (0 would reclaim every in-flight task). Should be ≥ agents.workers.stale_task_threshold (default 3): a lower value logs a warning on startup and reload, and the sprint-master reclaim uses the larger of the two. The reclaim runs once per poll interval per sprint-master process, across all tenants’ tasks
sweep_cooldown_minutes
number
10
Minutes to suppress re-enqueueing a sweep task after completion (0 to disable)
label_sync_limit
number
25
Max issues to reconcile labels for per poll cycle
item_panel_revisit_limit
number
20
Open items whose item panel is re-checked per repo per poll when they had no transition or operator event (catches changes to human-wait keys, needs-human reasons and inherited constraints). Items with a transition or operator event since the last sweep are always re-checked. Reloads live.
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
auto_unblock_quota
boolean
true
Automatically re-queue quota-blocked issues after their reset time has passed
max_auto_unblocks_per_cycle
number
3
Max issues to auto-unblock during one sprint-master cycle
health_stale_after_seconds
number
30
Integer ≥ 0. Seconds without a main-thread health snapshot (pushed every 2 s) before GET /health returns 503 with stale: true. 0 disables the check. Needs a restart
mayor_timeout_seconds
number
20
Hard per-message timeout (integer, 1–300) for the Mayor’s single-turn call. A timed-out message gets a holding reply plus a hand-off work task that composes the full reply. The hand-off runs on a worker and composes its reply with the analyzer role model, not conversation; it has no dedicated model key
startup_poll_concurrency
number
8
Max repos running first-poll (startup) or /wake-triggered poll work at once (integer, ≥ 1). Startup first polls are spread evenly across one poll interval, and the startup comment warm-up (tracked or Colony-labelled issues only) fetches at most this many issues’ comments at once
startup_clone_concurrency
number
4
Max repo clones (each preceded by an emptiness probe) the sprint-master runs at once after startup (integer, ≥ 1). /health is served before any clone starts. A repo whose probe or clone fails, or that is empty, is reported under repoClones in /health and retried with exponential backoff (1 min, doubling, capped at 30 min) while the other repos proceed; a repo starts polling once its clone is ready. Repos with repos.active = FALSE are not cloned
active_repo_reconcile_interval
number
60
Seconds (integer, ≥ 5) between re-reads of repos.active. A configured repo enabled with colony repos enable starts polling within one interval (track-store upgrade, asynchronous clone, then a first poll through the startup_poll_concurrency bound); a disabled repo stops polling, its timer is cleared and its in-memory state is dropped once any in-flight poll finishes. If the read fails, the current set is kept. Repos added to or removed from the config still need a restart
mayor_max_concurrent
number
4
Global cap (integer, 1–64) on Mayor calls in flight. A message over the cap is not queued: it gets a holding reply plus a hand-off work task
retrospective_max_concurrent
number
4
Process-wide cap (integer, 1–64) on blocked-retrospective Claude CLI calls in flight across all repos. A repo at the cap skips its retrospective for that poll without waiting and retries on a later poll; the issue spends no attempt
mayor_enabled
boolean
true
Kill switch. false turns the Mayor off entirely: addressed messages get today’s non-Mayor handling (the canned clarification reply, no model call, no hand-off)
mayor_issue_messages_per_hour
number
10
Max addressed messages the Mayor handles per issue per rolling hour (integer, 1–1000). Over the limit there is no model call and no hand-off; one rate-limited reply is posted per hour window
mayor_sender_messages_per_hour
number
5
Max addressed messages the Mayor handles per sender (across repos) per rolling hour (integer, 1–1000). Over the limit behaves as above. A denied sender gets at most one denial reply per issue per hour
auto_unblock_cooldown_minutes
number
10
Per-issue cooldown before auto-unblocking the same issue again
max_auto_unblocks_per_issue
number
3
Lifetime automatic unblock limit per issue before escalation
full_sync_interval
number
10
Every N poll intervals (N × poll_interval, about 5 min at the 30 s default), perform a full provider sync instead of cache-only reads; wake-triggered polls don’t count
full_sync_interval_active
number
50
Full-sync interval in poll intervals (about 25 min at the 30 s default) after webhooks have been active for enough cycles
full_sync_active_threshold
number
5
Consecutive webhook-active cycles before switching to full_sync_interval_active
webhook_inactivity_minutes
number
15
Minutes without webhook events before falling back toward full polling behavior
queue_starvation_threshold_hours
number
24
Hours a pending task may wait before a starvation warning is logged (0 disables)
orphan_recovery_cooldown_minutes
number
5
Per-issue cooldown before re-enqueuing orphan recovery work (0 disables)
code_map_scan_interval_hours
number
24
Hours between periodic code-map scans for repos with code_map.enabled. The interval is measured from the repo’s last scan or check stored in Postgres, so it survives restarts and deploys. A default branch whose HEAD and scanner version are unchanged is checked, not rescanned
work_task_retention_days
number
31
Days to retain completed work_tasks rows before pruning
cost_raw_retention_days
number
unset
Opt-in retention for raw cost_events and execution_telemetry rows (integer, minimum 32, which keeps the calendar-month budget readers getTenantMonthlyCost and getRepoMonthlyCost whole; recommended 400). Unset keeps every row (removing the key from a running config takes effect only after a restart). Lifetime totals are preserved by the daily rollups. Rows are deleted in batches of 5000 per table, at most hourly, and only when the row’s UTC day is before the rollup watermark, is older than the window, and belongs to an issue that has been done for longer than the window (or is a repo-scoped cost_events row). Once set, these per-issue readers see only retained history: getIssueCost and getCostEvents (issue timeline, colony inspect, epic summary, calibration check); getExecutionTelemetry (colony why, MCP diagnose); cost percentiles and calibration; the regression guard’s issue_costs query; the analytics period report’s issue_costs average cost and turns; the epic-review reviewer/developer cost split; MCP estimate (a fully pruned done issue shows $0 and drops out of the percentiles) and the MCP issues cost column; and the external v1_cost_events view. Lifetime totals exclude cost rows with no resolvable repo, matching the rollup. Rolled-up cost follows an issue to its current repo, but telemetry rollups keep the repo the issue had when they were rolled up. Pruning assumes done issues receive no further cost: if a done row is reopened, its pruned history is lost to getIssueCost and per-issue cost caps.
utilization_rollup_enabled
boolean
true
Enable once-per-UTC-day rollup of worker utilization into worker_utilization_daily
auto_repair_stale_blocked
boolean
false
Automatically clear stale is_blocked flags with no active dependency edge. Only touches dependency-scoped (block_reason = 'dependency') or reason-less blocks; failure and circuit-breaker blocks (merge_conflict, cost_cap, review_cycle_limit, …) are never auto-repaired. Reuses the max_auto_unblocks_per_issue cap; a flapping issue escalates to needs-human.
auto_repair_stale_subtask_edges
boolean
false
Automatically resolve stale subtask dependency edges on completed epics. Reuses the max_auto_unblocks_per_issue cap; a flapping issue escalates to needs-human.
Runaway backstop: skip LLM resolution when conflict files exceed this count. The primary gate is semantic complexity (LLM-judged), not this cap.
max_conflict_regions
number
150
Runaway backstop: skip LLM resolution when conflict regions exceed this count. The primary gate is semantic complexity (LLM-judged), not this cap.
timeout
number
300
Timeout in seconds for conflict resolution
model
string
claude.models.merger (then claude-opus-5-5)
Override model for conflict resolution
auto_merge_high_confidence_resolutions
boolean
true
Automatically merge when the LLM judges the conflict semantically simple, all files resolve at high confidence, and independently re-run review.checks pass. Set to false to always hand back.
Minutes, rolling window for error rate calculation
max_task_duration
number
45
Minutes before alerting on a long-running task
max_replica_pause_minutes
number
30
Minutes a nomad replica may stay paused before a replica_paused alert; a replica paused past this threshold also counts as unavailable in fleet shortfall (0 disables the alert, and paused replicas are then judged on heartbeat alone)
How often to refresh consistency findings. The orphan check lists open issues from the provider once per repo per interval; repair endpoints re-query only the affected repo from the store. Must be > 0.
repo_active_reconcile_seconds
number
60
How often to re-read repos.active; repos disabled in the DB are dropped from per-repo polling and reporting until re-enabled (min 5). Disabling a repo also turns off dashboard issue actions (unblock/retry/cancel/transition, consistency repair, track edits) and item-comment alerts for it until re-enabled, and hides its pending tasks from the task-queue panel
sweep_cooldown_minutes
number
10
Minutes to suppress re-enqueueing a sweep task after completion (0 to disable)
agent_health_host
string
'localhost'
Host for polling agent health endpoints
long_lived_state_ceiling_hours
number
24
Stall threshold in hours for paused, auto-recovering blocked, and open-children items
human_wait_ceiling_hours
number
72
owed_to_human threshold in hours for other awaiting-human items
human_wait_reminder_hours
number
24
Hours between repeat owed_to_human comments while an item stays waiting; the first posts when human_wait_ceiling_hours is crossed
Sprint-master and the webhook-receiver also re-check repos.active, on a fixed 60-second interval that is not configurable. A repo disabled while sprint-master runs stops being polled and no tasks are enqueued for it; a repo enabled at runtime is picked up without a restart and polled immediately. Webhook events received while a repo is disabled are dropped, not replayed: the first sprint-master poll after re-enable reconciles instead.
slack — Posts Block Kit messages to a Slack incoming webhook. Set url_env to the name of the environment variable containing the webhook URL.
pagerduty — Sends Events API v2 triggers. Set routing_key to the PagerDuty integration routing key (literal value, not an env var).
webhook — POSTs a JSON payload to any HTTP endpoint. Set url_env to the name of the environment variable containing the URL.
github_issue — Creates a GitHub issue labeled colony:alert in the first configured repo. No additional fields required.
item_comment — Posts a comment on the referenced work item for item-scoped alerts (dead-letter digests, failed-projection audits, SLA warnings). This channel is the default for sprint-master item-addressed alerts, but only when no other sink resolves: with alert_channels empty or absent, or when every configured entry is skipped (for example slack without a URL), it is the sole channel. Configuring a resolvable slack, webhook, pagerduty or github_issue channel replaces it. To receive both a sink and item comments, list { type: item_comment } explicitly; it is then built at its listed position. Comments carry the colony:operational marker so auto-unblock paths skip them correctly.
The alert_cooldown (minutes) controls deduplication — each unique alert ID is only dispatched once per window. The cost_alert_threshold fires a warning when aggregate daily or monthly spend exceeds the configured USD amounts.
Every alert carries a fixed class, persisted as metadata.alertClass on the stored alert. action means the alert owes an operator an action (“do something or it stays broken”); report means a number moved. A new detector must declare one.
Detector
Scope
Class
agent_down
deployment
action
pipeline_stall
deployment
action
high_error_rate
deployment
report
projection_queue_backlog (deprecated)
repo
report
long_running_task
item or repo
report
repeated_reclaim
item or repo
report
cost_threshold
deployment
report
token-expiry
repo
action
issue_stall
item
report
owed_to_human
item
action
blocked_issue_threshold
deployment
report
dead_letter
deployment (deprecated), item (digest)
action
stuck_projections (deprecated)
deployment
report
failed_projections (deprecated)
deployment
action
failed_projection
item
action
consistency
deployment
action
kpi_regression
repo
report
fleet_shortfall
tenant
action
replica_paused
tenant
action
outbox_stalled
repo
action
dead_letters
repo
action
budget_breach
repo
action
daily_cost_ceiling
tenant
action
stale_issue
item
report
sla_breach
item
report
intake_failed
item
action
circuit_breaker (trip)
repo
action
circuit_breaker_reset (all-clear)
repo
report
token_expiry (worker)
repo
action
fatal_worker
repo
action
Item comments. The item_comment channel treats the classes differently. An action alert posts a new comment every time it is delivered. A report alert keeps one standing comment per item and detector: the first delivery posts it, and each later delivery revises that comment, ending it with a _Last raised: <timestamp>_ line. If the first post was suppressed (an operator-audience comment on a comment_policy.customer_facing repository), is still pending, or was never recorded, later deliveries write nothing. Without a pipeline store or tenant, a report alert posts a new comment, as action does.
Sinks. Colony does not route by class; each sink receives the tag and the operator routes on it. webhook posts a top-level alertClass in its JSON. slack adds *Class:* action|report to the context line. pagerduty sets custom_details.alert_class. github_issue adds a **Class:** line to the issue body.
Maximum automatic unblocks per issue before requiring manual intervention (used by auto_repair_stale_blocked)
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
Note: Transient auto-unblock (formerly auto_unblock_transient on this config) is now exclusively the sprint-master’s responsibility. Configure it via agents.sprint_master.auto_unblock_transient.
Used by agents.monitor.regression_guard. Controls the pipeline-health regression guard that detects KPI degradation over rolling windows.
Field
Type
Default
Description
enabled
boolean
false
Enable the regression guard
current_window_hours
number
24
Hours in the recent (current) measurement window
baseline_window_days
number
7
Days in the baseline measurement window
relative_threshold
number (0–1)
0.25
Fractional degradation that counts as a regression
min_samples
number
20
Minimum sample floor — regressions are not reported below this count
kpis
Record<RegressionKpi, boolean>
{}
Per-KPI enable flags; omitted keys are disabled
KPI regression directions — a regression is flagged when the metric moves in the bad direction beyond relative_threshold:
KPI
Regresses on
block_rate
rise
failure_blocked_rate
rise
review_pass_rate
fall
mean_cost_per_issue
rise
mean_turns_per_issue
rise
reimplement_loop_rate
rise
dead_letter_rate
rise
The REGRESSION_DIRECTION const exported from @colony/core encodes this mapping as a runtime value — downstream compute code should import it rather than re-deriving the direction.
This block is hot-reloadable via POST /api/config/reload. A partial reload merges only the specified keys and preserves all unspecified fields (including nested kpis entries).
Per-repo worker pool configuration. Workers claim tasks from the Postgres work_tasks queue and dispatch to executor libraries. This section is optional — omit it when using standalone agent processes.
Field
Type
Default
Description
Common fields
—
Inherits enabled, poll_interval, health_port from Common AgentConfig Fields; defaults depend on deployment configuration
heartbeat_interval
number
—
Seconds between task heartbeats. Workers send heartbeats to the Postgres queue to signal liveness — if a worker stops heartbeating for longer than sprint_master.heartbeat_timeout_minutes, the task is reclaimed. Must be > 0, and 2× the interval must be below stale_task_threshold×60, heartbeat_timeout_minutes×60 and 120s (default 30)
max_task_retries
number
3
Max failures for a repo+issue+taskType combination within 60 minutes before dropping re-enqueue
max_task_duration
number
45
Minutes before a task execution is considered timed out and aborted
max_task_reclaims
number
3
Minimum 1. Hot-reloadable. Lease-loss reclaims (stale-heartbeat resets to pending) a single task may accumulate. Once a task has been reclaimed this many times, the worker fails it before dispatch and blocks the issue with the transient lease_loss reason. /colony:retry creates a fresh task whose count starts at 0
stale_task_threshold
number
3
Minutes before a claimed task without a heartbeat is reclaimed by another worker. Increase this if long-running pre-LLM setup steps (e.g. merging a branch far behind main) regularly exceed the default
speculative_workspace_prep
boolean
false
Pre-create worktrees for pending develop tasks while the worker is idle
unknown_tenant_retry_minutes
number
5
Minutes to retry an unrecognised COLONY_TENANT at nomad startup (exponential backoff) before exiting non-zero. Covers a fresh deployment where the tenant row isn’t seeded yet when the replica starts, without masking a genuine typo forever
Note: The resolution chain applies to multi-repo deployments using repos[]. For single-repo setups (the default), all settings are configured at the top level — no per-repo overrides are needed. See Multi-Repo (Colony Cloud) for details.
When a field can be set both globally and per-repo, Colony resolves the value using this fallback chain:
repoConfig.<field> ?? config.<field> ?? default
The per-repo value takes precedence when set; it falls back to the global value, then to the built-in default. The following helper functions in packages/core/src/config.ts implement this pattern for specific fields:
Controls Colony’s self-improvement feature, which allows Colony to file issues against itself.
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
max_open_issues
number (≥1)
5
Total concurrently-open SI issues for this repo, split between the operator and strategy pools (see strategy.capacity_share and seeding pools); each pool seeds its tracks in weight-proportion until its share of the cap is reached
Controls epic decomposition and completion behavior.
Field
Type
Default
Description
use_feature_branches
boolean
false
Create and use an epic feature branch for grouped subtask work
rebase_strategy
'on-complete' | 'periodic' | 'never'
'on-complete'
When subtask branches should be rebased while an epic is in progress. With periodic, a refresh merge head that fails required CI files a remediation subtask on the epic branch while the epic is waiting for subtasks, or triggers CI repair on the epic PR after finalization
auto_merge_subtasks
boolean
true
Automatically merge approved subtask PRs whose base is an epic integration branch. false leaves an approved subtask PR for a human instead of merging it
Highest review finding severity that can trigger automatic remediation. Also controls whether a partial acceptance-criteria gap is treated as minor: with 'none', a partial gap has no in-session auto-fix path to catch it, so it stays major and blocking (routes to REMEDIATE/ESCALATE) instead of silently falling below blocking_severity. With 'minor', a minor partial gap routes to a remediation subtask rather than AUTO_FIX, because criteria gaps carry no file location for the in-session fix’s scope guard.
max_remediation_cycles
number
3
Maximum automated remediation cycles before escalation
require_human_final_review
boolean
true
Require a human final review after automated epic review/remediation completes
coverage_floor
number
0
Fraction (0-1) of the epic’s changed production files the criteria pass must have accounted for (listed as reviewed, or out_of_scope with a reason). Below this floor the reviewer escalates to a human instead of approving, since it cannot vouch for a verdict it lacked the evidence to reach. 0 disables the floor. Independently of the floor, any unaccounted production file turns an APPROVE into an ESCALATE (unreviewed_files).
blocking_severity
'minor' | 'major'
'major'
Severity at or above which a finding classified real forces a REMEDIATE/ESCALATE route. A minor finding below this threshold is not blocking, but remains eligible for the AUTO_FIX route independently of this setting when auto_fix_threshold is 'minor'. See Classify-then-route synthesis.
adversarial
boolean
false
Enables the second (adversarial/hostile-second-opinion) LLM review pass alongside the criteria pass. When false, only the criteria pass runs — its claude.execute call, cost, and events — and the adversarial execution-failure/parse-failure escalations and verdict combination are all skipped. The deterministic coverage, dead-code, and test-integrity guards run either way; a coverage- or dead-code-guard finding can still force REQUEST_CHANGES regardless of its label, and a test-integrity finding does so unless the classifier dismisses it, in which case it escalates for human corroboration. The posted review comment records whether the adversarial pass ran.
ci_defer_max
number
3
Maximum deferrals for one epic review. When the only escalation reason is an execution-shaped unverified_criterion and the reviewed head’s CI is still pending, the review is deferred and resumed when checks complete instead of escalating. After this many deferrals it escalates unverified_criterion as usual.
ci_defer_max_wait
number
7200
Maximum time, in seconds (same unit as review.ci_check_timeout), one epic review may stay deferred waiting for CI before it escalates unverified_criterion.
polish_followup
'file' | 'log'
'file'
What happens to open non-blocking (polish) findings. file: when the epic’s change merges, Colony creates one non-enqueued follow-up issue listing every open polish finding not yet filed. log: the reviewer’s approval comment lists the findings and no issue is created; when the epic merges they are marked logged and resolve like other findings (run /colony:followup before the merge to file them anyway). /colony:approve followup|no-followup overrides this setting for a single epic.
auto_fix_protected_paths
string[]
['**/migrations/**']
Minimatch globs the in-session AUTO_FIX must not change. If the fix touches any matching path (including new untracked files), its changes are discarded, nothing is pushed, and the findings go to a remediation subtask; the review comment names the protected paths (auto_fix_touched_protected_path). The developer’s forbidden_paths and read_only_paths always apply in addition, so setting [] removes only the migrations default. Overridable per-repo via repos[].epic.review.auto_fix_protected_paths, which replaces this value for that repo.
auto_fix_max_changed_lines
integer
150
Maximum added plus removed source lines the in-session AUTO_FIX may change (positive integer); test, documentation and changelog lines are not counted. Before anything is pushed, Colony also requires the fix to touch only files cited by the routed findings plus their tests, documentation (docs/**, *.md, CHANGELOG.md) and index.* barrels in a cited file’s directory or its parents, to contain no formatting-only hunks and no new exports outside test files, docs and cited files (a barrel may re-export from a cited module), and to pass every blocking review.checks command in the review worktree. On any violation the changes are discarded, nothing is pushed, and the epic is approved with the minors as polish findings — except under blocking_severity: 'minor', where those minors are blocking and go to a remediation subtask instead. The guards run again on the rebased commit if the push has to rebase onto a moved branch. If the push errors or times out, Colony checks the remote branch: a fix that reached it is verified in the same run, and an unknown remote state retries the review. Overridable per-repo via repos[].epic.review.auto_fix_max_changed_lines.
Note:coverage_floor is opt-in (0) because the unaccounted-file check below already escalates any APPROVE with an unreviewed production file; the floor adds a threshold on the ratio itself. Enable it deliberately once you’ve observed what ratio your epics normally achieve.
Epic review always reviews the whole epic diff; the old line budget, character cap and test-file deprioritisation are gone, and epic.review.max_diff_lines has been removed (a config that still sets it loads and logs one deprecation warning). The sanitized diff (lockfile and binary hunks collapsed to one line each) is inlined whole, in its original order, up to a ceiling of 1,000,000 characters (REVIEW_INLINE_DIFF_MAX_CHARS). Both the criteria and the adversarial prompt carry a manifest with one line per changed file (change kind, lines added and removed, and class: production, test, docs or generated). Above the ceiling, no diff text is inlined: the reviewer gets the manifest plus the full diff written inside the review worktree (.colony-epic-review-diff.patch, and .colony-epic-review-delta.patch for an over-ceiling adversarial delta), and reads it with Read, Grep and Glob. The files are deleted before any auto-fix session and when the review ends.
File accounting. The criteria pass must list every production file in the manifest in its files array, as reviewed or as out_of_scope with a non-empty reason. A production file that is not accounted for turns an APPROVE into an ESCALATE with reason unreviewed_files (it never becomes a remediation finding), and the comment names the files. Unaccounted test, docs and generated files are ignored. The coverage ratio used by coverage_floor is accounted ÷ changed production files (1 when there are none).
Epic review runs its criteria pass (and the adversarial pass, when adversarial is enabled), normalizes their output into findings, then synthesizes a verdict in two stages:
Classify (LLM). Each normalized finding is labeled real, non-actionable, stale, already-satisfied (the cited code is still present but is no longer defective, as distinct from stale, where the cited code is gone), or unsatisfiable-criterion (the finding maps to an acceptance criterion that cannot be satisfied as specified by anyone — valid only on a criteria-pass gap, and only when the classifier states a non-empty reason; without one the label is discarded and the finding is treated as real). This stage only assigns labels — it never decides what happens next, and it never decides whether a finding is a recurrence of a prior cycle’s finding (see the deterministic recurrence check below).
Route (deterministic code).routeClassifications() (packages/reviewer/src/epic-router.ts) maps the classified findings, the criteria pass’s coverage ratio, and a deterministic recurrence lookup (computed by the caller, not the classifier) to exactly one of four routes:
Route
Meaning
APPROVE
No actionable real finding — nothing at or above blocking_severity, and no minor finding eligible for auto-fix; the epic PR is approved
AUTO_FIX
Every actionable finding is minor and auto_fix_threshold is 'minor'; the reviewer fixes them in-session and pushes to the epic branch instead of spawning a remediation subtask (if the fix touches an auto_fix_protected_paths path it is refused and the findings go to a remediation subtask). This still consumes one of max_remediation_cycles. Minors are eligible for AUTO_FIX independently of blocking_severity, so this route is reachable at the default config. On the final remediation cycle (when no cycle would remain after the fix) with nothing blocking, the epic is approved instead (final_cycle_minor_only) and the minors are recorded as polish findings, since an auto-fix there could only escalate.
REMEDIATE
Any genuinely new blocking finding (major, or a coverage- or dead-code-guard finding at any label) spawns a remediation subtask — a finding that maps to a criterion renders as a - **Gap**: bullet, an unmapped one as a - **Integration**: bullet, in the same subtask. Auto-fix-eligible minors are never bundled in here — they’re below blocking_severity and are already persisted separately as non-blocking polish findings
ESCALATE
Coverage is below coverage_floor; or the criteria pass did not account for every changed production file (unreviewed_files — an APPROVE that would otherwise stand, escalated without a remediation finding; like unsatisfiable_criterion it is checked ahead of the max_remediation_cycles cap, so it reports its own reason at the cap); or a stale/non-actionable/already-satisfied-labeled adversarial finding or criteria-pass integration issue at or above blocking_severity was the only thing this cycle would otherwise have raised (unverified_dismissal — see below); or every otherwise-blocking finding already has an active prior-cycle record at or above blocking_severity (a deterministic fingerprint recurrence, not a classifier label — already tracked from a prior cycle and still unresolved); or a criteria gap was labeled unsatisfiable-criterion with a stated reason (unsatisfiable_criterion) — this reason is checked before the dismissal and recurrence rules (the coverage_floor check still runs first), escalates on the first cycle that raises it rather than only after repeated cycles, and is the only reason evaluated ahead of the max_remediation_cycles cap check, so it still surfaces its own distinct reason when the cycle count is already at the cap; like every ESCALATE, it consumes no remediation cycle, since a defective criterion needs a human edit and no additional cycle substitutes for one; it is never a dismissal and can never itself produce APPROVE; a human reviews
The model can mislabel a finding, but it cannot choose the route directly — a hallucinated classification can at worst point routing at the wrong (deterministic) rule, never bypass the rules themselves, for every finding source. Coverage-guard and dead-code-guard findings are always blocking regardless of their LLM label, and criteria-pass gap findings (a missing/partial acceptance criterion) carry the same protection — all three are collected before the label-based settle step, so a stale/non-actionable/already-satisfied mislabel can never demote one of them out of routing (a criteria gap still falls into the blocking or auto-fix-eligible bucket purely by its own severity, never dropped from routing entirely). Test-integrity-guard findings are deliberately label-gated instead: deleting a test is frequently correct, and an immune finding on an intended deletion would be unclearable — it would re-derive from the same diff every cycle until it escalated. They are major, so one the classifier labels real still blocks, and a dismissal at or above blocking_severity forces ESCALATE (unverified_dismissal) for human corroboration on the first cycle rather than spending remediation cycles on a diff no subtask can change. Adversarial findings and criteria-pass integration issues (no criterion, unlike a gap) aren’t re-collected the same way — a stale/non-actionable/already-satisfied label on one of them drops it from routing like any other dismissal, and if something else this cycle is still actionable that surviving work routes normally. But if such a dismissal at or above blocking_severity is the only thing this cycle would otherwise have raised, the route would silently become APPROVE with no deterministic backstop; instead it forces ESCALATE (unverified_dismissal) for human corroboration, so a single third-pass label can never turn a major adversarial finding into a silent approval. stale and already-satisfied findings below that floor are dropped before routing and never spawn a remediation subtask, since the cited code is either gone or already correct.
Recurrence is handled the same way regardless of finding source, including guard findings and criteria gaps (which the label-based settle step can never touch): epic-review.ts looks up every classified finding’s fingerprint against prior-cycle agent_findings records once per cycle and passes the resulting set into the router as recurringFingerprints. A finding whose fingerprint already has an active (non-dismissed) prior-cycle record never itself spawns a new remediation subtask; if it’s the only thing an otherwise-clean pass would have raised and it was itself at or above blocking_severity, the router escalates (repeated_blocking_finding) instead of approving an epic with a known, still-open blocking finding, or re-remediating a finding that already has an active subtask — a recurring minor finding below the threshold was never blocking and still routes to APPROVE (or AUTO_FIX, if otherwise eligible). A genuinely new blocking finding alongside a recurring one still spawns a remediation subtask for the new item alone.
“Blocking” is defined by a written rubric, not by whatever severity the model assigns. Each finding carries a rubric_category; the rubric text is rendered verbatim in the criteria, adversarial, classify and auto-fix prompts.
Blocking (stays major)
Not blocking (minor, a polish follow-up)
criterion-not-met — an acceptance criterion is not met
edge-case — edge-case robustness
integration — the subtasks don’t integrate (contract or data-flow mismatch, missing wiring, combination-only breakage)
hypothetical-race — hypothetical races
primary-path-regression — a correctness regression on the primary path
retry-idempotency — retry or idempotency polish
security-data-loss — a security, data-loss or corruption risk (this is what “critical” means; there is no critical severity)
observability
tests-weakened — tests deleted or weakened without justification
performance — no measured regression; style; docs
The classify pass applies the rubric deterministically. A major finding is downgraded to minor only when all of these hold:
its source is the adversarial pass, or it is a criteria-pass integration issue (a criteria-pass finding with no criterion);
its rubric_category is a not-blocking category;
its downgrade_reason is non-empty.
Everything else keeps its severity: a finding in a blocking category stays major even when a reason is given (the downgrade is discarded; severity is never raised), as do a missing or unknown category (recorded as uncategorized), an empty reason, and every other source. Criteria gaps and coverage-guard findings are always criterion-not-met, dead-code-guard findings integration, and test-integrity-guard findings tests-weakened, whatever the classifier returns.
A downgraded finding keeps its original severity (downgradedFrom: major) and the reason, is never auto-fixed, and is persisted as non-blocking polish with metadata.rubricCategory and metadata.severityDowngrade. At the default config an epic whose only major finding was downgraded is approved; if the criteria pass returned REQUEST_CHANGES with every gap addressed and every major integration issue downgraded, the run approves rather than escalating no_actionable_finding, and the outcome event still records the REQUEST_CHANGES verdict. Under blocking_severity: minor a downgraded finding still meets the blocking threshold, because that is what the operator configured. The classification table shows it as major → minor with its category.
Integration scope of the adversarial pass. Each subtask was already reviewed on its own, so the adversarial pass is scoped to cross-subtask contracts and data flow, wiring between subtasks, combination-only behaviour and regressions on the epic’s primary path. For each adversarial finding with a cited line, the reviewer blames that line and reads the Refs: #M trailer of the introducing commit (older commits: the feat: implement #M — … subject); the subtask number is recorded as introduced_by_subtask on the finding evidence (null when unknown). A major adversarial finding attributed to a single subtask is downgraded to minor with the reason single-subtask (introduced by #M); adversarial pass is integration-scoped and persisted as polish, unless its category is security-data-loss (an uncategorized finding is also kept blocking). Attribution is accepted only when every blamed commit is in the epic’s merge-base..head, the subtask is a child of the epic, and the whole cited range lies in the epic diff and blames to that one child. integration, criterion-not-met and criterion-mapped findings are never downgraded by this rule. Findings with no location, unknown attribution (squash merges, commits without a Refs: trailer, lines committed before the epic or outside developer commits) keep their severity.
Verification mode. A review runs in verification mode when a usable baseline exists: epic_reviewed_head_sha is set and the pass that persisted it accounted for every production file it was asked to review (recorded in a separate operational_state marker). It does not depend on epic.review.adversarial. The criteria pass then sees only the delta since the baseline head, plus the prior blocking findings to re-check, instead of hunting over the whole epic diff again, and the unreviewed_files check counts only the delta’s production files. The review comment states the mode (verification (baseline <short sha>) or full (<reason>)), and the epic_review_outcome event carries reviewMode. A full review runs instead, with the reason named in the comment, when there is no baseline (no_baseline), the completeness marker is missing, 0 or unreadable (incomplete_baseline), the head SHA is unavailable (head_unavailable), the baseline is not an ancestor of the head after a force-push or rebase (not_ancestor), the base branch was merged in since the baseline and the delta cannot be computed without the base-branch changes (base_drift: when the base was merged in, the delta is computed against a synthetic merge of the baseline with the base commit the head contains, so it shows only epic-side changes; base_drift applies only when that synthetic merge conflicts or cannot be computed), the delta is empty (empty_delta), or a git fetch or diff fails (git_error). /colony:review (like retry and reimplement) clears epic_reviewed_head_sha, so it forces a full review. The adversarial pass keeps its own gating and takes the delta only when it is enabled and the baseline was itself adversarially reviewed. Because each later cycle only has to confirm that prior findings are fixed and that the latest change added no regression, the review converges instead of finding new work in old code each time, so the default max_remediation_cycles: 3 should be enough.
For a conceptual overview of how findings promote into repo intelligence and how retrospectives feed lessons back into the knowledge base, see Findings, Intelligence & Retrospectives.
Used by intelligence.reconcile. Controls embedding-based deduplication: when a candidate intelligence item has a cosine similarity above reinforce_threshold to an existing item of the same kind, the existing item’s observation count is incremented rather than inserting a duplicate. Falls back to plain insert when embeddings are unavailable (null vector).
Field
Type
Default
Description
reinforce_threshold
number
0.9
Cosine-similarity threshold for semantic deduplication (0–1; higher = stricter matching)
Used by intelligence.retrieval. The multi-source repo-intelligence retrieval service selects, ranks, and budgets snippets from findings, intelligence items, retrospectives, and the code map. It always runs and its snippets are always injected into the prompts of all five agents (analyzer, planner, developer, reviewer, retrospector) whenever a Pipeline Store is wired. The former enabled, inject and agents keys were removed; a config that still sets them loads, logs a deprecation warning and ignores them. code_map.inject still decides whether code_map snippets appear in the ranked section.
Field
Type
Default
Description
token_budget
number
1200
Bounds the per-run prompt growth: the rendered Repo Intelligence section is at most this many estimated tokens (default 1,200; must be ≥ 1)
max_snippets_per_source
number
5
Maximum snippets returned per source before cross-source ranking (must be ≥ 1)
similarity_threshold
number
0.3
Cosine similarity floor for the embedding-based recall signal (0–1)
re_enrichment_enabled
boolean
false
Enqueue re-retrospect tasks for detected legacy low-fidelity intelligence items (detection always runs; this flag gates the task enqueue)
Every retrieval persists its cost and per-source outcome in repo_intelligence_retrieval_events. token_estimate is the estimated tokens of the rendered Repo Intelligence section. source_states says, per source, whether it searched or why it could not (never_scanned, unsupported_language, empty_corpus, and so on). Run this to see the last week by agent:
Used by intelligence.embedding. Configures the embedding provider that computes semantic vectors for intelligence items. Only openai is supported today (uses text-embedding-3-small); reuses OPENAI_API_KEY already documented for the codex block.
Field
Type
Default
Description
enabled
boolean
false
Enable embedding computation (safe to leave false until backfill runs)
provider
'openai'
'openai'
Embedding provider (currently only openai is supported)
Distinct from agents.merger / executors.merger — this block gates analysis passes that run before the merge step (pre-merge checks and semantic-conflict detection). It does not configure the merger agent itself.
This block is hot-reloadable via POST /api/config/reload. Workers pick up changes live without a redeploy.
How Colony merges a PR. A per-repo repos[].merge.method replaces it. Epic PRs into the default branch, and subtask PRs into epic/* branches, always use a merge commit (the latter keep per-commit Refs:/Colony-Remediation: trailers for epic review). Colony sets the merge commit title to the PR title and the message to a condensed brief (what the change does, the change list, Closes #N); rebase keeps the original commits, so GitHub ignores the title and message. For repos where humans merge, enable GitHub’s “Default to pull request title and description” squash setting.
Used by merge.semantic_conflict_check. Gates the semantic-conflict analysis pass that detects concurrent changes to different files that are semantically coupled (e.g. one issue renames a config key while another adds a consumer of the old key). Default off — nothing changes for existing deployments until enabled: true is set.
Field
Type
Default
Description
enabled
boolean
false
Enable the semantic-conflict analysis pass
min_confidence
number
0.75
LLM confidence threshold (0–1) at/above which the later PR is deferred for re-review
max_candidate_branches
number
10
Maximum concurrent branches to compare against — runaway backstop
model
string
—
Optional model override for the focused semantic-conflict assessment
lookback_hours
number
24
How far back (hours) to consider recently-merged branches when scanning for semantic conflicts
Controls which planned files count when Colony decides whether two in-flight issues overlap. Hot-reloadable. repos[].overlap replaces the top-level value for that repo, key by key.
Key
Type
Default
Description
ignore_union_merged
boolean
true
Ignore paths the repo marks merge=union in .gitattributes. Only exactly union exempts; custom drivers, -merge and binary do not. Set false to opt out.
ignore_paths
string[]
[]
minimatch globs relative to the repo root (dot: true, same semantics as forbidden_paths). Each must be a non-empty string.
List in ignore_paths only files whose concurrent edits merge trivially: append-only changelogs and fragment directories. Files marked merge=union are already covered by the default.
Do not list lockfiles (conflicts need regeneration), generated files such as schema/colony.config.schema.json, or migration directories (two branches can pick the same number). Ignored paths stay in planned_files; they are only skipped when comparing issues.
Gates the per-issue in-flight message mailbox: durable, per-issue storage of operator messages addressed to an agent that is already running. When an agent invocation finishes, undelivered mailbox messages are delivered by resuming the same session with a prompt presenting them as operator feedback, before the executor acts on the result (commits/pushes, posts a verdict, persists output). Implemented once at the shared agent-invocation layer (runWithMailbox), so it applies uniformly to the analyzer, developer, reviewer, planner, and merger.
Codex limitation:runWithMailbox calls the same resume(sessionId, prompt) interface on both providers, but the Codex engine’s resume is currently a stub that always returns a failure result — Codex never gets mid-run or mid-resume mailbox delivery. The helper degrades cleanly: on Codex, undelivered messages simply stay in the mailbox and are folded into the next run’s prompt as operator feedback (the pre-run pickup path, which does not depend on resume). Implementing Codex session resume is tracked separately and is out of scope here.
This block is hot-reloadable via POST /api/config/reload. Workers pick up changes live without a redeploy.
Field
Type
Default
Description
enabled
boolean
true
Master gate for mailbox delivery across all agents. On by default so delivery works the moment producers (#9251/#9252) enqueue a message — the cost is one or two indexed queries per agent invocation against an empty mailbox until then. Operators can still opt out per agent via agents.<role>.enabled: false
max_resume_rounds
number
3
Maximum resume rounds per invocation — bounds how many times a run may be resumed to flush newly-arrived messages (minimum 0; 0 disables resume rounds but keeps next-run pickup)
Deprecated:intake_rules is a tenant-wide key and is superseded by per-repo repos[].workflows, which lets each repo declare its own activated workflow set and routing rules. Setting intake_rules emits a startup deprecation warning. See Resolution precedence below and docs/user-guide/workflows.md for the current routing mechanism. Removing this key entirely is tracked as a separate follow-up; it is not yet removed.
Declarative per-issue workflow routing. When present, Colony evaluates rules in order at intake time and routes each issue to the first matching rule’s workflow. If no rule matches, the default workflow is used.
intake_rules only takes effect for a repo that has norepo_workflows rows (i.e. no repos[].workflows configured) — see Resolution precedence.
This block is hot-reloadable via POST /api/config/reload. The sprint-master picks up changes live without a redeploy.
intake_rules:
default: colony-default# required — workflow id used when no rule matches
rules: # optional — evaluated in order, first match wins
- workflow: colony-content
match:
labels: [content] # matches if the issue carries ANY of these labels (OR)
title_pattern: '^\[docs\]'# optional — regex tested against issue title
- workflow: colony-docs
match:
issue_type: documentation# optional — matches GitHub issue type / node id
body_pattern: 'RFC-\d+'# optional — regex tested against issue body
Deprecated:default_workflow is a tenant-wide key and is superseded by per-repo repos[].workflows (set a member’s default: true). Setting default_workflow emits a startup deprecation warning. See Resolution precedence below and docs/user-guide/workflows.md. Removing this key entirely is tracked as a separate follow-up; it is not yet removed.
Selects a builtin workflow as the repo-level default. When set, resolveWorkflowForRepo materializes the named builtin at the config tier — above a repo-committed .colony/workflow.yaml — so a cloud-side selection reliably overrides a repo-local file.
default_workflow: colony-content# or colony-default (the default when absent), colony-support
Valid values:colony-default, colony-content, colony-support. colony-dependabot is rejected because it is pinned in code.
Hot-reloadable via POST /api/config/reload — sprint-master picks up changes live without a redeploy.
Note: This is a repo-default selector, not a per-issue routing mechanism. Use intake_rules for per-issue label-based routing (both deprecated — prefer repos[].workflows). default_workflow only takes effect for a repo that has no repo_workflows rows — see Resolution precedence.
Controls the strategist station: when it fires, how it runs, and which repos it covers. The cadence is cron-only (5-field expression, evaluated in UTC); the default is 0 3 * * 1 (Mondays 03:00 UTC). The interval cadence kind is no longer supported and is rejected by config validation.
On startup, Colony reads the last-persisted next_due_at from the database and fires a catch-up cycle immediately if the time has passed — so restarts never silently delay a weekly cycle.
strategy:
enabled: true
cadence:
kind: cron
expr: '0 3 * * 1'# default: Mondays 03:00 UTC
max_turns: 40
effort: high
stagger_window_minutes: 60
repos:
- owner: acme
repo: legacy
strategy:
enabled: false# opt this repo out
The model comes from claude.models.strategist (default claude-opus-5-5). agents.strategist.engine, if set, must be claude-code — Codex refuses readRoot, which the station needs.
StrategyConfig fields:
Field
Type
Default
Description
enabled
boolean
true
Enables the strategist station. Resolves repo first (repos[].strategy.enabled), then global, then default
cadence.kind
'cron'
cron
Cron only — interval is rejected. Global only
cadence.expr
string
0 3 * * 1
5-field cron expression (UTC); required when cadence is present. Global only
max_turns
integer (≥ 1)
40
Max Claude turns per strategist run. Global only
effort
'low' | 'medium' | 'high' | 'max'
high
Reasoning effort for the strategist run. Global only
stagger_window_minutes
integer (1–10080)
60
Window across which per-repo runs are staggered. Global only
capacity_share
number (0–1)
0.5
Share of self_improvement.max_open_issues for strategy tracks; only applies with an active charter. Also settable per repo (repos[].strategy)
default_cooldown_minutes
integer (≥ 1)
60
Cooldown for strategy tracks created by strategy apply. Also settable per repo
default_selection_mode
'human' | 'auto:first' | 'auto:preferred'
human
Selection mode for strategy tracks created by strategy apply. Also settable per repo
approval
'human' | 'auto'
human
human: an operator approves each proposed snapshot. auto: a valid proposal is approved and applied as actor auto. Also settable per repo
Each of the seeding keys (capacity_share, default_cooldown_minutes, default_selection_mode, approval) resolves repo first, then the global strategy block, then the default. They are per-repo (repos[].strategy) and hot-reloadable (replace, not merge). capacity_share must be between 0 and 1; default_cooldown_minutes must be an integer ≥ 1; approval must be human or auto. See Strategy approval and lifecycle and Seeding: pools, shares and menus.
enabled and each seeding key (capacity_share, default_cooldown_minutes, default_selection_mode, approval) can also be stored in the repo_configs.strategy column (JSONB object, NULL = not set) so a host can set them without a config redeploy. Per key, the store value wins, then repos[].strategy, then the global strategy block, then the default. Invalid keys in the column are dropped with a warning naming each one; global-only keys (cadence, max_turns, effort, stagger_window_minutes) and unknown keys are ignored.
Hot-reloadable — every key is replaced on reload (an absent key falls back to its default); the scheduler reads the cadence each tick, so no restart is needed.
See strategy.md for the full strategize cycle documentation.
Colony workers support an optional operator-mounted credential file at /colony/keys/credentials.yaml. When present, the container entrypoint runs scripts/render-credentials.sh before starting any agent process. The rendered config files authenticate package manager clients against private feeds (Azure DevOps Artifacts npm registries and NuGet feeds).
The /colony/keys volume already exists in the default container setup (it also holds the GitHub App private key).
Missing file — If /colony/keys/credentials.yaml does not exist, render-credentials.sh exits 0 silently. No warning is logged, and all agents start normally.
Schema mismatch — If schema is not 1, the entrypoint exits non-zero with a message naming the offending file. No agent process starts. Fix the YAML and restart the worker.
Missing PAT — If credentials.azure_devops.pat is absent or null, the entrypoint exits non-zero with a clear error. Fix and restart.
Empty feeds — Zero feed entries is not an error; entrypoint exits 0.
Credential values — The renderer never logs token values. Log output only reports the count of entries written (e.g., render-credentials: wrote 2 npm credential entries to ~/.npmrc).
Edit /colony/keys/credentials.yaml on the host and restart the worker container. The entrypoint re-renders all credential files from scratch on each start — stale entries from a previous run are replaced.
Credentials are never baked into image layers. The /colony/keys directory is operator-mounted at container run time. Rendered config files (~/.npmrc, ~/.config/NuGet/NuGet.Config) are written inside the running container’s filesystem with mode 0600 and do not persist across restarts.
On networks that perform TLS interception (corporate proxies, Zscaler, Palo Alto, and similar), every outbound HTTPS connection is re-signed by an internal CA that the system trust store does not recognize. Without trust propagation, every npm install, dotnet restore, az login, and curl call fails at the TLS handshake — before authentication is even attempted.
Executor-specific settings that belong to the execution logic of each agent type (distinct from agent process infrastructure such as poll_interval and health_port).
If executors is not set, values are auto-populated from the corresponding agents.* fields for backward compatibility via populateExecutorsFromAgents() in config.ts. This cascade does not happen when any repo sets repos[].workers; see per-agent keys alongside repos[].workers.
Workflow YAML and task inputs: Executors can receive typed inputs forwarded from a preceding stage via the outputs block in .colony/workflow.yaml — this is separate from colony.config.yaml. For the outputs block syntax, per-task-type input schemas, and merge semantics, see the Executor Contract Reference.
forbidden_paths and read_only_paths let operators restrict which files the developer agent may access or modify. The enforcement happens at the tool call level — the agent receives a hard error rather than a prompt-level suggestion.
forbidden_paths — the agent cannot read or write these paths. Use for secrets, credentials, and other files the agent should never see (e.g. .env*, secrets/**).
read_only_paths — the agent can read these paths for context but cannot edit them. Use for IaC definitions, generated migration files, and CI workflows (e.g. infrastructure/**, .github/workflows/**, **/Migrations/**).
Example:
executors:
developer:
forbidden_paths:
- 'secrets/**'
- '.env*'
read_only_paths:
- 'infrastructure/**'
- '**/*.bicep'
- '**/*.bicepparam'
- '.github/workflows/**'
- '**/Migrations/**'
Paths are repo-relative and use minimatch glob syntax with { dot: true } (so .env* matches .env). Empty or unset lists mean no enforcement — behavior is identical to deployments without these keys.
Cascade: values set under agents.developer are cascaded into executors.developer by resolveConfig(). At runtime, executors.developer is the authoritative source. The cascade is skipped when any repo sets repos[].workers; in that case agents.developer.forbidden_paths and read_only_paths are ignored (see per-agent keys alongside repos[].workers).
Hook glob engine limitation: the PreToolUse hook script that enforces the lists at tool-call time uses a custom glob-to-regex engine that does not support brace expansion ({a,b}). Use separate list entries instead — e.g. '**/*.bicep' and '**/*.bicepparam' rather than '**/*.{bicep,bicepparam}'. The reviewer diff check uses minimatch directly and does support brace expansion.
Bash detection limitation: the hook pattern-matches common shell write idioms (>, >>, tee, sed -i, cp, mv, cat <<HEREDOC >) and read idioms (cat, less, head, tail, grep, source), but is best-effort. It misses variable expansion ($DEST), subshell paths ($(get_path)/file), and quoted paths with spaces. The reviewer diff check (which scans the actual PR diff) is the reliable safety net.
Advanced: This section is for operators who need to white-label Colony’s slash-command surface. Most users do not need to configure this block. Skip it on your first read.
Controls the root keyword used in all slash commands that Colony posts to GitHub issue comments and PRs. By default every command uses the colony prefix (e.g. /colony:retry, /colony:help). Setting commands.root replaces that prefix across all agent-posted comments and the webhook receiver’s command parser.
Field
Type
Default
Description
root
string
'colony'
Slash-command root keyword (e.g. 'pipeline' makes /pipeline:retry work). Must match ^[a-z][a-z0-9-]*$, max 32 characters.
authorization
'write' | 'any'
'write'
Who may drive the pipeline from comments. 'write' requires the sender to have write access to the repository; 'any' accepts any non-bot commenter (the behaviour before sender authorization existed).
commands.authorization is evaluated by evaluateSenderAuthorization in @colony/core, which asks the provider for the sender’s authority (write, read, none or unknown). Only write is allowed when the setting is 'write'; with 'any' no lookup is made. Results are cached per repository and login for 60 seconds. An unknown result (the lookup failed) is never cached and never allowed — the sender gets a reply naming the reason (and the missing permission when one is plausible) rather than a silent drop.
GitHub. Colony calls GET /repos/{owner}/{repo}/collaborators/{username}/permission. GitHub’s permissions-required-for-GitHub-Apps reference lists this endpoint under the repository permission Metadata: read, so the App must have it. admin, maintain and write count as write access; triage and read do not. A webhook author_association of OWNER is used as a fast path; COLLABORATOR, MEMBER and CONTRIBUTOR are always checked against the permission endpoint, because outside collaborators can hold read or triage access. A 401, 403 or 404 from the endpoint is reported as unknown with the likely missing permission (Metadata: read). 5xx responses, network errors and rate limits are reported as unknown transient failures that name the HTTP status where there is one, without naming a missing permission. Neither kind is cached.
Azure DevOps. Colony resolves the sender by account name or email (display names are not unique, so a sender known only by display name is reported as unknown) and reads their transitive group memberships from the Identities API (queryMembership=Expanded, on vssps.dev.azure.com). It then reads the Git Repositories security namespace ACLs through the Access Control Lists – Query API for the repository token and its ancestors (repoV2/{projectId} and repoV2). Permissions granted to the sender’s groups, and those inherited from the project-level and organization-level tokens, are honoured; a lower-level explicit setting overrides an inherited one, and a deny on the user or on any of their groups blocks write. The sender needs the Contribute Git repository permission (GenericContribute, bit 4) effectively allowed and not denied. The PAT used by Colony needs the scopes Identity (Read) (vso.identity) for the identities lookup and Security (Manage) (vso.security_manage), which Microsoft lists for Access Control Lists – Query. If the lookup fails, or the identity cannot be resolved uniquely, the sender is reported as unknown.
Clarification replies are gated too (behaviour change). With the default 'write', a reply to a clarification question only resumes the issue when its author has write access. An issue reporter without write access — the usual case for public or externally filed issues — can no longer answer Colony’s questions: their reply gets a one-time notice and the issue stays in needs-clarification until a collaborator replies (or an operator uses /colony:state). Set commands.authorization: 'any' to keep the previous behaviour. Comments from bot accounts (*[bot]) are ignored as replies without a lookup or notice. Refused replies are counted by colony_clarification_reply_authorization_denied_total{outcome,repo} on the monitor; refused slash commands by colony_webhook_slash_command_authorization_denied_total{outcome} on the webhook receiver.
Custom ProviderAdmin implementations.ProviderAdmin.getSenderAuthority is optional so implementations outside this repo keep compiling. An admin that does not implement it reports every sender as unknown, so under 'write' all comment commands and clarification replies are refused with a reply naming the reason. Implement it, or set 'any'.
Override, not alias. Setting commands.root: pipeline means /pipeline:retry works and /colony:retry stops working. The original root is not preserved as a secondary alias — Colony accepts only the configured root.
What changes. All slash commands rendered in agent comments (analyzer, developer, reviewer, merger, planner, sprint-master) and the webhook receiver’s command parser use the configured root. Operators and humans must use the new root when interacting with issues.
What does NOT change. GitHub labels are unaffected. State labels (e.g. colony:analyzing, colony:blocked) and inbound label commands (colony:enqueue, colony:paused) remain colony:-prefixed regardless of commands.root. To rename labels, use the separate labels.prefix option. See GitHub Labels for the full label vocabulary and the labels.prefix option.
Not hot-reloadable.commands.root is read at process startup. Changing it requires restarting both webhook-receiver and sprint-master to take effect. Live reloading via POST /api/config/reload does not apply to this field.
Validation. The value is validated at startup by colony check. The accepted pattern is ^[a-z][a-z0-9-]*$ with a maximum length of 32 characters: lowercase letters and digits only, starting with a letter, hyphens allowed. Invalid values abort startup with a clear error.
root: pipeline# /pipeline:retry, /pipeline:help, etc.
Forward-looking note:commands.root is preliminary work toward per-workflow trigger words. When Colony adds support for multiple workflows in a single environment, each workflow will be able to use a distinct slash-command root to route interactions independently.
Colony Cloud supports managing multiple repositories from a single Colony instance using repos[] or tenants[] configuration. For single-repo deployments (the default open-source path), these sections are not needed — the flat github + workspace top-level config is all you need.
Multi-repo deployments list each repository under repos. Each entry configures authentication, workspace, and pipeline behavior for one repository. Config cannot have both top-level repos and tenants.
Field
Type
Default
Description
owner
string
required
GitHub organization or user that owns the repository
repo
string
required
Repository name
token_env
string
—
Name of the environment variable containing the PAT for this repo. Either token_env or app is required
Per-repo code-map (symbol index) settings, overriding the top-level code_map default. See fields below
sla
SlaConfig
—
Per-repo SLA thresholds, overriding the top-level sla default. See fields below
intake_mode
'all' | 'tagged'
—
Overrides the global agents.sprint_master.intake_mode for this repo. When set, only this repo’s intake behavior changes
workers
WorkerPoolConfig
—
Per-repo worker pool settings. See fields below
default_stewards
string[]
—
Code-host logins assigned to items Colony creates when no parent assignees exist. Also stored in the repo_configs.default_stewards column (TEXT[], NULL = not set) so a host can set it without a config redeploy. A non-NULL column overrides the YAML value at every station (intake, colony_import_plan, sprint-master-created items, workers); NULL falls back to YAML
dependabot
DependabotConfig
—
Per-repo Dependabot integration settings, overriding the top-level dependabot default. See fields below
This repo’s activated workflow set, synced into the repo_workflows table at sprint-master startup and on config reload. See fields below
claude
{ models?: { analyzer?, developer?, reviewer? } }
—
Repo-scoped per-role Claude model ids. Replaces the tenant-wide claude.models.<role> and the claude.scaling[tier].model default for this repo; model_routing, state-declared models and the kill-switch still win. Applies only when the agent’s engine is claude-code. See Model Selection
Can also be set at the top level of the config (pattern_memory: alongside github:/workspace:), giving every repo a shared default. Precedence is repoConfig.pattern_memory ?? config.pattern_memory ?? default, resolved by resolvePatternMemory (see Resolution Chain).
When neither tier sets a pattern_memory block, pattern memory is on with max_results: 3 and lookback_days: 30. A block you write must contain all three fields to pass schema validation, and max_results and lookback_days must be ≥ 1.
Field
Type
Default
Description
enabled
boolean
true
Enable pattern memory for this repo (required when the block is present)
max_results
number (≥1)
3
Maximum number of pattern results to include in prompts (required when the block is present)
lookback_days
number (≥1)
30
Number of days of history to search for patterns (required when the block is present)
Per-repo code-map (symbol index) settings. enabled turns on building the symbol index; inject decides whether it is rendered into prompts. See also agents.sprint_master.code_map_scan_interval_hours. Can also be set at the top level of the config, giving every repo a shared default; a repository that is too expensive to scan can still opt out locally. Precedence is repoConfig.code_map ?? config.code_map ?? default, resolved by resolveCodeMap.
Field
Type
Default
Description
enabled
boolean
false
Enable the code-map scan (scheduled sprint-master scan) and make the code map available as a retrieval source that is ranked and seeds the path query. When false, that source reports unavailable; retrieval itself still runs
inject
boolean
false
Emit code-map candidates as code_map snippets in the ranked Repo Intelligence section received by every retrieval consumer (analyzer, planner, developer, reviewer, retrospector). With false (shadow mode), candidates still seed the path query but no code_map snippets are rendered. See IntelligenceRetrievalConfig
token_budget
number
—
Accepted but currently has no effect. The section size is capped by intelligence.retrieval.token_budget (default 1200)
Can also be set at the top level of the config, giving every repo a shared set of thresholds. Precedence is repoConfig.sla ?? config.sla ?? undefined (unset — SLA warnings are opt-in), resolved by resolveSla.
Field
Type
Default
Description
warn_after_minutes
Record<string, number>
—
Map of pipeline state name (e.g. 'ready-for-dev') to the number of minutes before a warning is emitted. Only states that need a threshold need to be listed
Can also be set at the top level of the config, giving every repo a shared default. Unlike the other three keys, each field falls back independently: repoConfig.dependabot.<field> ?? config.dependabot.<field> ?? default, resolved by resolveDependabotConfig.
Field
Type
Default
Description
auto_review
boolean
false
Automatically trigger a review cycle for Dependabot PRs. When off, Colony does not review or merge Dependabot updates on its own, but a person’s Approve as-is (decision menu or colony_act approve) for the PR’s current head still merges it on green CI
auto_merge_patch
boolean
false
Patch updates: deterministic checks + green CI, no LLM review, then merge. Also lets LLM-approved patch PRs merge
auto_merge_minor
boolean
false
Minor updates: LLM review, merged only on approve (never skips the LLM). Also lets LLM-approved patch PRs merge when auto_merge_patch is off
auto_migrate_breaking
boolean
false
Controls only automatic adoption. A needed migration always holds the issue in human-review-ready with the decision menu, whatever this flag is set to; the hold overrides auto_merge_patch/auto_merge_minor routing, even for LLM-approved PRs. With the flag on, Colony picks the menu item only when the review’s recommendation is an Adopt option (adopt:<k>): it adopts with that option’s instructions (as /colony:adopt would), says so in the menu, and is limited by the adopted-once guard. It never approves or declines on its own. With it off, tick Adopt in the menu or run /colony:adopt yourself. The merge-authority flags still govern automatic merges; a person’s Approve as-is stands in for them
bot_usernames
string[]
['dependabot[bot]']
GitHub usernames to treat as Dependabot for triggering this integration
max_in_flight
number
3
Max non-terminal Dependabot tracking issues per repo. Untracked PRs beyond the cap wait for a later sweep, security PRs first, then lowest PR number
auto_merge_patch, auto_merge_minor and auto_migrate_breaking have no effect unless auto_review resolves to true for the repo; startup logs a warning when they do. Only Dependabot (dependabot[bot]) is supported: other bots in bot_usernames draw a startup warning. Tracking issues carry the colony:dependabot label, which you can use to filter them.
Merge authority. For Dependabot tracking issues (the colony-dependabot workflow), only the Dependabot flags authorize a merge. review.auto_merge_on_approval does not apply. The update type is re-derived from the live PR.
A same-tag Docker digest update (head branch dependabot/docker/…, both sides hex digests of 7–64 characters, optionally sha256:-prefixed) counts as a patch update; a tag change arrives as its own PR and is classified by its versions. GitHub Actions SHA pins and submodule bumps stay unknown.
Update type
auto_merge_patch
auto_merge_minor
Behaviour
patch
true
any
Deterministic checks + green CI, no LLM → approve → merge
patch
false
true
LLM review → merge only on approve
minor
any
true
LLM review → merge only on approve
patch / minor
not enabled for it
LLM review → on approve, human-review-ready (approved, not merged)
major (incl. 0.x) / unknown
any
any
LLM review → on approve, human-review-ready. Never auto-merged
An approved PR that the flags do not authorize moves to human-review-ready with a comment naming the flag that would have allowed the merge. The patch auto-approve step needs no LLM, so it still runs when no LLM is available.
Each open Dependabot PR is expected to have an open tracking issue while auto_review is enabled.
If an operator closes a tracking issue while its Dependabot PR is still open, Colony records a
decline (metadata.declined = true on the dependabot-pr link row — the system of record) instead
of re-filing a new tracking issue, and posts a comment on the PR for visibility. Re-filing is
suppressed until the PR is closed — Dependabot will reseed a fresh PR, which gets a fresh tracking
issue and is reviewed normally. Reopening the declined tracking issue while its Dependabot PR is still open
(/colony:reopen or a GitHub reopen) clears declined on the latest dependabot-pr link and
returns the issue to in-review, so automated review resumes. If the PR is already closed or
merged, the reopen is refused with a comment, and a GitHub reopen is closed again. Tracking issues that
predate the dependabot-pr link (identified only by a body marker) have no link row to carry a
decline, so closing one of those simply re-files a fresh tracking issue on the next sweep, restoring
tracking.
Declares this repo’s activated workflow set: the set of workflows intake can route an issue into, with exactly one designated default. Synced into the repo_workflows Pipeline Store table at sprint-master startup and on every config reload — intake reads the table directly, so a change takes effect on the next intake without a redeploy. This key is not part of ReloadableConfig; only the table sync (not an in-memory config field) reacts to a reload.
repos:
- owner: acme
repo: widgets
# ...
workflows:
- workflow_id: colony-default
default: true
- workflow_id: colony-content
match:
- labels: [content]
priority: 1
Ownership semantics (evaluated per repo on every sync):
workflows key present — the YAML is authoritative for this repo: its repo_workflows rows are replaced to exactly match, including removing any row not in the declared set.
workflows key absent — this repo’s repo_workflows rows are left untouched. Cloud-managed repos write rows directly and never declare this key.
workflows: [] — resets the repo to “nothing configured”: all rows are deleted and the repo falls back to colony-default.
A repo with no configured set (key absent and no rows in the table) behaves as the set {colony-default} with colony-default as the default.
Field
Type
Required
Description
workflow_id
string
Yes
A builtin workflow id or a custom (non-builtin) id, pinned by (workflow_id, version)
version
number
No
Pinned version. When omitted, resolves to the latest registered version for this workflow id
default
boolean
No
Exactly one member of a non-empty workflows array must set this to true
Workflow resolution (both the repo-level default and per-issue routing) checks these tiers in order, stopping at the first one that supplies an answer:
The repo’s repo_workflows activated set — declared via repos[].workflows above. When a repo has one or more rows, this tier is authoritative: non-default members are evaluated in priority order (first match wins), falling back to the set’s default member. The deprecated global keys below are never consulted once a repo has any repo_workflows rows.
The deprecated global intake_rules / default_workflow keys — only reached when the repo has zero repo_workflows rows. default_workflow resolves the repo-level default; intake_rules (if also set) then evaluates its rules against that default for per-issue routing.
colony-default — the final fallback when nothing above supplies a workflow.
Setting the deprecated tenant-wide intake_rules or default_workflow keys emits a single startup deprecation warning pointing at repos[].workflows. See docs/user-guide/workflows.md for a routing walkthrough.
Each entry in repos[] requires a workspace block. Fields here override the corresponding global workspace values for that repo using the fallback chain repoConfig.workspace.<field> ?? config.workspace.<field> ?? default.
Field
Type
Default
Scope
Description
repo_dir
string
required
overrides global
Path to the local git clone for this repo
base_dir
string
required
overrides global
Base directory for this repo’s worktrees. Supports {owner} and {repo} template tokens
setup_command
string
—
overrides global
Command to run after creating a worktree (e.g. 'bundle install'). Overrides the global workspace.setup_command. Prefer bash -c '...' over bash -lc '...' if a shell wrapper is needed
setup_timeout
number
300
overrides global
Seconds to allow the setup command to run. Overrides the global workspace.setup_timeout
prebuild_command
string
—
overrides global
Command to run after setup_command to pre-build workspace packages. Overrides the global workspace.prebuild_command
review_workspace_base
string
—
overrides global
Container-local path for ephemeral reviewer worktrees
skip_pre_push_hook
boolean
—
overrides global
Pass --no-verify to git push for this repo
branch
string
'main'
overrides global
Default branch name for this repo
secret_env_vars
string[]
—
per-repo only
Names of environment variables to resolve and inject into worker processes for this repo. Values of 8+ characters are replaced with [redacted:NAME] in check output, posted comments and stored transcripts; shorter values are not redacted
timeouts
TimeoutsConfig
—
per-repo only
Fine-grained clone and tooling timeouts. See fields below
Seconds before git submodule update --init is timed out
epic_review_push
number
300
Seconds before the epic reviewer auto-fix commit+push is timed out
epic_branch_merge
number
300
Seconds before each git step of an epic-branch merge (fetch, worktree add, merge, push; sprint-master and worker) is killed; a timed-out merge step counts as a conflict, any other step as a failed merge. The branch-write lock transaction is held for at most the lock wait plus about 6 × this value
remote_branch_check
number
30
Seconds before a remote branch presence or head check (git ls-remote) is abandoned. A timed-out presence check is treated as unknown: the dependency sweep does not count the branch as lingering, and cleanup and /reimplement do not delete it. Applies to the sprint-master; the synchronous check in the developer uses the same limit
retrospective_git
number
120
Seconds before each git command of the blocked retrospective (the git fetch and the repository-state facts: rev-list, diff --stat, merge-base, merge-tree) is abandoned. A timeout leaves out the ‘Verifiable Repository State’ section; the retrospective still runs. The fetch also aborts a transfer below 1000 B/s for 60 s
The review block inside a repos[] entry accepts an explicit subset of the global ReviewConfig fields. Only fields in the following pick list can be overridden per-repo:
Override the review check commands for this repo. Accepts the same string-or-object form as the global review.checks — a bare string is blocking; { command, blocking: false } makes the check report-only
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 to complete
ci_required_checks
string[]
Names of CI checks that must pass
ci_absent_check_grace
number
Seconds auto-merge waits for a required check with no run or status on the PR head before merging without it (default 600). A required check is also skipped as soon as every check suite and status on the head has finished without reporting it
format_command
string
Command to auto-format code before review. Colony formats only when this is set
clean_verification
string
Cache-defeating pre-handoff verification command (see global review.clean_verification for examples). When set, overrides the global value for this repo
Maximum number of LLM review rounds before giving up, for this repo. See the review section above for how a per-repo value interacts with the convergence check and hard-ceiling backstop
flaky_reruns
number
Times a failed blocking check is re-run on the PR tree before the baseline step, for this repo (0 disables; max 5)
ci_flaky_reruns
number
CI check runs that fail are re-run on the same head SHA this many times for this repo (0 disables; max 5)
flaky_quarantine_threshold
number
Flake count over the rolling 14-day window at or above which a blocking check is quarantined (advisory), for this repo (integer >= 1)
The following ReviewConfig fields are global-only and cannot be overridden per-repo: max_reimplement_cycles, empty_verdict_auto_approve, scope_drift.
Note: New fields added to ReviewConfig are not automatically per-repo-overridable. The pick list in RepoReviewConfig must be updated explicitly to expose them.
Multi-tenant deployments group repositories by tenant under tenants. Each tenant has its own GitHub App credentials and optional cost budget. Config cannot have both top-level tenants and repos.
Tenant-level GitHub App credentials for the ops identity
ado
object
—
Tenant-wide Azure DevOps credential ({ token_env: string; ops_token_env?: string }), threaded into each ADO repo’s resolved token. Satisfies the tenant auth requirement in place of app for an ADO-only tenant
anthropic_api_key_env
string
—
Name of the environment variable containing the Anthropic API key for this tenant. Overrides the global ANTHROPIC_API_KEY
provider
'anthropic' | 'foundry' | 'gateway'
—
Overrides claude.provider for this tenant. Omit to inherit the global claude.provider (built-in default: 'anthropic')
foundry
object
—
Per-tenant ClaudeFoundryConfig; overrides claude.foundry. Only used when the tenant’s effective provider is 'foundry'
gateway
object
—
Per-tenant ClaudeGatewayConfig; overrides claude.gateway. Only used when the tenant’s effective provider is 'gateway'
cost_budget
object
—
Cost budget settings for this tenant. See fields below
defaults
object
—
Default settings cascaded to repos in this tenant that do not override them. Currently supports timeouts (TimeoutsConfig)
Provider precedence: tenant provider override > global claude.provider > built-in 'anthropic'. Credentials resolve per provider — when provider: 'foundry', the tenant’s foundry.api_key_env is used; when provider: 'anthropic', the tenant’s anthropic_api_key_env is used.
Each tenant must define app, a tenant-wide ado credential, or have at least one repo in repos configured as a provider: 'ado' repo (which carries its own ado block). Each repo inside tenants[].repos must also define its own repo auth (token_env or app) unless it is configured as an ADO repo.
Example — two tenants on different providers:
tenants:
- id: acme
app:
app_id: 12345
private_key_path: /run/secrets/acme-app.pem
installation_id: 67890
anthropic_api_key_env: ACME_ANTHROPIC_KEY
repos:
- owner: acme
repo: app
token_env: ACME_GITHUB_TOKEN
- id: contoso
app:
app_id: 23456
private_key_path: /run/secrets/contoso-app.pem
installation_id: 78901
provider: foundry
foundry:
resource: contoso-azure-resource
api_key_env: CONTOSO_FOUNDRY_KEY
repos:
- owner: contoso
repo: platform
token_env: CONTOSO_GITHUB_TOKEN
Note: Per-tenant provider configuration is resolved at startup and is not hot-reloadable. The tenants block is excluded from ReloadableConfig — a full process restart is required to pick up provider changes.
When the tenant’s monthly_usd cap is exhausted, intake halts for every repo in the tenant. A signed
comment is intended to be posted on the first in-flight issue per repo (per-tenant-per-month cooldown to
avoid repeated comments), but in the current Sprint Master deployment inFlightIssues — the tracker the
comment-posting helper scans to pick a target issue — is never populated, so this remains log-only in
practice today: watch for the Tenant monthly budget exhausted, skipping repo warning rather than a
GitHub comment.
Individual repos can carry their own monthly cap, nested inside the tenant cap above. This field has no
YAML key, no CLI command, and — in this OSS distribution — no monitor/dashboard write path either; it is a
DB-only column (repo_configs.budget_cap_usd) surfaced to the runtime as ResolvedRepoConfig.budgetCapUsd
/ RepoContext.budgetCapUsd. Only a positive value acts as a gate — there is no separate enable flag,
the value’s positivity is the enable flag. A non-positive value (0 or negative) is treated the same as
NULL (the column default): no cap, no gating. This lets 0 be used as a safe “unset” encoding by any
external writer of this column without accidentally halting intake. Migration 130 is a read-only
report, not a data change: it identifies any pre-existing non-positive budget_cap_usd rows and emits a
row-count RAISE NOTICE naming the affected repo_ids, but deliberately does not rewrite them to NULL.
Earlier revisions of this migration did rewrite those rows, which turned out to be self-defeating —
a deployment that had used 0 as a permanent kill-switch would silently resume spending on the first poll
after upgrade, with the row already NULL and no record of which repos had been gated. Leaving the stored
value intact keeps it recoverable and keeps it visible to the runtime read-seam warnings described below,
which fire every process start for as long as the row stays non-positive — a NULLed row could never trip
them again. The migration’s RAISE NOTICE is forwarded to Colony’s own pino log at warn level by a
notice listener attached in Migrator.migrate() (packages/pipeline-store/src/migrator.ts), so it is
visible in Colony’s log stream even though Postgres’s default log_min_messages setting would otherwise
discard a plain NOTICE from the server log. Because the migration makes no data change, its message is
purely informational; the authoritative, ongoing signal is the runtime warn logged at each read seam
(adapter, cost store, worker config resolution) every time a non-positive cap is read and dropped — this
fires on every process start for a legacy row, not just once at migration time.
If the repo already has a repo_configs row (i.e. any DB-driven config feature — intake mode, review
checks, model selection, auto-merge — has ever been set for it), set the cap with a column-preserving
UPDATE:
UPDATE repo_configs SET budget_cap_usd = $2WHERE repo_id = $1;
review_checks and review_checks_disabled. An empty review_checks ('[]', the column default) means “unset”: the repo inherits the tenant’s review.checks, and a non-empty list replaces them. To run no review checks for a repo, set review_checks_disabled = true (migration 208, default false). The flag wins over any stored review_checks entries, self-validation skips its checks, and the review reports that checks were disabled for the repo.
If the repo has no repo_configs row yet, be aware that migration 031_tenant_config.sql gives every
other column a NOT NULL DEFAULT: a fresh INSERT materialises intake_mode = 'tagged' and
review_checks = '[]' (plus auto_merge = false) even though you only intended to set a budget cap. In
DB-driven-config deployments (where repoConfigRowToResolved reads this row into ResolvedRepoConfig),
those materialised defaults are propagated as real overrides — intake_mode = 'tagged' silently switches
the repo to label-gated intake (requiring colony:enqueue on every issue), while review_checks = '[]'
is harmless: it means “unset”, so the repo keeps inheriting the tenant’s review.checks. OSS YAML
deployments read budget_cap_usd directly via getRepoBudgetCap and never invoke the adapter, so these
defaults are inert there. If you are on a DB-driven-config deployment and inserting a fresh row, set
intake_mode explicitly to your intended value in the same statement. Leave review_checks as '[]' to
inherit the tenant’s checks, supply a JSON array of {"name": ..., "command": ...} objects to replace
them, or set review_checks_disabled = true to run none, e.g.:
-- review_checks '[]' means "unset": the repo inherits the tenant's review.checks.
-- Non-empty entries replace the tenant's checks. To run no review checks at all,
-- also set review_checks_disabled = true.
INSERT INTO repo_configs (repo_id, budget_cap_usd, intake_mode, review_checks)
VALUES (
$1,
$2,
'all',
'[{"name":"test","command":"npm test"},{"name":"lint","command":"npm run lint"}]'
)
ON CONFLICT (repo_id) DO UPDATESET budget_cap_usd =EXCLUDED.budget_cap_usd;
Managed/cloud deployments may layer their own dashboard or API on top of this column.
At each poll, the tenant cap (cost_budget.monthly_usd) is checked first and still binds across the whole
tenant as described above. If the tenant cap has room, a second, narrower check runs against the
individual repo’s budget_cap_usd: when a repo’s own monthly spend reaches its cap, new-issue intake
and the New→Analyzing advance halt for that repository only — sibling repos in the same tenant keep
polling normally, and every other lifecycle step for the capped repo (merged/closed PR detection, label
projection from Postgres, stale-task reclamation, dependency unblocking, worktree pruning, and the rest)
continues to run so in-flight issues keep being serviced. The repo-cap check is logged with a
Repository monthly budget exhausted, skipping repo warning (structured with repo, spentUsd,
limitUsd) every time it trips. Unlike the tenant scope, the repo scope is user-visible: a
<!-- colony:repo-budget-exhausted:YYYY-MM -->-marked comment is posted on each skipped issue —
distinct skipped issues each receive their own comment. Both the poll path (posting on the
lowest-numbered new-state issue for the repo) and the webhook intake path (posting on the specific
issue whose intake it just gated) call the same shared helper, which serialises on a single
Postgres-backed bot_dedup_keys atomic claim keyed (repoId, issueNumber, 'repo-budget-exhausted', 'YYYY-MM') — issueNumber is the real gated issue, so the gate is one-per-issue-per-month, closing the
race only when both paths target the same issue (e.g. a poll and a webhook racing on the same
newly-opened issue). Whichever producer’s claim wins the INSERT ... ON CONFLICT DO NOTHING posts the
comment; another producer racing on that same issue/month sees created: false and skips posting. If the
comment post itself fails after the claim is won, a transient GitHub error (5xx, connection reset or
timeout, HTTP 429, or a GitHub 403 secondary-rate-limit/abuse-detection response — the classes
isRetryableError recognises) is normally absorbed by the write service’s own projection retry queue — it
returns without throwing, the claim is intentionally retained, and the queued projection re-posts later —
so no explicit release is needed for that path. The claim is released (best-effort DELETE) only when a
transient error is actually thrown (e.g. a write service constructed without a projection store), so the
next poll or webhook targeting that issue retries the post. A permanent (non-retryable) failure — auth,
validation, not-found, or a generic 403 — keeps the claim so the doomed write is attempted at most once per
(repo, issue, month) rather than being retried every poll cycle. A generic 403 stays non-retryable
deliberately: only the narrower secondary-rate-limit/abuse-detection message shape is treated as transient,
so a genuinely revoked or invalid token does not retry forever.
A claim being held (created: false) does not always mean a comment was actually posted — a crash or
SIGTERM landing between winning the claim and completing the write leaves a durable claim with no
comment. Both producers pass a getComments callback into postRepoBudgetExhaustedComment, which uses it
to self-heal this case: on created: false, it reads the claim’s posted_at, and when that timestamp is
more than 5 minutes old (a live producer posts within seconds, never minutes) it attempts a self-heal.
The self-heal itself is gated by a second, distinct bot_dedup_keys claim — kind
repo-budget-exhausted-selfheal, same (repoId, issueNumber, 'YYYY-MM') key shape — won via the same
atomic INSERT ... ON CONFLICT DO NOTHING as the original claim, and only the winner fetches comments and
checks the marker before proceeding to post. The original repo-budget-exhausted claim is never deleted,
so there is no delete/re-insert window for two concurrent recoverers to double-post. Because the self-heal
claim can only be won once per (repo, issue, month), this bounds the whole flow to at most one post plus
at most one self-heal re-post per (repo, issue, month) — including when the post itself is silently
suppressed (e.g. a customer-facing repo) or fails permanently, which leaves the marker absent forever but
does not turn into a per-poll retry loop: the second and later stale calls lose the self-heal claim and
short-circuit before fetching comments, so the getComments GitHub call also runs at most once per (repo,
issue, month). Neither path retains its own in-memory cooldown for this scope any more; the marker check
here is narrowly scoped to the self-heal path, not a general substitute for the PG claim.
The comment is best-effort, not a guarantee of delivery: the poll path only fires if a new-state issue
is already present in Postgres when the cap trips. In a poll-only (webhook-degraded) deployment, newly
opened GitHub issues are gated by intakeIssues before ever being written to Postgres, so they never
populate that candidate list. If no new-state issue happens to already be stranded in PG, a tripped cap
in that deployment mode produces no comment from the poll path — only the Repository monthly budget exhausted, skipping repo warning log — though the webhook intake path does not have this gap, since it
always has a concrete issueNumber to comment on the moment intake for that issue is attempted. Because
the dedup claim is now per-issue rather than per-repo, if both paths happen to target the same issue
concurrently, whichever wins the claim posts and the other skips; if they target different issues, each
still gets its own comment.
Both getRepoBudgetCap and getRepoMonthlyCost match owner/name case-insensitively and
deterministically select a single repos row (ORDER BY r.id LIMIT 1) — the same row for both queries —
so the cap and the spend total are always drawn from the same repo and never summed across multiple
tenants’ rows that happen to share an owner/name (repos only enforces UNIQUE(tenant_id, owner, name),
not global uniqueness). getRepoBudgetCap additionally returns a discriminated result distinguishing a
repos-row lookup miss (no row matched at all — e.g. an owner/name casing mismatch against the stored row,
or the repo hasn’t been seeded into repos yet) from a deliberately cleared cap (a row was found with no
cap set). A lookup miss is non-authoritative: it never clears an already-known cap or its fail-closed
protection (see below) — only a confirmed cap-cleared result does.
Per-repo spend is authoritative from the database: Sprint Master re-reads the repo’s total monthly cost
(getRepoMonthlyCost) and re-seeds the tracker every poll cycle, rather than deriving it from a
process-global cost delta. The re-seed overwrites the tracked spend with the DB total, including
downward movement — an issue transferred out of the repo or a corrected/deleted cost event lowers the
repo’s monthly total, and the tracker mirrors that drop on the very next poll. A repo that was gated
therefore un-gates within the same month once its DB total falls back below the cap, keeping the poll-path
gate consistent with the webhook path (which reads live DB spend directly on every intake event). The cap value itself
(budget_cap_usd) is likewise re-read from the database every poll, so a direct-SQL cap change takes
effect without a restart. The same repo_spend value is also exposed on Sprint Master’s /health endpoint
(alongside the existing tenant_spend) for observability.
The cap and spend reads are assigned atomically — both-or-neither — so a failure partway through this
hydration (e.g. the cap read succeeds but the spend read throws) can never leave a live cap paired with a
stale or unseeded spend value. Sprint Master also tracks, in memory, the last cap value actually observed
for each repo during its current process lifetime, seeded from two sources: every successful poll-cycle
hydration, and — re-checked before each poll’s hydration attempt, though it only has an effect the first
time (before either source has populated the record for that repo) — any cap already present on the repo’s
context (RepoContext.budgetCapUsd), which in DB-driven-config deployments is itself populated at startup
from ResolvedRepoConfig.budgetCapUsd. A hydration failure is
treated as gated (fail-closed) only for a repo that has previously been observed to carry a cap (via
either source): for that repo, intakeIssues and the New→Analyzing advance are skipped for that one poll,
and no repo-budget-exhausted comment is posted, since the spend/cap figures are stale and not authoritative
that cycle. Consequently, a repo whose startup-resolved config already carries a cap gates immediately on
its very first post-restart poll if that poll’s hydration fails — it does not need a prior successful
poll-cycle read to be treated as capped. A repos-row lookup miss (repoFound: false) is handled the same
way as a hydration failure with respect to the existing cap: it is not treated as “cap cleared”, so the
poll leaves ctx.budgetCapUsd and the last-observed-cap record exactly as they were (the spend read is
simply skipped for that poll, since there is no confirmed cap to pair it with) — this is what keeps a
config-seeded cap and its fail-closed protection from being silently discarded by a transient lookup miss.
A hydration failure for a repo that has never been observed to
carry a cap through either source — a fresh process’s first poll for a repo whose resolved config has no
cap, or a repo that has simply never set one — does not gate; the repo falls through fail-open, since
gating every repo in the deployment (including ones that never set a cap) off a single read failure would
silently halt all new-issue intake behind nothing but a log line. Both outcomes emit a pipeline error
event so the failure is observable regardless of which way it resolves. Every other lifecycle step (merged/
closed PR detection, label projection, stale-task reclamation, and the rest) continues servicing in-flight
issues regardless of which branch is taken. Hydration is retried on the next poll; note that the in-memory
last-observed-cap record resets on process restart, so a capped repo whose cap is not reflected in its
startup-resolved config (e.g. an OSS YAML deployment with no ResolvedRepoConfig.budgetCapUsd path, where
the cap is only ever known via the DB read) will fail open for its very first post-restart poll if that
poll’s hydration fails, rather than gate.
The webhook intake path (handleIntake, the primary route that creates paid analyze/plan work) applies
this identical fail-closed-for-observed-capped / fail-open-for-never-capped rule off the same in-memory
last-observed-cap record — Sprint Master hands the webhook path the same Map instance the poll path
writes to, so an observation made by one path (a successful hydration, or a config-seeded cap) is visible
to the other. A getRepoBudgetCap/getRepoMonthlyCost failure on the webhook path for a repo previously
observed as capped therefore also fails closed: the event is treated as handled without upserting the issue
or enqueueing work, leaving it for the poll-cycle fallback to pick up once the DB recovers. A failure for a
repo never observed as capped fails open, same as the poll path, and both branches emit the same pipeline
error event. This closes the gap where a DB degradation could previously disable the cap only on the
route that actually creates new paid work.
When present, enables nomad mode for the tenant: a fixed pool of roaming workers claims tasks from any repo in the tenant rather than being pinned to one. Absent = per-repo behavior (default, unchanged).
In nomad mode, pool_size is a desired replica count (an orchestration input), not an in-process fork count. Combining tenants[].workers with repos[].workers.pool_size on any member repo is rejected at config load time.
Field
Type
Default
Description
pool_size
number (integer ≥1)
required
Desired replica count for nomad workers in this tenant
memory
string
—
Container memory limit for worker processes (e.g. '4g', '6G')
health_port_start
number
—
Starting port for sequential health-check endpoint allocation
max_cached_repos
number (integer ≥1)
4
LRU cap on warm RepoContexts per nomad worker. Limits idle worktree memory usage per worker
max_cache_disk_mb
number
—
Disk budget in MB for warm clone checkouts per nomad worker. When set, eviction runs until both max_cached_repos and this budget are satisfied, not just the count cap. Unset preserves count-only eviction
max_mirror_disk_mb
number
20480
Disk budget in MB for the persistent per-tenant object-store mirrors under /colony/objects/<tenant>/.... Unlike max_cache_disk_mb, mirrors are otherwise never reclaimed and grow with every repo ever cold-started. The default budget applies when unset. When exceeded, the least-recently-refreshed mirror not referenced by a cached clone is removed
max_toolchain_disk_mb
number (integer ≥1)
—
Disk budget in MB for the mise toolchain directory (MISE_DATA_DIR, default /usr/local/share/mise). When exceeded after a cold start, installed tool versions not required by any warm or in-flight repo (nor by the global /etc/mise config, nor baked into the image — listed in /etc/colony/mise-baseline.json, overridable via COLONY_MISE_BASELINE) are uninstalled, oldest install first, until under budget. Unset disables pruning. Not hot-reloadable: requires a worker restart
max_in_flight_per_repo
number
2
Per-repo cap used by the tenant claim’s fairness ranking: a repo already at this many claimed tasks is ranked last (not excluded), so one busy repo can’t monopolise the pool while an idle replica can still claim its only available task
cold_repo_escape_minutes
number
30
Age (minutes) after which a pending task outranks warm-repo affinity, so a cold repo is never starved by a busy warm one
For a docker-compose snippet that stands up a nomad worker pool (including deploy.replicas, unique COLONY_INTERNAL_WORKER_ID injection, and the v1 scope note), see Nomad worker pool (multi-tenant mode) in the deployment guide.
When repos[].workers (the worker pool model) is configured, setting per-agent-type keys under agents (developer, analyzer, reviewer, merger, planner) for executor-specific settings is deprecated. Use the executors section instead.
When workers is configured, these keys are not copied into executors at config load time, and a deprecation warning is emitted. This does not mean they are ignored: the executors still fall back to the agents.* value when the matching executors.* key is unset:
agents.analyzer.effort
agents.developer.repo_context, pr_overlap_threshold and auto_decompose_on_exhaustion
agents.reviewer.effort
agents.planner.model, effort and max_turns
agents.merger.conflict_resolution
Only agents.developer.forbidden_paths, read_only_paths, self_validation_max_cycles and ci_repair_max_cycles are truly ignored, because they are read only from executors.developer.
Warning: When workers is configured, colony config migratedeletes these keys without copying them into executors. Write the values under executors by hand before running it, or they are lost. Migrate only handles analyzer effort; developer repo_context and pr_overlap_threshold; reviewer effort; planner max_turns, model and effort; and merger conflict_resolution. Other developer keys are left in place.
Removal timeline: These deprecated per-agent keys are scheduled for removal in the next major release. Move the values to executors by hand, then run colony config migrate to clean up your config.
# Before (deprecated — when repos[].workers is set)
agents:
developer:
pr_overlap_threshold: 0.5
# After (write this by hand before running `colony config migrate`)
Migration: Move all fields under agents.monitor. The loader still accepts monitoring: as a top-level key and merges it into agents.monitor for backward compatibility (see the legacy monitoring: merge in loadConfig, packages/core/src/config.ts), but this bridge will be removed in a future release.
Migration: Manage tracks via the dashboard UI or the monitor REST API (POST /api/tracks). YAML track definitions in the config file are still accepted by the config loader and emit a deprecation warning at load time, but at runtime they are ignored — when a TrackStore (Postgres) is available, the seeding loop reads exclusively from the store. Run colony config migrate to remove stale YAML track entries.
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.
Each entry in self_improvement.tracks is a SelfImprovementTrack object with the following fields:
Field
Type
Default
Description
name
string
required
Unique identifier for this track
label
string
required
GitHub label applied to self-improvement issues filed on this track
cooldown_minutes
number
required
Minimum minutes between filings on this track
seed_title
string
—
Title template for self-improvement issues filed on this track
seed_body
string
—
Body template for self-improvement issues filed on this track
instructions
string
—
Additional instructions injected into the developer prompt for this track
cadence
object (kind, expr)
—
Firing schedule. kind: 'cooldown' uses cooldown_minutes; kind: 'cron' uses a cron expr. Internal cadence.expr is managed via the dashboard API
proposal
object (ProposalSlate)
—
Slate of issue sizes to propose. Internal proposal.slate structure is managed via the dashboard API
weight
number
—
Fair-share seeding weight — must be ≥ 1 on an enabled track; sets the track’s share and slots within its pool