Skip to content

Colony Configuration Reference

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.

ScenarioReadSkip
First-time single repoTier 1 + 2Tier 3
Production single repoTier 1 + 2 + relevant Tier 3 sectionsMulti-tenant
Multi-repo / Colony CloudAll tiers—

Colony uses YAML configuration files. The config is loaded from the first location found in this order:

  1. Path passed via the --config CLI flag
  2. ./colony.config.yaml (current working directory)
  3. ~/.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:

$id: https://runcolony.com/schema/colony.config.schema.json

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):

# yaml-language-server: $schema=https://runcolony.com/schema/colony.config.schema.json
github:
owner: your-org
repo: your-repo
# ...

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:

# yaml-language-server: $schema=./schema/colony.config.schema.json

This relative form will not resolve for configs at ~/.colony/config.yaml or in a separate target repository — use the URL form for those.

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.

Required fields vs. Colony-defaulted fields

Section titled “Required fields vs. Colony-defaulted fields”

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
npm run generate: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.

github:
owner: your-org # GitHub org or user that owns the repo
repo: your-repo # repository name
token_env: GITHUB_TOKEN # default; set GITHUB_TOKEN in your environment
workspace:
repo_dir: /path/to/your/repo # absolute path to your local git clone
review:
checks:
test: npm test # CHANGE to your actual test command
lint: npm run lint # CHANGE to your actual lint command
VariableRequiredDescription
GITHUB_TOKENrequiredPersonal Access Token. See required scopes. Used by Colony to create branches, open PRs, and post comments
ANTHROPIC_API_KEYrequiredAnthropic API key for Claude Code invocations by worker agents
DATABASE_URLrequiredPostgres connection string (e.g. postgresql://user:pass@localhost:5432/colony)
OPENAI_API_KEYrequired when any agent uses engine: codexOpenAI API key for Codex invocations. The key name is configurable via codex.api_key_env (default OPENAI_API_KEY). See Engine Selection

Authentication and identity settings for the target repository.

FieldTypeDefaultDescription
ownerstringrequiredGitHub organization or user that owns the target repository
repostringrequiredTarget repository name
token_envstring'GITHUB_TOKEN'Name of the environment variable containing the Personal Access Token used for GitHub API calls

For GitHub App auth, bot identity, and ops identity settings, see the full github reference in Tier 3.

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

review.checks (required — do not leave empty)

Section titled “review.checks (required — do not leave empty)”

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.

FieldTypeDefaultDescription
checksRecord<string, string | { command: string; blocking?: boolean }>{}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.

Controls log output from all Colony processes.

FieldTypeDefaultDescription
levelstring'info'Pino log level. Valid values: 'trace', 'debug', 'info', 'warn', 'error', 'fatal'
format'json' | 'pretty''pretty'Log output format. Use 'json' in production/containerized deployments for structured log ingestion; use 'pretty' for local development

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.

FieldTypeDefaultDescription
max_daily_usdnumber50Maximum 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_pctnumber10Percentage 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_commentbooleanfalseWhen 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.

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

Override which Claude model each agent uses. The defaults balance capability against cost; use this section to tune the trade-off.

FieldTypeDefaultDescription
developerstring'claude-opus-5-5'Model used for the developer agent
reviewerstring'claude-opus-5-5'Model used for the reviewer agent
analyzerstring'claude-sonnet-5'Model used for the analyzer agent
plannerstring'claude-opus-5-5'Model used for the planner agent
mergerstring'claude-opus-5-5'Model used for the merger agent
strategiststring'claude-opus-5-5'Model used by the strategist station. Must be a non-empty Claude model id; claude-fable-5 is opt-in and never a default
conversationstring'claude-haiku-4-5'Model used by the sprint-master’s Mayor to answer addressed messages in a single tool-less turn

Per-repo model override (repos[].claude.models)

Section titled “Per-repo model override (repos[].claude.models)”

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
1model_routing.override (global kill-switch)
2Workflow state-declared model:
3model_routing.routes[task][tier] when routing is enabled and a route matches
4Repo claude.models.<role>
5claude.scaling[tier].model, including the built-in defaults (developer only)
6Tenant/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.

ModelApprox. 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 / $25Older Opus generation — same pricing as Opus 5; a valid fallback for users running existing workflows.
claude-opus-4-7~$5 / $25Older Opus generation — same pricing; useful for users already running 4-7 in existing workflows.
claude-opus-4-6~$5 / $25Older 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 / $15Previous Sonnet generation — still a valid choice, no longer the shipped default.
claude-haiku-4-5-20251001~$1 / $5The 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 / $50Optional 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>:

claude:
models:
developer: claude-opus-5-5 # highest capability, lowest fake-validation rate
reviewer: claude-opus-5-5 # read-only loop; slowness tolerable; Opus 5.5 matters here
analyzer: claude-sonnet-4-6 # high volume; sonnet-high is the sweet spot
planner: claude-opus-5-5 # lowest volume, highest blast radius
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.

For all claude settings, see the full claude reference in Tier 3.

Engine Selection (agents.<agent>.engine and codex:)

Section titled “Engine Selection (agents.<agent>.engine and codex:)”

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

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

FieldTypeDefaultDescription
timeoutnumber600Overall Codex CLI invocation timeout in seconds
max_retriesnumber1Number of times to retry a failed Codex invocation
inactivity_timeoutnumber—Seconds without output before the process is killed. Optional — omit for no inactivity cap
binary_pathstringcodex (from PATH)Path to the Codex binary. Override when codex is not on PATH
api_key_envstring'OPENAI_API_KEY'Name of the environment variable containing the OpenAI API key for Codex invocations
modelsobject(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.

FieldTypeDefaultDescription
developerstring'codex-1'Model used when the developer agent runs on Codex
reviewerstring'o4-mini'Model used when the reviewer agent runs on Codex
analyzerstring'o4-mini'Model used when the analyzer agent runs on Codex
plannerstring'o4-mini'Model used when the planner agent runs on Codex
mergerstring'o4-mini'Model used when the merger agent runs on Codex
conversationstring'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.

Invalid claude.models entry (Claude-family required):

claude.models.<key> '<model>' is not a Claude model — claude.models entries must be Claude model ids (e.g. claude-opus-5)

Invalid codex.models entry (Codex/GPT-family required):

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

Section titled “Worked example: developer on Codex, all other agents on Claude”
# Claude model selection for non-Codex agents (unchanged from default)
claude:
models:
analyzer: claude-sonnet-4-6
reviewer: claude-opus-5-5
planner: claude-opus-5-5
merger: claude-sonnet-4-6
# Switch only the developer to Codex
agents:
developer:
engine: codex
# Codex settings — only the developer reads these in this config
codex:
api_key_env: OPENAI_API_KEY
models:
developer: codex-1 # built-in default; shown here for clarity

With this config:

  • The developer agent uses Codex CLI with codex-1 and reads OPENAI_API_KEY from the environment.
  • All other agents (analyzer, reviewer, planner, merger) use Claude Code with their configured Claude models — unchanged from the default.
  • colony check validates that codex-1 is a valid Codex model and warns if OPENAI_API_KEY is absent.

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.

The developer agent picks its model per-issue based on the issue’s assessed complexity:

ComplexityEffective model
smallclaude.scaling.small.model → fallback: claude.models.developer
mediumclaude.scaling.medium.model → fallback: claude.models.developer
largeclaude.scaling.large.model → fallback: claude.models.developer

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):

TierModelMax turns
smallclaude-sonnet-580
mediumclaude-opus-5-5150
largeclaude-opus-5-5250

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
scaling:
small:
developer_max_turns: 80
model: claude-sonnet-4-6
medium:
developer_max_turns: 150
model: claude-sonnet-4-6 # explicit — otherwise DEFAULT_SCALING.medium.model wins
large:
developer_max_turns: 250
model: claude-sonnet-4-6 # explicit — otherwise DEFAULT_SCALING.large.model wins

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.

model_routing:
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
FieldTypeDefaultDescription
enabledbooleanfalseMaster switch. When false, routes are ignored and resolution falls back to claude.models.*
overridestring—Global force-model. When set, forces this model for every task regardless of task type, tier, or enabled. Useful as a kill-switch
routesobject—Per-task-type, per-tier model map. Task keys: analyze, develop, review, merge, plan. Tier keys: small, medium, large
quota_fallbackbooleantrueWhen 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):

  1. override — when set, applies unconditionally regardless of enabled or routes
  2. Station-declared model — a model on the workflow state itself (see the paragraph below)
  3. routes[taskType][tier] — when enabled !== false and a matching route entry exists
  4. 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
  5. 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:

  1. 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.
  2. 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.

Colony scores each task to a complexity tier before resolving its model. The scoring uses signals available at claim time:

Base tier (first match wins):

  1. analyzerComplexity from pipeline_issues (set by the analyzer) — used directly when present
  2. plannedFileCount from task inputs: < 2 → small; > 6 → large; else medium
  3. issueBodyLength in characters: < 500 → small; else medium
  4. Default: medium

One-tier escalation — the base tier is escalated by one step (capped at large) when any of the following signals is present:

  • decompositionStrategy is set and not 'single_unit' (i.e. the planner decomposed the issue)
  • reviewCycle ≥ 1 (at least one review-cycle has already occurred)
  • A directive of kind changes_requested, ci_failure, or must_decompose is attached to the task

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 reasonEscalates?
review_cycle_limitYes
build_failureYes
ci_hard_failureYes
All othersNo

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
FieldScopeWhat happens when hit
claude.max_cost_per_issuePer-issueClaude invocation is aborted; issue moves to colony:blocked; comment posted with cost breakdown. Resume with /colony:retry after raising the limit.
max_daily_usdPer-tenant/dailyNo 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_pctModifierLowers 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.

Intake Mode (agents.sprint_master.intake_mode)

Section titled “Intake Mode (agents.sprint_master.intake_mode)”

Controls whether the sprint master picks up all new issues or only those tagged with colony:enqueue.

FieldTypeDefaultDescription
intake_mode'all' | 'tagged''tagged'Whether to pick up all new issues or only colony-tagged ones

Example:

agents:
sprint_master:
intake_mode: all # pick up every new issue automatically

For all sprint master settings, see the full agents.sprint_master reference in Tier 3.

Override when your repository’s default branch is not main.

FieldTypeDefaultDescription
branchstring'main'Default branch name for the repository. Override when the repo’s default branch is not main (e.g. 'master', 'develop')

Example:

workspace:
branch: master

For all workspace settings, see the full workspace reference in Tier 3.

Auto-Merge (review.auto_merge_on_approval)

Section titled “Auto-Merge (review.auto_merge_on_approval)”
FieldTypeDefaultDescription
auto_merge_on_approvalbooleanfalseAutomatically merge the PR after the reviewer approves it

Example:

review:
auto_merge_on_approval: true

review.auto_merge_on_approval does not apply to Dependabot tracking issues; their merges are authorized only by the dependabot flags.

For all review settings, see the full review reference in Tier 3.

Monitor Dashboard (agents.monitor.enabled)

Section titled “Monitor Dashboard (agents.monitor.enabled)”

The monitor agent is disabled by default. Enable it to access the pipeline dashboard and alerting.

FieldTypeDefaultDescription
enabledbooleanfalseEnable the monitor agent. Exposes a dashboard and Prometheus metrics endpoint

Example:

agents:
monitor:
enabled: true

For all monitor settings (alerting, self-healing, cost thresholds, etc.), see the full agents.monitor reference in Tier 3.

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.'
FieldTypeDefaultDescription
enabledbooleantrueWhen false, no disclosure footer is appended. Disabling this weakens the operator’s own Article 50(1) compliance posture — only disable after legal review.
textstringSee aboveThe disclosure text appended after a horizontal rule (---). Self-hosted operators may substitute their own deployment name.

The footer format is always:

---
<text>

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

BlockStatusSingleton(s) consumed by
claudeReloads liveworker, sprint-master, monitor
codexReloads live — Codex engine settings; per-agent engine field is NOT reloadable (requires redeploy)worker
reviewReloads liveworker
dependabotReloads live — the worker’s approve and merge decisions and sprint-master intakeworker, sprint-master
max_daily_usdReloads liveworker, sprint-master, monitor
daily_ceiling_commentReloads liveworker
budget_headroom_pctReloads liveworker, sprint-master, monitor
agentsPartial — selected workers, sprint_master, and monitor sub-keys reload live; agent identity/startup settings need redeployworker, sprint-master, monitor
llmReloads live (deprecated — prefer claude.scaling)worker
attributionReloads liveworker, sprint-master
comment_policyReloads live (worker, sprint-master); monitor requires restart (caches write-services)worker, sprint-master
intelligenceReloads liveworker
model_routingReloads liveworker
intake_rulesReloads live (deprecated — use repos[].workflows)sprint-master
default_workflowReloads live (deprecated — use repos[].workflows)sprint-master
strategyReloads live — all keys, including cadence (read every scheduler tick)sprint-master
mergeReloads liveworker
mailboxReloads liveworker
overlapReloads liveworker, sprint-master
max_cost_per_issueReloads live (top-level alias for claude.max_cost_per_issue)worker
loggingPartial — level reloads live; format needs redeployworker, sprint-master, monitor
workspacePartial — safe sub-keys reload live; identity/path sub-keys need redeployworker
reposPartial — 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 redeployworker, sprint-master, webhook-receiver
githubNeeds redeploy (including request_budget)worker, sprint-master, monitor, webhook-receiver, mcp
adoNeeds redeployworker, sprint-master
databaseNeeds redeployworker, sprint-master, monitor
tenantsNeeds redeployworker, sprint-master
labelsNeeds redeployworker, sprint-master
commandsNeeds redeploysprint-master, webhook-receiver
webhookNeeds redeploywebhook-receiver
deploymentNeeds redeployall
event_logNeeds redeployworker, sprint-master, monitor
pluginsNeeds redeployworker
self_improvementNeeds redeploysprint-master
executorsNeeds redeployworker
calibrationNeeds redeploysprint-master
epicNeeds redeployworker

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.

Sub-keyStatus
levelReloads live
formatNeeds redeploy
Sub-keyStatus
setup_commandReloads live
setup_timeoutReloads live
prebuild_commandReloads live
skip_pre_push_hookReloads live
repo_dirNeeds redeploy
base_dirNeeds redeploy
cleanup_after_mergeNeeds redeploy
branchNeeds redeploy
review_workspace_baseNeeds redeploy
prune_blocked_after_daysNeeds redeploy

Only the following agent sub-keys reload live. Other agents.* settings require restart or redeploy.

Sub-key pathStatus
workers.*Reloads live
sprint_master.poll_intervalReloads live
sprint_master.code_map_scan_interval_hoursReloads live
sprint_master.heartbeat_timeout_minutesReloads live
sprint_master.sweep_cooldown_minutesReloads live
sprint_master.label_sync_limitReloads live
sprint_master.item_panel_revisit_limitReloads live
sprint_master.projection_drain_limitReloads live
sprint_master.auto_unblock_transientReloads live
sprint_master.max_auto_unblocks_per_cycleReloads live
sprint_master.mayor_timeout_secondsReloads live
sprint_master.startup_poll_concurrencyReloads live
sprint_master.startup_clone_concurrencyReloads live
sprint_master.active_repo_reconcile_intervalReloads live
sprint_master.mayor_max_concurrentReloads live
sprint_master.retrospective_max_concurrentReloads live
sprint_master.mayor_enabledReloads live
sprint_master.mayor_issue_messages_per_hourReloads live
sprint_master.mayor_sender_messages_per_hourReloads live
sprint_master.auto_unblock_cooldown_minutesReloads live
sprint_master.max_auto_unblocks_per_issueReloads live
sprint_master.queue_starvation_threshold_hoursReloads live
sprint_master.orphan_recovery_cooldown_minutesReloads live
sprint_master.work_task_retention_daysReloads live
sprint_master.cost_raw_retention_daysReloads live
sprint_master.utilization_rollup_enabledReloads live
sprint_master.auto_repair_stale_blockedReloads live
sprint_master.auto_repair_stale_subtask_edgesReloads live
monitor.poll_intervalReloads live
monitor.cost_alert_thresholdReloads live
monitor.self_healingReloads live
monitor.alert_channelsReloads live
monitor.regression_guardReloads live
monitor.agent_down_timeoutReloads live
monitor.pipeline_stall_timeout_minutesReloads live
monitor.error_rate_thresholdReloads live
monitor.error_rate_windowReloads live
monitor.max_task_durationReloads live
monitor.max_replica_pause_minutesReloads live
monitor.alert_cooldownReloads live
monitor.metrics_refresh_minutesReloads live
monitor.consistency_refresh_minutesReloads live
monitor.repo_active_reconcile_secondsReloads live
monitor.long_lived_state_ceiling_hoursReloads live
monitor.human_wait_ceiling_hoursReloads live
monitor.human_wait_reminder_hoursReloads live
monitor.daily_digestReloads live
Agent enabled, health_port, auth, identity, and non-listed agent fieldsNeeds redeploy

repos[].epic.review.auto_fix_protected_paths overrides epic.review.auto_fix_protected_paths for that repo (the repo value replaces the tenant value).

repos[].epic.review.auto_fix_max_changed_lines overrides epic.review.auto_fix_max_changed_lines for that repo.

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:

Sub-key pathStatus
review.checksReloads live
review.timeout_per_checkReloads live
review.flaky_rerunsReloads live
review.ci_flaky_rerunsReloads live
review.flaky_quarantine_thresholdReloads live
review.require_ci_passReloads live
review.ci_check_timeoutReloads live
review.ci_required_checksReloads live
review.ci_absent_check_graceReloads live
review.format_commandReloads live
review.clean_verificationReloads live
review.auto_merge_on_approvalReloads live
review.external_prsReloads live
review.ci_repairReloads live
dependabot.*Reloads live
default_stewardsReloads live
workspace.setup_commandReloads live
workspace.setup_timeoutReloads live
workspace.prebuild_commandReloads live
workspace.skip_pre_push_hookReloads live
owner / repo / token_env / app / ops_app / ops_token_envNeeds redeploy
workspace.repo_dir / workspace.base_dir / workspace.branch / workspace.review_workspace_baseNeeds redeploy
workers / sla / self_improvement / intake_mode / pattern_memory / code_mapNeeds redeploy

Tier 3: Advanced & Multi-Repo Configuration

Section titled “Tier 3: Advanced & Multi-Repo Configuration”

Complete reference for all configuration fields. New users can skip this section until they encounter a scenario that requires it.

Top-level tenant identifier used when Colony synthesizes the default tenant in single-repo mode.

FieldTypeDefaultDescription
tenant_idstring'default'Identifier assigned to the implicit tenant when tenants[] is not configured. Useful for event, cost, and DB records.

Controls deployment-mode-specific path handling. This section is optional.

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

FieldTypeDefaultDescription
organizationstringrequiredAzure DevOps organization name
projectstringrequiredAzure DevOps project name
repostringrequiredAzure DevOps repository name
token_envstringrequiredEnvironment variable containing the ADO Personal Access Token for the coder identity
ops_token_envstring—Environment variable containing a separate ADO PAT for ops actions
closed_statestring'Closed'Work item state that represents a closed/done issue
active_statestring'Active'Work item state that represents an active issue
work_item_type_mapADOWorkItemTypeMap—Work item type names to use for Colony-created items
webhook_usernamestring—Username expected by the ADO webhook receiver when basic auth is configured
webhook_password_envstring—Environment variable containing the ADO webhook basic-auth password

Used by ado.work_item_type_map.

FieldTypeDefaultDescription
defaultstring'User Story'Work item type for general Colony-created items
self_improvementstring—Work item type for self-improvement items
epicstring—Work item type for epic parent items
subtaskstring—Work item type for decomposed subtask items
bugstring—Work item type for bug or defect items

Authentication and identity settings for the target repository.

FieldTypeDefaultDescription
ownerstringrequiredGitHub organization or user that owns the target repository
repostringrequiredTarget repository name
token_envstring'GITHUB_TOKEN'Name of the environment variable containing the Personal Access Token used for GitHub API calls
appGitHubAppConfig—GitHub App credentials for the coder identity (Analyzer, Developer). Use instead of token_env for App-based auth
ops_appGitHubAppConfig—Separate GitHub App credentials for the ops identity (Sprint Master, Reviewer, Merger). Allows two distinct bot identities
ops_token_envstring—Name of the environment variable containing the PAT for the ops identity. Alternative to ops_app
bot_usernamestring—Display name shown for bot-authored comments and labels
rate_limit_jitter_msinteger (≥ 0)30000Upper 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_budgetobject— (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.

Used by github.app and github.ops_app.

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

Controls the namespace used for every pipeline label Colony creates on GitHub issues or Azure DevOps work items — state labels and flag labels.

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

FieldTypeDefaultDescription
repo_dirstring'.'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_dirstring'~/.colony/workspaces/{owner}/{repo}'Base directory for worktrees. Supports {owner} and {repo} template tokens which are substituted at runtime
cleanup_after_mergebooleantrueRemove the worktree after a PR is merged. Set to false to retain worktrees for post-merge inspection
setup_commandstring—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_timeoutnumber300Seconds to allow the setup command to run before timing out
prebuild_commandstring—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_daysnumber7Days before worktrees for blocked issues are automatically pruned
review_workspace_basestring—Container-local path for ephemeral reviewer worktrees. Required when the reviewer runs in an isolated container with a different filesystem layout
skip_pre_push_hookboolean—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
branchstring'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.

FieldTypeDefaultDescription
url_envstring'DATABASE_URL'Name of the environment variable containing the Postgres connection string
listen_url_envstringurl_envEnvironment variable for a direct Postgres URL used by LISTEN/NOTIFY. Set this separately when url_env points at PgBouncer transaction pooling
max_connectionsnumber10Maximum 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_sizemapunsetPer-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_timeoutnumber10000idleTimeoutMillis for the pg connection pool (milliseconds). Lower this for connection-constrained environments
connection_timeoutnumber10000connectionTimeoutMillis for establishing a pg client connection
statement_timeoutnumber30000Server-side Postgres statement timeout in milliseconds (see note below for poolers/Neon)
query_timeoutnumber30000Client-side node-postgres query timeout in milliseconds
keep_alivebooleantrueEnable 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
sslboolean | objectfalseEnable 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.

FieldTypeDefaultDescription
enabledbooleantrueEnable or disable event logging for agents that use the event logger
dirstring'~/.colony/events'Directory where event log files are written
retention_daysnumber30Number of days to retain local event log files before pruning
agent_message_retention_daysnumber14Number of days to retain agent_messages rows before sprint-master retention sweeps prune partitions
pipeline_event_retention_daysnumberunset (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.

FieldTypeDefaultDescription
enabledbooleanrequiredEnable the webhook receiver
portnumber (1–65535)requiredPort for the webhook receiver HTTP server to listen on
secret_envstring—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.

FieldTypeDefaultDescription
timeoutnumber1800Overall Claude CLI invocation timeout in seconds
max_retriesnumber1Number of times to retry a failed Claude invocation
inactivity_timeoutnumber300Seconds without stdout/stderr output before the process is killed with SIGKILL
max_cost_per_issuenumber—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_pathstring'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)
foundryClaudeFoundryConfig—Azure Foundry configuration. Only used when provider: 'foundry'
gatewayClaudeGatewayConfig—Anthropic-compatible gateway configuration. Only used when provider: 'gateway'
auth_mode'api-key' | 'oauth-token' | 'wif''api-key'Claude Code authentication mode. api-key uses Anthropic/Foundry API keys; oauth-token uses a Claude subscription OAuth token; wif uses Workload Identity Federation (experimental)
api_key_envstring'ANTHROPIC_API_KEY'Informational name for the Anthropic API key environment variable. Current Anthropic API-key runtime checks use ANTHROPIC_API_KEY
oauth_token_envstring'CLAUDE_CODE_OAUTH_TOKEN'Environment variable containing the OAuth token when auth_mode: oauth-token
oauth_expires_atstring—ISO timestamp used for pre-invocation OAuth expiry checks. Refreshing this value can resume workers paused for token expiry
modelsClaudeModelsConfig—Per-agent model overrides
scalingClaudeScalingConfig—Per-complexity turn limits and model overrides. When omitted, built-in defaults are used (see below)

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.

claude:
auth_mode: wif
wif:
federation_rule_id: fr_...
organization_id: 00000000-0000-0000-0000-000000000000
service_account_id: sa_...
# workspace_id: wrkspc_... # only when the rule spans several workspaces
identity_token_file: /run/secrets/anthropic-idtoken
# identity_token_file_env: ANTHROPIC_IDENTITY_TOKEN_FILE # alternative: env var holding the path
FieldDescription
federation_rule_idRequired. Sent as ANTHROPIC_FEDERATION_RULE_ID
organization_idRequired. Sent as ANTHROPIC_ORGANIZATION_ID
service_account_idRequired. Sent as ANTHROPIC_SERVICE_ACCOUNT_ID
workspace_idOptional. Sent as ANTHROPIC_WORKSPACE_ID only when set
identity_token_filePath of the JWT file, sent as ANTHROPIC_IDENTITY_TOKEN_FILE. Wins over identity_token_file_env
identity_token_file_envName 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'.

FieldTypeDefaultDescription
resourcestring—Azure resource name. URL constructed as https://{resource}.services.ai.azure.com/anthropic. Mutually exclusive with base_url
base_urlstring—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_envstring'ANTHROPIC_FOUNDRY_API_KEY'Environment variable holding the Foundry API key
pin_models.opusstring—Pin the Opus deployment name (sets ANTHROPIC_DEFAULT_OPUS_MODEL)
pin_models.sonnetstring—Pin the Sonnet deployment name (sets ANTHROPIC_DEFAULT_SONNET_MODEL)
pin_models.haikustring—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'.

FieldTypeDefaultDescription
base_urlstringrequiredGateway base URL (sets ANTHROPIC_BASE_URL)
auth_token_envstring'ANTHROPIC_AUTH_TOKEN'Environment variable holding the gateway auth token (sets ANTHROPIC_AUTH_TOKEN)
custom_headersstring—Custom headers forwarded to the gateway (sets ANTHROPIC_CUSTOM_HEADERS)
disable_experimental_betasboolean—When true, sets CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1
pin_models.opusstring—Pin the Opus model identifier (sets ANTHROPIC_DEFAULT_OPUS_MODEL)
pin_models.sonnetstring—Pin the Sonnet model identifier (sets ANTHROPIC_DEFAULT_SONNET_MODEL)
pin_models.haikustring—Pin the Haiku model identifier (sets ANTHROPIC_DEFAULT_HAIKU_MODEL)
budget_exhausted_matchlist—[{ 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[].statusnumber—HTTP status the rule matches (400–599)
budget_exhausted_match[].textstring—Case-insensitive substring of the error text the rule matches
attribution.headerstring—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.formatstringjsonjson (one header holding a JSON object) or headers (one header per field)
attribution.fieldslistall fiveSubset of tenant, repo, issue, station, task

See Running Colony behind an LLM gateway for budget, throttle and 403 behavior, attribution examples and model-id guidance.

Example (TrueFoundry):

claude:
provider: gateway
gateway:
base_url: https://llm-gateway.truefoundry.com/api/llm
auth_token_env: TRUEFOUNDRY_API_KEY
custom_headers: 'x-tfy-anthropic-beta: context-management-2025-06-27'
disable_experimental_betas: true
pin_models:
opus: claude-code/claude-opus
sonnet: claude-code/claude-sonnet
haiku: claude-code/claude-haiku
# 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 configResolved pricing tierCost attribution
acme/claude-sonnet-4-6Sonnet ($3/$15 per M)✓
anthropic-main/claude-opus-4-8Opus ($5/$25 per M)✓
claude-code/claude-haiku-4-5Haiku ($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.

See also Running Colony behind an LLM gateway.

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.

VariablePurpose
ANTHROPIC_BASE_URLOverride the Anthropic API endpoint root. Claude Code appends /v1/messages for requests.
ANTHROPIC_AUTH_TOKENBearer token forwarded to the gateway endpoint.
ANTHROPIC_CUSTOM_HEADERSAdditional 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_BETASSet 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.

Two failure modes account for almost all gateway routing problems. The error messages differ enough to tell them apart immediately.

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.

claude:
provider: gateway
gateway:
pin_models:
opus: claude-code/claude-opus-4-8 # ✓ contains "opus"
sonnet: claude-code/claude-sonnet-4-6 # ✓ contains "sonnet"
haiku: claude-code/claude-haiku-4-5 # ✓ contains "haiku"

Run colony check after updating — it validates all model ids against the same tier-matching logic Colony uses at runtime.

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:

  1. 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.
  2. 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.

SignalModel rejectionAuth rejection
Error originClaude Code startup, before any API callFirst API request to the gateway
HTTP statusNone (local check)401 Unauthorized
Colony block reasonmodel-compatibility errorauth-failure
Fix targetpin_models / claude.models.*auth_token_env + Compose allowlist

Used by claude.models.

FieldTypeDefaultDescription
developerstring'claude-opus-5-5'Model used for the developer agent
reviewerstring'claude-opus-5-5'Model used for the reviewer agent
analyzerstring'claude-sonnet-5'Model used for the analyzer agent
plannerstring'claude-opus-5-5'Model used for the planner agent
mergerstring'claude-opus-5-5'Model used for the merger agent
strategiststring'claude-opus-5-5'Model used by the strategist station. Must be a non-empty Claude model id; claude-fable-5 is opt-in and never a default
conversationstring'claude-haiku-4-5'Model used by the sprint-master’s Mayor to answer addressed messages in a single tool-less turn

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.

ModelApprox. 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 / $25Older Opus generation — same pricing as Opus 5; a valid fallback for users running existing workflows.
claude-opus-4-7~$5 / $25Older Opus generation — same pricing; useful for users already running 4-7 in existing workflows.
claude-opus-4-6~$5 / $25Older 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 / $15Previous Sonnet generation — still a valid choice, no longer the shipped default.
claude-haiku-4-5-20251001~$1 / $5The 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 / $50Optional 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>:

claude:
models:
developer: claude-opus-5-5 # highest capability, lowest fake-validation rate
reviewer: claude-opus-5-5 # read-only loop; slowness tolerable; Opus 5.5 matters here
analyzer: claude-sonnet-4-6 # high volume; sonnet-high is the sweet spot
planner: claude-opus-5-5 # lowest volume, highest blast radius
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.

Example:

claude:
scaling:
small:
developer_max_turns: 80
medium:
developer_max_turns: 150
large:
developer_max_turns: 250
no_progress_window: 75
FieldTypeDefault (built-in)Description
developer_max_turnsnumber80 / 150 / 250 (small / medium / large)Maximum Claude turns for a developer invocation at this complexity
modelstringclaude-sonnet-5 (small) / claude-opus-5-5 (medium/large)Override the model for this complexity level, 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_turnsnumber500Maximum turns for planning sub-tasks at this complexity
no_progress_windownumber— (75 for large only)Number of turns without measurable progress before aborting
backstop_max_turnsnumber500Hard 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):

Tiermodeleffortdeveloper_max_turnsRationale
smallclaude-sonnet-5high80Sonnet-high beats Opus-medium on cost-for-quality for 1–3 file mechanical work
mediumclaude-opus-5-5high150Opus-high for 3–7 file work; max not justified at this scope
largeclaude-opus-5-5max250The 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:

FieldDefaultRecommended starting point
claude.timeout1800Increase to 3600 for large repos with long build times
review.timeout_per_check120Raise to 300 for slow test suites
agents.sprint_master.poll_interval3030 is sufficient for evaluation; lower only if you need sub-30s latency and have webhooks configured

Controls PR review behaviour: deterministic check commands, LLM review rounds, CI gating, and merge policy.

FieldTypeDefaultDescription
checksRecord<string, string | { command: string; blocking?: boolean }>{}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_checknumber120Seconds allowed for each check command before it is killed
max_review_cyclesnumber5Maximum 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_rerunsnumber1Times 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_rerunsnumber1CI 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_thresholdnumberunsetWhen 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_cyclesnumber—Maximum number of times the developer re-implements after a review rejection. Unlimited if unset
auto_merge_on_approvalbooleanfalseAutomatically merge the PR after the reviewer approves it
require_ci_passbooleantrueWait for all required CI checks to pass before merging
ci_check_timeoutnumber300Seconds to wait for CI checks to complete before timing out
ci_required_checksstring[][]Names of specific CI checks that must pass. When empty, all checks must pass
ci_absent_check_gracenumber600Seconds 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_commandstring—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_verificationstring—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_approvebooleantrueAuto-approve when the LLM returns an empty or unparseable verdict and all deterministic checks passed
scope_driftobject—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.enabledbooleanfalseEnable 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
external_prsExternalPrReviewConfigmode: offExternal PR review settings — controls whether Colony reviews human-authored PRs. See ExternalPrReviewConfig below
ci_repairCiRepairConfig—Controls which failed CI checks can trigger automatic CI repair tasks and how many repair cycles are allowed

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.

FieldTypeDefaultDescription
mode'off' | 'on_request' | 'on_ready' | 'auto''off'When to review external PRs. off — disabled. on_request — only when a human comments /colony:review on 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_filterstring[]['*']Allowlist of GitHub usernames to review. ['*'] means any author. Set to a specific list to limit reviews to those users
label_filterstring[][]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_botsbooleantrueSkip PRs authored by bot accounts (GitHub user type 'Bot')
exclude_draftsbooleantrueSkip draft PRs
auto_approvebooleanfalseWith 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)

Example:

review:
external_prs:
mode: on_request # safest starting mode

Used by review.ci_repair.

FieldTypeDefaultDescription
max_cyclesnumber2Maximum CI repair cycles before escalating. executors.developer.ci_repair_max_cycles takes precedence when set
deny_checksstring[][]Check names that should never trigger automatic CI repair
allow_checksstring[]—If set, only matching check names can trigger automatic CI repair

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.

All agent types share these base fields:

FieldTypeDefaultDescription
enabledbooleantrueWhether the agent runs
poll_intervalnumber30Seconds between poll cycles (minimum 5)
health_portnumber(per agent)HTTP health check port
effort'low' | 'medium' | 'high' | 'max'— (high for reviewer and planner)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.

Issue intake and pipeline monitoring. Enqueues tasks to the Postgres work queue when issues transition states.

FieldTypeDefaultDescription
Common fieldshealth_port: 9100See Common AgentConfig Fields
intake_mode'all' | 'tagged''tagged'Whether to pick up all new issues or only colony-tagged ones
heartbeat_timeout_minutesnumber5Minutes 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_minutesnumber10Minutes to suppress re-enqueueing a sweep task after completion (0 to disable)
label_sync_limitnumber25Max issues to reconcile labels for per poll cycle
item_panel_revisit_limitnumber20Open 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_limitnumber50Max queued VCS write projections to drain per poll cycle
auto_unblock_transientbooleantrueAutomatically unblock issues blocked by transient infrastructure failures
auto_unblock_quotabooleantrueAutomatically re-queue quota-blocked issues after their reset time has passed
max_auto_unblocks_per_cyclenumber3Max issues to auto-unblock during one sprint-master cycle
health_stale_after_secondsnumber30Integer ≥ 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_secondsnumber20Hard 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_concurrencynumber8Max 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_concurrencynumber4Max 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_intervalnumber60Seconds (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_concurrentnumber4Global 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_concurrentnumber4Process-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_enabledbooleantrueKill 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_hournumber10Max 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_hournumber5Max 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_minutesnumber10Per-issue cooldown before auto-unblocking the same issue again
max_auto_unblocks_per_issuenumber3Lifetime automatic unblock limit per issue before escalation
full_sync_intervalnumber10Every 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_activenumber50Full-sync interval in poll intervals (about 25 min at the 30 s default) after webhooks have been active for enough cycles
full_sync_active_thresholdnumber5Consecutive webhook-active cycles before switching to full_sync_interval_active
webhook_inactivity_minutesnumber15Minutes without webhook events before falling back toward full polling behavior
queue_starvation_threshold_hoursnumber24Hours a pending task may wait before a starvation warning is logged (0 disables)
orphan_recovery_cooldown_minutesnumber5Per-issue cooldown before re-enqueuing orphan recovery work (0 disables)
code_map_scan_interval_hoursnumber24Hours 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_daysnumber31Days to retain completed work_tasks rows before pruning
cost_raw_retention_daysnumberunsetOpt-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_enabledbooleantrueEnable once-per-UTC-day rollup of worker utilization into worker_utilization_daily
auto_repair_stale_blockedbooleanfalseAutomatically 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_edgesbooleanfalseAutomatically resolve stale subtask dependency edges on completed epics. Reuses the max_auto_unblocks_per_issue cap; a flapping issue escalates to needs-human.

Issue analysis and triage. Uses bare AgentConfig with no additional fields.

FieldTypeDefaultDescription
Common fieldshealth_port: 9101See Common AgentConfig Fields

PR review: deterministic checks plus LLM review. Uses bare AgentConfig with no additional fields.

FieldTypeDefaultDescription
Common fieldshealth_port: 9103, effort: highSee Common AgentConfig Fields

Issue implementation via Claude Code.

FieldTypeDefaultDescription
Common fieldshealth_port: 9102See Common AgentConfig Fields
repo_contextRepoContextConfig—Controls repository context injection into prompts
pr_overlap_thresholdnumber (0–1)—Fraction of plan files overlapping with open PRs to trigger block
auto_decompose_on_exhaustionbooleantrueRoute oversized issues to planner after developer turn-limit exhaustion
forbidden_pathsstring[]—Glob patterns the agent may not read or write. See Protected Paths.
read_only_pathsstring[]—Glob patterns the agent may read but not write. See Protected Paths.
self_validation_max_cyclesnumber (1–10)3Maximum self-validation repair cycles before escalating
ci_repair_max_cyclesnumber (1–10)2Maximum CI repair cycles before escalating

Used by agents.developer.repo_context.

FieldTypeDefaultDescription
enabledboolean—Enable repository context injection
max_tokensnumber—Maximum tokens for the context payload
tree_depthnumber—Depth of the directory tree to include

Epic decomposition — breaks large issues into sub-tasks.

FieldTypeDefaultDescription
Common fieldshealth_port: 9105, effort: highSee Common AgentConfig Fields
max_turnsnumber200Max Claude turns for planning
modelstring—Override model for planner

Merge orchestration — handles PR merging and conflict resolution.

FieldTypeDefaultDescription
Common fieldshealth_port: 9104See Common AgentConfig Fields
conflict_resolutionConflictResolutionConfig—Automated merge conflict resolution settings

Used by agents.merger.conflict_resolution.

FieldTypeDefaultDescription
enabledbooleantrueEnable automated conflict resolution
max_conflict_filesnumber50Runaway backstop: skip LLM resolution when conflict files exceed this count. The primary gate is semantic complexity (LLM-judged), not this cap.
max_conflict_regionsnumber150Runaway backstop: skip LLM resolution when conflict regions exceed this count. The primary gate is semantic complexity (LLM-judged), not this cap.
timeoutnumber300Timeout in seconds for conflict resolution
modelstringclaude.models.merger (then claude-opus-5-5)Override model for conflict resolution
auto_merge_high_confidence_resolutionsbooleantrueAutomatically 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.

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

FieldTypeDefaultDescription
Common fieldsenabled: true, health_port: 9106See Common AgentConfig Fields
agent_down_timeoutnumber120Seconds before alerting that an agent is down
pipeline_stall_timeout_minutesnumber60Minutes before alerting a pipeline stall
error_rate_thresholdnumber (0–1)0.5Alert if error rate exceeds this fraction
error_rate_windownumber30Minutes, rolling window for error rate calculation
max_task_durationnumber45Minutes before alerting on a long-running task
max_replica_pause_minutesnumber30Minutes 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)
cost_alert_thresholdCostAlertThreshold—Cost alerting thresholds
alert_cooldownnumber30Minutes, deduplication window for alerts
alert_channelsMonitoringAlertChannel[][]Alert delivery channels
metrics_refresh_minutesnumber10How often to refresh pipeline metrics
consistency_refresh_minutesnumber5How 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_secondsnumber60How 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_minutesnumber10Minutes to suppress re-enqueueing a sweep task after completion (0 to disable)
agent_health_hoststring'localhost'Host for polling agent health endpoints
long_lived_state_ceiling_hoursnumber24Stall threshold in hours for paused, auto-recovering blocked, and open-children items
human_wait_ceiling_hoursnumber72owed_to_human threshold in hours for other awaiting-human items
human_wait_reminder_hoursnumber24Hours between repeat owed_to_human comments while an item stays waiting; the first posts when human_wait_ceiling_hours is crossed
daily_digestDailyDigestConfigenabled: false, time: '09:00'Scheduled daily pipeline digest delivery
weekly_digestWeeklyDigestConfigenabled: falseScheduled weekly pipeline digest delivery
authMonitorAuth—Credential for the monitor’s in-page login form and Authorization: Basic header (programmatic clients)
self_healingSelfHealingConfig(see below)Self-healing automation settings
regression_guardRegressionGuardConfig(see below)Pipeline health regression guard settings

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.

Used by agents.monitor.cost_alert_threshold.

FieldTypeDefaultDescription
daily_usdnumber—Alert when daily cost exceeds this USD amount
monthly_usdnumber—Alert when monthly cost exceeds this USD amount

Used by agents.monitor.auth.

FieldTypeDefaultDescription
usernamestringrequiredUsername for the monitor credential (used for in-page login and Authorization: Basic)
password_envstringrequiredName of the environment variable containing the password

Used by agents.monitor.daily_digest.

FieldTypeDefaultDescription
enabledbooleanfalseEnable scheduled digest delivery
timestring'09:00'Scheduled delivery time in HH:MM UTC format
channelsDailyDigestChannelConfig[][]Delivery channels. At least one channel is required when enabled: true

Used by agents.monitor.daily_digest.channels[].

FieldTypeDefaultDescription
type'slack' | 'webhook' | 'github_issue'requiredDigest delivery channel type
url_envstring—Environment variable containing the Slack or webhook endpoint URL
urlstring—Literal Slack or webhook endpoint URL
repostring—Target owner/repo for github_issue digest delivery

Used by agents.monitor.weekly_digest.

FieldTypeDefaultDescription
enabledbooleanfalseEnable scheduled weekly digest delivery
timestring'09:00'Scheduled delivery time in HH:MM UTC format
day_of_weeknumber1Day of week for delivery (0 = Sunday, 1 = Monday … 6 = Saturday, UTC)
channelsDailyDigestChannelConfig[][]Delivery channels. At least one channel is required when enabled: true

Used by agents.monitor.alert_channels.

FieldTypeDefaultDescription
type'github_issue' | 'webhook' | 'slack' | 'pagerduty' | 'item_comment'requiredAlert channel type
urlstring—Endpoint URL for webhook/slack/pagerduty
url_envstring—Name of the environment variable containing the endpoint URL
routing_keystring—PagerDuty integration routing key (literal value, not an env var name)
agents:
monitor:
alert_cooldown: 30
cost_alert_threshold:
daily_usd: 50
monthly_usd: 500
alert_channels:
- type: slack
url_env: COLONY_SLACK_WEBHOOK_URL
- type: pagerduty
routing_key: YOUR_PAGERDUTY_ROUTING_KEY
- type: webhook
url_env: COLONY_ALERT_WEBHOOK_URL
- type: github_issue
  • 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.

DetectorScopeClass
agent_downdeploymentaction
pipeline_stalldeploymentaction
high_error_ratedeploymentreport
projection_queue_backlog (deprecated)reporeport
long_running_taskitem or reporeport
repeated_reclaimitem or reporeport
cost_thresholddeploymentreport
token-expiryrepoaction
issue_stallitemreport
owed_to_humanitemaction
blocked_issue_thresholddeploymentreport
dead_letterdeployment (deprecated), item (digest)action
stuck_projections (deprecated)deploymentreport
failed_projections (deprecated)deploymentaction
failed_projectionitemaction
consistencydeploymentaction
kpi_regressionreporeport
fleet_shortfalltenantaction
replica_pausedtenantaction
outbox_stalledrepoaction
dead_lettersrepoaction
budget_breachrepoaction
daily_cost_ceilingtenantaction
stale_issueitemreport
sla_breachitemreport
intake_faileditemaction
circuit_breaker (trip)repoaction
circuit_breaker_reset (all-clear)reporeport
token_expiry (worker)repoaction
fatal_workerrepoaction

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.

Used by agents.monitor.self_healing.

FieldTypeDefaultDescription
max_auto_unblocks_per_issuenumber—Maximum automatic unblocks per issue before requiring manual intervention (used by auto_repair_stale_blocked)
auto_restartbooleanfalseEnable automatic agent restart on failure
restart_strategy'pid' | 'systemd' | 'pm2''pid'Process restart mechanism
restart_cooldownnumber300Seconds between restart attempts
max_restart_attemptsnumber3Maximum restart attempts before giving up
restart_dry_runbooleanfalseLog restart actions without executing them

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.

FieldTypeDefaultDescription
enabledbooleanfalseEnable the regression guard
current_window_hoursnumber24Hours in the recent (current) measurement window
baseline_window_daysnumber7Days in the baseline measurement window
relative_thresholdnumber (0–1)0.25Fractional degradation that counts as a regression
min_samplesnumber20Minimum sample floor — regressions are not reported below this count
kpisRecord<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:

KPIRegresses on
block_raterise
failure_blocked_raterise
review_pass_ratefall
mean_cost_per_issuerise
mean_turns_per_issuerise
reimplement_loop_raterise
dead_letter_raterise

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

agents:
monitor:
regression_guard:
enabled: true
current_window_hours: 24
baseline_window_days: 7
relative_threshold: 0.25
min_samples: 20
kpis:
block_rate: true
review_pass_rate: true
mean_cost_per_issue: true

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.

FieldTypeDefaultDescription
Common fields—Inherits enabled, poll_interval, health_port from Common AgentConfig Fields; defaults depend on deployment configuration
heartbeat_intervalnumber—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_retriesnumber3Max failures for a repo+issue+taskType combination within 60 minutes before dropping re-enqueue
max_task_durationnumber45Minutes before a task execution is considered timed out and aborted
max_task_reclaimsnumber3Minimum 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_thresholdnumber3Minutes 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_prepbooleanfalsePre-create worktrees for pending develop tasks while the worker is idle
unknown_tenant_retry_minutesnumber5Minutes 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:

  • resolveIntakeMode(repoConfig, config) — resolves intake_mode
  • resolveAutoMerge(repoConfig, config) — resolves auto-merge behavior
  • resolveSelfImprovement(repoConfig, config) — resolves self_improvement settings
  • resolveDependabotConfig(repoConfig, config) — resolves dependabot settings (per-field fallback)
  • resolvePatternMemory(repoConfig, config) — resolves pattern_memory settings
  • resolveCodeMap(repoConfig, config) — resolves code_map settings
  • resolveSla(repoConfig, config) — resolves sla settings (stays unset when neither tier sets it)

Controls Colony’s self-improvement feature, which allows Colony to file issues against itself.

FieldTypeDefaultDescription
enabledbooleanfalseEnable the self-improvement feature
labelstring'colony:self-improvement'GitHub label used to tag self-improvement issues
cooldown_minutesnumber (≥1)30Minimum minutes between self-improvement issue filings
max_open_issuesnumber (≥1)5Total 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
tracksSelfImprovementTrack[]—Per-track configuration for self-improvement. See deprecated fields

Controls the complexity calibration feature used to tune issue complexity estimates.

FieldTypeDefaultDescription
lookback_daysnumber7Number of days of historical issues to consider when calibrating complexity estimates

Controls epic decomposition and completion behavior.

FieldTypeDefaultDescription
use_feature_branchesbooleanfalseCreate 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_subtasksbooleantrueAutomatically merge approved subtask PRs whose base is an epic integration branch. false leaves an approved subtask PR for a human instead of merging it
reviewEpicReviewConfig(see below)Final epic review remediation and human-review controls

Used by epic.review.

FieldTypeDefaultDescription
auto_fix_threshold'minor' | 'none''minor'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_cyclesnumber3Maximum automated remediation cycles before escalation
require_human_final_reviewbooleantrueRequire a human final review after automated epic review/remediation completes
coverage_floornumber0Fraction (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.
adversarialbooleanfalseEnables 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_maxnumber3Maximum 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_waitnumber7200Maximum 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_pathsstring[]['**/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_linesinteger150Maximum 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:

  1. 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).

  2. 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:

    RouteMeaning
    APPROVENo actionable real finding — nothing at or above blocking_severity, and no minor finding eligible for auto-fix; the epic PR is approved
    AUTO_FIXEvery 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.
    REMEDIATEAny 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
    ESCALATECoverage 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 metedge-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 pathretry-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 justificationperformance — 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.

Registers executor plugins available to the worker.

FieldTypeDefaultDescription
registeredPluginRegistrationEntry[][]Plugin modules to load at startup

Used by plugins.registered[].

FieldTypeDefaultDescription
namestringrequiredPlugin name. Must match the manifest name returned by the loaded module
modulestringrequiredModule path or bare package specifier. Relative paths resolve from colony.config.yaml
tenantsstring[]['*']Tenant IDs allowed to use the plugin’s executors. '*' allows any tenant

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.

Controls learned routing and promotion behavior.

FieldTypeDefaultDescription
auto_promoteIntelligenceAutoPromoteConfig(see below)Confidence-gated promotion of observations
embeddingEmbeddingConfig(see below)Semantic-vector embedding provider used to compute intelligence scores
reconcileIntelligenceReconcileConfig(see below)Embedding-based deduplication on write — reinforce near-duplicates instead of inserting
retrievalIntelligenceRetrievalConfig(see below)Multi-source repo-intelligence retrieval service (always on)

Used by intelligence.auto_promote.

FieldTypeDefaultDescription
enabledbooleanfalseEnable automatic promotion of high-confidence observations
confidence_thresholdnumber0.8Minimum confidence required before an observation can be promoted
min_observation_countnumber2Minimum number of supporting observations required for promotion

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

FieldTypeDefaultDescription
reinforce_thresholdnumber0.9Cosine-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.

FieldTypeDefaultDescription
token_budgetnumber1200Bounds 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_sourcenumber5Maximum snippets returned per source before cross-source ranking (must be ≥ 1)
similarity_thresholdnumber0.3Cosine similarity floor for the embedding-based recall signal (0–1)
re_enrichment_enabledbooleanfalseEnqueue 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:

SELECT agent_role,
source_states->'codeMap'->>'state' AS code_map_state,
source_states->'codeMap'->>'reason' AS code_map_reason,
count(*) AS retrievals,
percentile_cont(0.5) WITHIN GROUP (ORDER BY token_estimate) AS p50_tokens,
max(token_estimate) AS max_tokens
FROM repo_intelligence_retrieval_events
WHERE origin = 'agent'
AND source_states IS NOT NULL
AND created_at > now() - interval '7 days'
GROUP BY 1, 2, 3
ORDER BY 1, 2, 3;

Lower intelligence.retrieval.token_budget to cap the growth.

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.

FieldTypeDefaultDescription
enabledbooleanfalseEnable embedding computation (safe to leave false until backfill runs)
provider'openai''openai'Embedding provider (currently only openai is supported)
modelstring'text-embedding-3-small'Model name for embedding computation
dimensionsnumber1536Vector dimensions — must match the chosen model
api_key_envstring'OPENAI_API_KEY'Environment variable name holding the API key

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.

FieldTypeDefaultDescription
semantic_conflict_checkSemanticConflictCheckConfig(see below)Opt-in semantic-conflict analysis pass. Default off.
methodmerge | squash | rebasemergeHow 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.

FieldTypeDefaultDescription
enabledbooleanfalseEnable the semantic-conflict analysis pass
min_confidencenumber0.75LLM confidence threshold (0–1) at/above which the later PR is deferred for re-review
max_candidate_branchesnumber10Maximum concurrent branches to compare against — runaway backstop
modelstring—Optional model override for the focused semantic-conflict assessment
lookback_hoursnumber24How far back (hours) to consider recently-merged branches when scanning for semantic conflicts

Example:

merge:
semantic_conflict_check:
enabled: true
min_confidence: 0.8
max_candidate_branches: 15
lookback_hours: 48

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.

KeyTypeDefaultDescription
ignore_union_mergedbooleantrueIgnore 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_pathsstring[][]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.

overlap:
ignore_paths: ['CHANGELOG.md', 'docs/changelog/*']
ignore_union_merged: true
repos:
- owner: my-org
repo: my-repo
overlap:
ignore_paths: ['CHANGES.md'] # replaces the top-level list for this repo

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.

FieldTypeDefaultDescription
enabledbooleantrueMaster 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_roundsnumber3Maximum 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)
agentsobject(inherit enabled)Per-agent opt-in/out overrides — keys: analyzer, developer, reviewer, planner, merger

Example:

mailbox:
enabled: true
max_resume_rounds: 3
agents:
reviewer:
enabled: false # reviewer opts out of mid-run mailbox delivery

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 no repo_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
  • default is required when intake_rules is present; it is a workflow id string.
  • rules is an ordered array; each rule has a workflow id and a match object.
  • Within a single rule, all provided predicates must hold (AND across predicates).
  • labels matches if the issue carries any of the listed labels (OR within the list).
  • title_pattern and body_pattern are JavaScript-compatible regular expressions validated at config load time.
  • When intake_rules is absent, every issue resolves to colony-default — today’s behavior.
FieldTypeRequiredDescription
defaultstringYesWorkflow id used when no rule matches (or rules is absent)
rulesIntakeRule[]NoOrdered list of routing rules; first match wins
FieldTypeRequiredDescription
workflowstringYesWorkflow id for matching issues
matchIntakeRuleMatchYesPredicate set (at least one key)

At least one predicate must be specified per rule.

FieldTypeDescription
labelsstring[]Matches if the issue carries ANY of the listed labels (OR within the list)
issue_typestringMatches if the issue type equals this value (GitHub issue type or node id)
title_patternstringJavaScript-compatible regex tested against the issue title
body_patternstringJavaScript-compatible regex tested against the 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:

FieldTypeDefaultDescription
enabledbooleantrueEnables the strategist station. Resolves repo first (repos[].strategy.enabled), then global, then default
cadence.kind'cron'cronCron only — interval is rejected. Global only
cadence.exprstring0 3 * * 15-field cron expression (UTC); required when cadence is present. Global only
max_turnsinteger (≥ 1)40Max Claude turns per strategist run. Global only
effort'low' | 'medium' | 'high' | 'max'highReasoning effort for the strategist run. Global only
stagger_window_minutesinteger (1–10080)60Window across which per-repo runs are staggered. Global only
capacity_sharenumber (0–1)0.5Share of self_improvement.max_open_issues for strategy tracks; only applies with an active charter. Also settable per repo (repos[].strategy)
default_cooldown_minutesinteger (≥ 1)60Cooldown for strategy tracks created by strategy apply. Also settable per repo
default_selection_mode'human' | 'auto:first' | 'auto:preferred'humanSelection mode for strategy tracks created by strategy apply. Also settable per repo
approval'human' | 'auto'humanhuman: 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).

schema: 1
credentials:
azure_devops:
pat: <personal-access-token> # required; Azure DevOps PAT with Packaging read scope
organization: <org-name> # informational; not used by the renderer
feeds:
- url: https://<org>.pkgs.visualstudio.com/_packaging/<feed-name>/npm/registry/
kind: npm
scope: '@my-scope' # optional; derived from feed name if omitted
- url: https://<org>.pkgs.visualstudio.com/_packaging/<feed-name>/nuget/v3/index.json
kind: nuget
FieldTypeRequiredDescription
schemanumberrequiredSchema version. Must be 1. Any other value causes entrypoint to exit non-zero
credentials.azure_devops.patstringrequiredAzure DevOps Personal Access Token. Missing or null value causes entrypoint to exit non-zero
credentials.azure_devops.organizationstring—Azure DevOps organization name. Informational only; not used by the renderer
credentials.azure_devops.feedsarray—List of feed entries. Empty array or missing section is not an error — entrypoint exits 0 silently
feeds[].kind'npm' | 'nuget'requiredPackage manager for this feed
feeds[].urlstringrequiredFull registry/feed URL
feeds[].scopestring—npm scope to bind (e.g. "@acme"). For kind: npm only. Derived from the feed name in the URL if omitted
schema: 1
credentials:
azure_devops:
pat: ghp_xxxxxxxxxxxxxxxxxxxx
organization: myorg
feeds:
- url: https://myorg.pkgs.visualstudio.com/_packaging/my-npm-feed/npm/registry/
kind: npm
scope: '@myorg'
- url: https://myorg.pkgs.visualstudio.com/_packaging/my-nuget-feed/nuget/v3/index.json
kind: nuget
KindOutput fileFormat
npm~/.npmrcscope→registry mapping + base64-encoded _authToken
nuget~/.config/NuGet/NuGet.ConfigXML <packageSources> + <packageSourceCredentials>

All rendered files are written with mode 0600.

The following kind values are reserved for future use and are not processed in v1:

  • github — reserved; the existing scripts/git-credential-colony.mjs helper handles GitHub auth and is not superseded by this convention
  • pypi — future: ~/.config/pip/pip.conf
  • maven — future: ~/.m2/settings.xml
  • 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.

Mount your PEM-format root CA certificate(s) under /colony/keys/ca-certs/:

docker-compose.yml
services:
worker:
volumes:
- /path/to/ca-certs/:/colony/keys/ca-certs/:ro

Or mount individual files:

volumes:
- ./corp-root-ca.crt:/colony/keys/ca-certs/corp-root-ca.crt:ro

Any *.crt file in that directory is treated as a PEM-encoded root CA. The directory is operator-managed and never baked into image layers.

The entrypoint runs scripts/install-trusted-cas.sh before any other initialization. It propagates trust to:

Runtime / toolMechanism
curl, wget, apt, Azure CLISystem trust store via update-ca-certificates
dotnet restore, dotnet tool installSystem trust store (honored automatically)
Node.js, npm, npx, bunNODE_EXTRA_CA_CERTS env var pointing at a combined CA bundle

Certificates must be PEM-encoded with a .crt extension. If your CA certificate is in DER or PFX format, convert it before mounting:

Terminal window
# DER → PEM
openssl x509 -inform DER -in corp-ca.der -out corp-ca.crt
# PFX → PEM (extract CA cert only)
openssl pkcs12 -in corp-ca.pfx -nokeys -out corp-ca.crt
  • Empty or absent directory — exits 0 silently; trust stores are unchanged; behavior is identical to a standard deployment.
  • Malformed cert — entrypoint exits non-zero with a message naming the offending file. No agent process starts. Fix the certificate and restart.
  • Multiple certs — all .crt files in the directory are installed.
  • Cert rotation — replace files on the host and restart the worker. Trust stores are rebuilt from scratch on each start.
  • Cert contents — never logged. Log output only reports the count of certificates installed (e.g., install-trusted-cas: installed 1 CA certificate(s)).

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.

FieldTypeDefaultDescription
effort'low' | 'medium' | 'high' | 'max'—Claude effort level for the analyzer. Maps to claude --effort
max_turnsnumber100Maximum Claude turns for an analyzer run. A state-declared station config takes precedence. Replaces deprecated llm.analyzer_max_turns
FieldTypeDefaultDescription
repo_contextRepoContextConfig—Controls how the developer builds repository context for Claude Code
pr_overlap_thresholdnumber—Fraction from 0 to 1 of changed files that may overlap another open PR before blocking development
max_plan_filesnumber—Override the complexity gate threshold for planned files. Runtime default is floor(maxTurns / 10); set 0 to disable
auto_decompose_on_exhaustionbooleantrueRoute oversized issues to planner after developer turn-limit exhaustion
forbidden_pathsstring[]—Glob patterns the agent may not read or write. See Protected Paths.
read_only_pathsstring[]—Glob patterns the agent may read but not write. See Protected Paths.
self_validation_max_cyclesnumber (1–10)3Maximum self-validation repair cycles before escalating to human review.
ci_repair_max_cyclesnumber (1–10)2Maximum CI repair cycles before escalating to human review.

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.

FieldTypeDefaultDescription
effort'low' | 'medium' | 'high' | 'max'highClaude effort level for the reviewer (falls back to the built-in agents.reviewer.effort default)
max_turnsnumber500Maximum Claude turns for a reviewer run. A state-declared station config takes precedence. Replaces deprecated llm.reviewer_max_turns
FieldTypeDefaultDescription
max_turnsnumber200Maximum number of turns for the planner’s Claude session
effort'low' | 'medium' | 'high' | 'max'highClaude effort level for the planner
modelstring—Override the Claude model used by the planner
FieldTypeDefaultDescription
conflict_resolutionConflictResolutionConfig—LLM-assisted conflict resolution settings. See the agents.merger section for field details

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.

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

commands:
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.

FieldTypeDefaultDescription
ownerstringrequiredGitHub organization or user that owns the repository
repostringrequiredRepository name
token_envstring—Name of the environment variable containing the PAT for this repo. Either token_env or app is required
appGitHubAppConfig—Per-repo GitHub App credentials for the coder identity. Either app or token_env is required
ops_appGitHubAppConfig—Per-repo GitHub App credentials for the ops identity
ops_token_envstring—Name of the environment variable containing the PAT for the ops identity. Alternative to ops_app
bot_usernamestring—Display name shown for bot-authored comments and labels for this repo
workspaceRepoWorkspaceConfigrequiredPer-repo workspace settings. Overrides the global workspace section
reviewRepoReviewConfig—Per-repo review overrides. Only the fields in the explicit pick list can be overridden
self_improvementSelfImprovementConfig—Per-repo override for self-improvement settings
pattern_memoryPatternMemoryConfig—Per-repo pattern memory settings, overriding the top-level pattern_memory default. See fields below
code_mapCodeMapConfig—Per-repo code-map (symbol index) settings, overriding the top-level code_map default. See fields below
slaSlaConfig—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
workersWorkerPoolConfig—Per-repo worker pool settings. See fields below
default_stewardsstring[]—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
dependabotDependabotConfig—Per-repo Dependabot integration settings, overriding the top-level dependabot default. See fields below
workflowsRepoWorkflowMember[]—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.

FieldTypeDefaultDescription
enabledbooleantrueEnable pattern memory for this repo (required when the block is present)
max_resultsnumber (≥1)3Maximum number of pattern results to include in prompts (required when the block is present)
lookback_daysnumber (≥1)30Number 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.

FieldTypeDefaultDescription
enabledbooleanfalseEnable 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
injectbooleanfalseEmit 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_budgetnumber—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.

FieldTypeDefaultDescription
warn_after_minutesRecord<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
FieldTypeDefaultDescription
pool_sizenumber (integer ≥1)—Number of worker processes to run for this repo
memorystring—Container memory limit for worker processes (e.g. '4g', '6G')
health_port_startnumber—Starting port for sequential health check endpoint allocation. Port ranges must not overlap across repos

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.

FieldTypeDefaultDescription
auto_reviewbooleanfalseAutomatically 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_patchbooleanfalsePatch updates: deterministic checks + green CI, no LLM review, then merge. Also lets LLM-approved patch PRs merge
auto_merge_minorbooleanfalseMinor 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_breakingbooleanfalseControls 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_usernamesstring[]['dependabot[bot]']GitHub usernames to treat as Dependabot for triggering this integration
max_in_flightnumber3Max 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 typeauto_merge_patchauto_merge_minorBehaviour
patchtrueanyDeterministic checks + green CI, no LLM → approve → merge
patchfalsetrueLLM review → merge only on approve
minoranytrueLLM review → merge only on approve
patch / minornot enabled for itLLM review → on approve, human-review-ready (approved, not merged)
major (incl. 0.x) / unknownanyanyLLM 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.

FieldTypeRequiredDescription
workflow_idstringYesA builtin workflow id or a custom (non-builtin) id, pinned by (workflow_id, version)
versionnumberNoPinned version. When omitted, resolves to the latest registered version for this workflow id
defaultbooleanNoExactly one member of a non-empty workflows array must set this to true
matchIntakeRuleMatch[]NoPredicates (OR-ed) evaluated in priority order for non-default members; ignored for the default member
prioritynumberNoLower priority is evaluated first; first match wins. Default 0

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:

  1. 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.
  2. 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.
  3. 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.

Per-Repo Workspace Overrides (RepoWorkspaceConfig)

Section titled “Per-Repo Workspace Overrides (RepoWorkspaceConfig)”

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.

FieldTypeDefaultScopeDescription
repo_dirstringrequiredoverrides globalPath to the local git clone for this repo
base_dirstringrequiredoverrides globalBase directory for this repo’s worktrees. Supports {owner} and {repo} template tokens
setup_commandstring—overrides globalCommand 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_timeoutnumber300overrides globalSeconds to allow the setup command to run. Overrides the global workspace.setup_timeout
prebuild_commandstring—overrides globalCommand to run after setup_command to pre-build workspace packages. Overrides the global workspace.prebuild_command
review_workspace_basestring—overrides globalContainer-local path for ephemeral reviewer worktrees
skip_pre_push_hookboolean—overrides globalPass --no-verify to git push for this repo
branchstring'main'overrides globalDefault branch name for this repo
secret_env_varsstring[]—per-repo onlyNames 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
timeoutsTimeoutsConfig—per-repo onlyFine-grained clone and tooling timeouts. See fields below
FieldTypeDefaultDescription
clonenumber600 (recommended)Seconds before git clone is timed out
mise_installnumber600Seconds before mise install is timed out
mise_reshimnumber30Seconds before mise reshim is timed out
submodule_initnumber120Seconds before git submodule update --init is timed out
epic_review_pushnumber300Seconds before the epic reviewer auto-fix commit+push is timed out
epic_branch_mergenumber300Seconds 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_checknumber30Seconds 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_gitnumber120Seconds 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

Per-Repo Review Overrides (RepoReviewConfig)

Section titled “Per-Repo Review Overrides (RepoReviewConfig)”

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:

FieldTypeDescription
checksRecord<string, string | { command: string; blocking?: boolean }>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_checknumberSeconds to allow each check to run
require_ci_passbooleanRequire all CI checks to pass before merging
ci_check_timeoutnumberSeconds to wait for CI checks to complete
ci_required_checksstring[]Names of CI checks that must pass
ci_absent_check_gracenumberSeconds 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_commandstringCommand to auto-format code before review. Colony formats only when this is set
clean_verificationstringCache-defeating pre-handoff verification command (see global review.clean_verification for examples). When set, overrides the global value for this repo
auto_merge_on_approvalbooleanAuto-merge the PR when the reviewer approves
external_prsExternalPrReviewConfigExternal PR review settings (mode, filters, auto_approve). Per-repo value overrides the corresponding global review.external_prs fields (field-by-field fallback — unset fields inherit from global)
ci_repairCiRepairConfigOverride CI repair settings for this repo
max_review_cyclesnumberMaximum 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_rerunsnumberTimes a failed blocking check is re-run on the PR tree before the baseline step, for this repo (0 disables; max 5)
ci_flaky_rerunsnumberCI check runs that fail are re-run on the same head SHA this many times for this repo (0 disables; max 5)
flaky_quarantine_thresholdnumberFlake 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.

FieldTypeDefaultDescription
idstringrequiredUnique identifier for this tenant
namestring—Human-readable tenant name
appGitHubAppConfig—Tenant-level GitHub App credentials for the coder identity. Required unless ado is set or at least one repo in repos is a provider: 'ado' repo
ops_appGitHubAppConfig—Tenant-level GitHub App credentials for the ops identity
adoobject—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_envstring—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')
foundryobject—Per-tenant ClaudeFoundryConfig; overrides claude.foundry. Only used when the tenant’s effective provider is 'foundry'
gatewayobject—Per-tenant ClaudeGatewayConfig; overrides claude.gateway. Only used when the tenant’s effective provider is 'gateway'
cost_budgetobject—Cost budget settings for this tenant. See fields below
defaultsobject—Default settings cascaded to repos in this tenant that do not override them. Currently supports timeouts (TimeoutsConfig)
workersNomadPoolConfig—When set, enables nomad mode for this tenant: workers roam across all tenant repos. See fields below
reposRepoConfig[]requiredList of repositories belonging to this tenant

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.

FieldTypeDefaultDescription
monthly_usdnumber—Monthly spending cap in USD for this tenant

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.

Repository-scoped budget cap (budget_cap_usd)

Section titled “Repository-scoped budget cap (budget_cap_usd)”

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 = $2 WHERE 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 UPDATE SET 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.

FieldTypeDefaultDescription
pool_sizenumber (integer ≥1)requiredDesired replica count for nomad workers in this tenant
memorystring—Container memory limit for worker processes (e.g. '4g', '6G')
health_port_startnumber—Starting port for sequential health-check endpoint allocation
max_cached_reposnumber (integer ≥1)4LRU cap on warm RepoContexts per nomad worker. Limits idle worktree memory usage per worker
max_cache_disk_mbnumber—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_mbnumber20480Disk 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_mbnumber (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_reponumber2Per-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_minutesnumber30Age (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.

Per-agent-type keys alongside repos[].workers

Section titled “Per-agent-type keys alongside repos[].workers”

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 migrate deletes 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`)
executors:
developer:
pr_overlap_threshold: 0.5

The following fields are still accepted by the config loader but will be removed in a future release. Migrate away from them as soon as possible.


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

Migration: Each field has its own replacement:

# Before (deprecated)
llm:
analyzer_max_turns: 80
reviewer_max_turns: 300
developer_max_turns: 150
# After
executors:
analyzer:
max_turns: 80
reviewer:
max_turns: 300
claude:
scaling:
medium:
developer_max_turns: 150

Migration: Move all fields under agents.monitor. The loader still accepts monitoring: as a top-level key 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.

# Before (deprecated)
monitoring:
enabled: true
port: 9100
# After
agents:
monitor:
enabled: true
port: 9100

self_improvement.tracks (SelfImprovementTrack[])

Section titled “self_improvement.tracks (SelfImprovementTrack[])”

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:

FieldTypeDefaultDescription
namestringrequiredUnique identifier for this track
labelstringrequiredGitHub label applied to self-improvement issues filed on this track
cooldown_minutesnumberrequiredMinimum minutes between filings on this track
seed_titlestring—Title template for self-improvement issues filed on this track
seed_bodystring—Body template for self-improvement issues filed on this track
instructionsstring—Additional instructions injected into the developer prompt for this track
cadenceobject (kind, expr)—Firing schedule. kind: 'cooldown' uses cooldown_minutes; kind: 'cron' uses a cron expr. Internal cadence.expr is managed via the dashboard API
proposalobject (ProposalSlate)—Slate of issue sizes to propose. Internal proposal.slate structure is managed via the dashboard API
weightnumber—Fair-share seeding weight — must be ≥ 1 on an enabled track; sets the track’s share and slots within its pool