Organization Pipeline Defaults (Agents)
The tenant view of Standards → Settings (/standards/settings) is the editor for Colony pipeline and agent configuration. With a repository in scope, choose Show tenant settings to reach it. Changes here write to tenants.config.* in the Pipeline Store and become the default for every repository in the tenant. Repositories can override some fields; see Merge precedence below.
For the complete field catalog (all ~100 fields, types, and defaults) see the Configuration schema reference. For cost tuning and model routing guidance see the Tune Model Routing and Cost Caps guide.
Configuration sections
Section titled “Configuration sections”The page is divided into the following sections, accessible via the in-page section navigator:
| Section | Description | Applies |
|---|---|---|
| Claude Provider | API provider (Anthropic direct, Azure Foundry, or an AI gateway) and endpoint settings | Requires worker redeploy |
| Claude | CLI timeout, inactivity timeout, and API retry count | Applies live |
| Models | Per-role model overrides (Developer, Reviewer, Analyzer, Planner, Merger, Mayor conversation) | Applies live |
| Scaling | Per-complexity-tier model, effort level, and developer turn limits (small / medium / large) | Applies live |
| Agent Turn Limits | Analyzer and reviewer max turns (defaults 100 and 500). Not affected by Scaling tiers; the planner’s limit is under Advanced: Execution | Applies live |
| Model Routing | Task-type × complexity-tier model routing matrix and global override | Applies live |
| Engine | Per-agent execution engine selection (Claude Code or OpenAI Codex) and Codex CLI settings | Requires worker redeploy |
| Review | Auto-merge, CI requirements, review checks, diff limits, and external PR review | Applies live |
| Agents | Mayor poll interval, heartbeat timeout, issue intake mode, and whether and how often the Mayor replies to addressed comments | Applies live |
| Costs | Per-issue cost cap, budget headroom and calibration lookback; the daily cost cap is shown read-only; administrators change it in Budgets | Applies live |
| Workspace | Worktree cleanup, stale-worktree pruning, and setup timeout | Applies live |
| Labels | Colony-managed label prefix | Requires worker redeploy |
| White-Label | Slash-command root prefix | Requires worker redeploy |
| Workers | Worker heartbeat interval, task retry limit, and task duration deadline | Applies live |
| Epic Execution | Feature-branch strategy, subtask rebase, and final-PR review policy | Requires worker redeploy |
| Dependency updates | Whether Colony reviews dependency updates automatically, which update types (patch, minor) may merge on their own, whether migration issues are filed for breaking changes, the bot accounts treated as dependency updates, and the most dependency updates in progress at once in each repository (default 3). These are the org-wide values; a repository can override any of them (see below). | Applies live |
| Self-Improvement | Autonomous self-improvement issue generation | Applies live |
| Pattern Memory | Few-shot pattern retrieval from past issue resolutions | Requires worker redeploy |
| Code Boundaries | Forbidden and read-only path globs for the developer agent | Requires worker redeploy |
| Conflict Resolution | LLM-assisted merge conflict resolution via the merger agent | Requires worker redeploy |
| Merging | How Colony merges a change (merge commit, squash or rebase), plus the opt-in pre-merge analysis that finds concurrent changes to semantically coupled files across branches and defers the later PR for re-review. Different from Conflict Resolution, which resolves git text conflicts | Requires worker redeploy |
| Advanced: Execution | Repo context bundle, plan-file gate, overlap threshold, and per-executor effort overrides | Requires worker redeploy |
| Advanced: Reliability | Mayor auto-unblock, sync intervals, and starvation thresholds | Requires worker redeploy |
| Attribution | EU AI Act Article 50(1) disclosure footer | Applies live |
| Intelligence | Repo intelligence auto-promotion thresholds, embedding settings, retrieval tuning (intelligence.retrieval.*) and the analyzer code-map snapshot (code_map.*). Retrieval always runs and is injected into every agent’s prompt. The former retrieval enable, injection and per-role switches (intelligence.retrieval.{enabled,inject,agents}) are removed; the keys are still accepted and ignored. | Applies live |
Applies live means the change reaches running Workers within one heartbeat through the config_refresh command. Requires worker redeploy means the change takes effect on the next Worker redeploy.
Per-repository dependency update overrides
Section titled “Per-repository dependency update overrides”On Autonomy → Settings, with the repository in scope, use the dependency update rows to override any of the six dependency update settings for that repository alone, so you can pilot auto-review on a few repositories or keep auto-merge off where automated dependency merges are not acceptable. Each setting shows where its value comes from: this repository, the tenant, or the default. Choose Use the tenant value to drop an override. Changes reach running workers within one heartbeat.
Using an AI gateway
Section titled “Using an AI gateway”Choose AI gateway under Claude Provider to route Claude Code through an Anthropic-compatible gateway such as LiteLLM or TrueFoundry.
| Setting | Where | Notes |
|---|---|---|
| Gateway Base URL | Standards → Settings → Claude Provider | Required, and must start with https:// |
| Disable experimental betas | Standards → Settings → Claude Provider | For gateways that reject Anthropic beta headers |
| Opus / Sonnet / Haiku models | Standards → Settings → Claude Provider | Optional model names to pin, as exposed by your gateway |
| Gateway Auth Token | Operations → Settings → Secrets (anthropic_gateway_auth_token) | Delivered to workers as ANTHROPIC_AUTH_TOKEN |
| Gateway Custom Headers | Operations → Settings → Secrets (anthropic_gateway_custom_headers) | Optional. One Name: value per line, passed unchanged as ANTHROPIC_CUSTOM_HEADERS. Write-only, because headers often carry credentials |
Changing the provider takes effect on the next worker redeploy. Cloud’s own platform features, such as the Mayor and draft assist, use Colony’s key unless an administrator turns on Mayor routing on Operations → Settings. With it on, they go through your provider, including your gateway, and never fall back to Colony’s key.
Representative fields
Section titled “Representative fields”The tables below cover the highest-impact fields. All other fields are documented in the Configuration schema reference.
Controls how much Colony may spend on Claude API calls before halting work.
| Field | Config key | Unit | Default | Description |
|---|---|---|---|---|
| Max cost per issue | claude.max_cost_per_issue | USD | none | Colony halts the task when this per-issue ceiling is reached. Set to 0 or leave blank for no limit. |
| Daily cost cap | max_daily_usd | USD | $50 | Read-only here. Administrators change the daily cost cap in Budgets, with a reason; the page shows $50 (default) until a value is stored. All pipeline work halts when the effective ceiling is reached and resumes at the next UTC midnight. |
| Budget headroom | budget_headroom_pct | % | 10 | Share of the daily cost cap held back to absorb overage from concurrent Workers. The effective daily ceiling is max_daily_usd × (1 − pct/100), so $45 with the defaults. |
| Daily ceiling comment | daily_ceiling_comment | — | Off | Post a comment on the most recently updated open item when the daily cost ceiling halts work. |
| Calibration lookback | calibration.lookback_days | days | 7 | Days of issue history the analyzer uses to calibrate complexity estimates. Leave blank for the default. |
The monthly tenant ceiling and per-repo caps aren’t set here. Set them in Operations → Settings (/operations/settings); see Cost & Budget and Dashboards.
Scaling tiers
Section titled “Scaling tiers”Colony classifies each issue as small, medium, or large based on the analyzer’s complexity estimate. Each tier has independent model, effort, and turn-limit settings.
| Tier | Field | Config key | Description |
|---|---|---|---|
| small / medium / large | Model | claude.scaling.<tier>.model | Override the Claude model for this tier. Leave blank to use the global model setting. |
| small / medium / large | Effort | claude.scaling.<tier>.effort | Reasoning effort level: low, medium, high, or max. Higher effort uses more tokens but produces better results on complex tasks. |
| small / medium / large | Developer max turns | claude.scaling.<tier>.developer_max_turns | Maximum conversation turns the developer agent may take for issues at this tier. Each turn is one Claude Code CLI invocation. (turns) |
Additional per-tier fields (backstop_max_turns, no_progress_window, planning_max_turns) are documented in the Configuration schema reference.
Agents (intake mode)
Section titled “Agents (intake mode)”Controls which issues Colony picks up for processing.
| Field | Config key | Values | Default | Description |
|---|---|---|---|---|
| Intake mode | agents.sprint_master.intake_mode | all | tagged | tagged | all processes every new issue automatically; tagged processes only issues that carry the Colony intake label. |
Workers
Section titled “Workers”Controls how managed Colony Workers communicate with the Cloud API and how long a task may run.
| Field | Config key | Unit | Default | Description |
|---|---|---|---|---|
| Heartbeat interval | workers.heartbeat_interval | seconds | — | Seconds between Worker heartbeat pings to the Colony Cloud API. |
| Max task retries | workers.max_task_retries | count | — | Maximum consecutive failures for a repo + issue + task-type combination within 60 minutes before the task is permanently dropped. |
| Max task duration | workers.max_task_duration | minutes | 45 | Wall-clock deadline per task. Workers abort and fail the task if it exceeds this limit. |
| Stale task threshold | workers.stale_task_threshold | minutes | 3 | Minutes a claimed task may go without a heartbeat before a Worker’s sweep reclaims it and requeues it for another Worker. Distinct from the Mayor’s Heartbeat timeout, which applies the same reclaim check on the Mayor’s sweep — raise both together to reliably delay reclaim. |
| Warm repos per worker | workers.max_cached_repos | count | 4 | Repositories each multi-repo (pool) Worker keeps warm at once. Applies to multi-repo Workers only; takes effect when replicas restart. |
| Clone cache budget | workers.max_cache_disk_mb | MB | No limit | Disk budget for a multi-repo Worker’s warm clones. Applies to multi-repo Workers only; takes effect when replicas restart. |
| Mirror budget | workers.max_mirror_disk_mb | MB | No limit | Disk budget for a multi-repo Worker’s shared object mirror. Applies to multi-repo Workers only; takes effect when replicas restart. |
| Toolchain budget | workers.max_toolchain_disk_mb | MB | No limit | Disk budget for a multi-repo Worker’s mise toolchain directory. When exceeded, tool versions no warm repo needs are uninstalled, oldest first. Applies to multi-repo Workers only; takes effect when replicas restart. |
| Max in-flight tasks per repo | workers.max_in_flight_per_repo | count | 2 | Most tasks one repository can have running across a multi-repo Worker at once. Applies to multi-repo Workers only; takes effect when replicas restart. |
| Cold repo escape | workers.cold_repo_escape_minutes | minutes | 30 | Minutes a task waits for a Worker that already has its repository warm before any Worker may take it and clone it cold. Applies to multi-repo Workers only; takes effect when replicas restart. |
Epic Execution
Section titled “Epic Execution”Controls how the final epic PR review fixes small findings itself. Changes to Epic Execution require a worker redeploy.
| Field | Config key | Unit | Default | Description |
|---|---|---|---|---|
| Auto-fix threshold | epic.review.auto_fix_threshold | minor | none | minor | Severity of findings Colony may fix in-session on the final epic PR. none escalates every finding. |
| Auto-fix line cap | epic.review.auto_fix_max_changed_lines | lines | 150 | Maximum added plus removed source lines an in-session auto-fix may change on the final epic PR. Test and documentation lines don’t count. A larger diff is reverted and the epic is approved with the minor findings as polish. Blank means 150. |
| Max remediation cycles | epic.review.max_remediation_cycles | count | — | Maximum remediation cycles for the final epic review. |
Merging
Section titled “Merging”| Field | Config key | Default | Description |
|---|---|---|---|
| How Colony merges a change | merge.method | Blank | merge, squash or rebase. Blank sends no method, so the code host merges with a merge commit. Applies to every repository in the organization, so repositories that allow different methods cannot all be satisfied. Epic changes into the default branch always merge-commit. |
Semantic Conflict Check
Section titled “Semantic Conflict Check”Two branches can merge cleanly as text and still break each other. One PR renames a config key while another adds a consumer of the old name, for example. When enabled, Colony analyzes concurrent changes to semantically coupled files before merging and defers the later PR for re-review. This differs from Conflict Resolution, which resolves git text conflicts.
| Field | Config key | Default | Description |
|---|---|---|---|
| Enabled | merge.semantic_conflict_check.enabled | Off | Opt-in. Colony changes nothing about merging until you turn it on. |
| Min confidence (0–1) | merge.semantic_conflict_check.min_confidence | 0.75 | Colony defers the later PR when the assessment’s confidence meets or exceeds this value. Lower values catch more conflicts and raise more false positives. |
| Max candidate branches | merge.semantic_conflict_check.max_candidate_branches | 10 | Most open branches Colony compares against. Raise it for repos with many parallel contributors. |
| Lookback (hours) | merge.semantic_conflict_check.lookback_hours | 24 | How far back Colony looks for recently merged branches when building the candidate set. |
| Model override | merge.semantic_conflict_check.model | Blank | Claude model for the assessment. Blank uses the global merger model. |
Execution engine
Section titled “Execution engine”The Engine section lets operators switch any agent role to the OpenAI Codex CLI on a per-role basis. By default, all roles use claude-code (the Claude Code CLI). Setting agents.<role>.engine: codex routes that role’s tasks to the Codex CLI instead.
Codex is opt-in — switching a role requires:
- The
OPENAI_API_KEYsecret to be configured in Operations → Settings. - Codex model IDs (e.g.
codex-1,o4-mini) to be set in the Codex model fields if you want to override the CLI default. - A Worker redeploy after saving — engine selection is read on startup and is not hot-reloadable.
claude.models.* and claude.scaling apply only to Claude Code-engine roles. When a role runs on Codex, configure its model via codex.models.<role> instead.
For the complete field reference see ## codex and Engine selection in the Configuration schema reference.
Merge precedence
Section titled “Merge precedence”This page edits the tenant-level (tenants.config) layer. A few settings can also be set for a repository group or a single repository: workflow, standards set, the analyzer, developer and reviewer models, review checks, timeout per check, required CI checks, CI check timeout, intake mode, auto-merge and the setup timeout, plus setup commands and dependency updates on the repository. For those, the most specific level wins: repository, then groups by rank, then tenant, then Colony’s built-in default. Everything else on this page applies to the whole tenant. See Repo Settings.
Role permissions
Section titled “Role permissions”| Action | Required role |
|---|---|
| View org pipeline configuration | Owner or Admin |
| Save org pipeline configuration | Owner or Admin |
Both GET and PUT /api/orgs/:orgId/pipeline/config require the tenant-administrator grant (org-pipeline-config-read and org-pipeline-config-update). Without it, the tenant view of Standards → Settings shows the page inert and names the grant.
API reference
Section titled “API reference”| Method | Path | Access | Description |
|---|---|---|---|
GET | /api/orgs/:orgId/pipeline/config | Owner or Admin | Fetch the current org-level pipeline configuration. |
PUT | /api/orgs/:orgId/pipeline/config | Owner or Admin | Save the org-level pipeline configuration. |