This page is the flat reference for every colony.config.yaml field. For a narrative guide that explains when and why to use each section, see Self-Host — Configuration .
Colony loads config from the first location found:
Path passed via the --config CLI flag
./colony.config.yaml (current working directory)~/.colony/config.yaml (user home directory)
Call resolveConfig() before any GitHub operations. It validates the config and resolves credentials from environment variables.
Variable Required Description GITHUB_TOKENrequired Personal Access Token for GitHub API access ANTHROPIC_API_KEYrequired Anthropic API key for Claude Code invocations DATABASE_URLrequired Postgres connection string
Authentication and identity settings for the target repository.
Field Type Default Description ownerstring required GitHub organization or user that owns the target repository repostring required Target repository name token_envstring 'GITHUB_TOKEN'Name of the environment variable containing the Personal Access Token appGitHubAppConfig — GitHub App credentials for the coder identity (Analyzer, Developer). Use instead of token_env for App-based auth ops_appGitHubAppConfig — Separate GitHub App credentials for the ops identity (Sprint Master, Reviewer, Merger) ops_token_envstring — Name of the environment variable containing the PAT for the ops identity bot_usernamestring — Display name shown for bot-authored comments and labels
Used by github.app and github.ops_app.
Field Type Default Description app_idnumber required GitHub App ID (found in the App settings page) private_key_pathstring required Path to the .pem private key file for this App installation_idnumber required Installation ID for this App on the target organization or repo
Field Type Default Description prefixstring 'colony'Prefix for pipeline state labels (e.g. colony:analyzing, colony:in-development). Change to run multiple Colony instances against the same repo with distinct namespaces
Controls how Colony creates and manages git worktrees for each issue.
Field Type Default Description repo_dirstring '.'Path to the local git clone of the target repository. Not required for Docker Compose deployments — workers clone automatically base_dirstring '~/.colony/workspaces/{owner}/{repo}'Base directory for worktrees. Supports {owner} and {repo} template tokens branchstring 'main'Default branch name. Override when the repo’s default branch is not main setup_commandstring — Command to run after creating a worktree, instead of the default npm install setup_timeoutnumber 300Seconds to allow the setup command to run before timing out prebuild_commandstring — Command to run after setup_command to pre-build workspace packages cleanup_after_mergeboolean trueRemove the worktree after a PR is merged prune_blocked_after_daysnumber 7Days before worktrees for blocked issues are automatically pruned review_workspace_basestring — Container-local path for ephemeral reviewer worktrees skip_pre_push_hookboolean — When true, passes --no-verify to git push
Connection settings for the Postgres pipeline store. Optional in config — if omitted, Colony reads DATABASE_URL from the environment. A Postgres connection is always required at runtime.
Field Type Default Description url_envstring 'DATABASE_URL'Name of the environment variable containing the Postgres connection string max_connectionsnumber 10Maximum connections in the pg connection pool idle_timeoutnumber 10000idleTimeoutMillis for the pg pool (milliseconds)sslboolean falseEnable SSL for Postgres connections. Required for most cloud-hosted Postgres instances
Field Type Default Description levelstring 'info'Pino log level: 'trace', 'debug', 'info', 'warn', 'error', 'fatal' format'json' | 'pretty''pretty'Use 'json' in production for structured log ingestion; 'pretty' for local development
Top-level scalar. Caps aggregate spend across all issues and repos for the current UTC day.
Field Type Default Description max_daily_usdnumber | null 50Maximum USD per UTC day. Set to null to disable the ceiling entirely
Field Type Default Description enabledboolean trueWhen false, no disclosure footer is appended. Disabling weakens EU AI Act Article 50(1) compliance — only disable after legal review textstring 'Orchestrated by [Colony](https://runcolony.com) — autonomous software development pipeline.'Disclosure text appended after a horizontal rule
Controls the local event log written by Colony agents.
Field Type Default Description enabledboolean — Enable or disable event logging dirstring '~/.colony/events'Directory where event log files are written retention_daysnumber 30Days to retain event log files before pruning
Configures the webhook receiver that listens for incoming GitHub webhook events. Omit if not running the webhook receiver.
Field Type Default Description enabledboolean required Enable the webhook receiver portnumber (1–65535) required Port for the webhook receiver HTTP server secret_envstring — Name of the environment variable containing the HMAC secret for verifying GitHub webhook payloads
Controls Claude CLI invocation behavior and model selection for all agents.
Field Type Default Description timeoutnumber 1800Overall Claude CLI invocation timeout in seconds max_retriesnumber 1Number of times to retry a failed Claude invocation inactivity_timeoutnumber 300Seconds without output before the process is killed with SIGKILL max_cost_per_issuenumber — USD cost cap per issue. When reached, the issue moves to failure-blocked. Omit for no limit binary_pathstring 'claude'Path to the Claude CLI binary provider'anthropic' | 'foundry''anthropic'API provider. Use 'foundry' to route through Azure Foundry foundryClaudeFoundryConfig — Azure Foundry settings. Only used when provider: 'foundry' modelsClaudeModelsConfig — Per-agent model overrides scalingClaudeScalingConfig — Per-complexity turn limits and model overrides
Used by claude.foundry.
Field Type Default Description resourcestring — Azure resource name. URL constructed as https://{resource}.services.ai.azure.com/anthropic. Mutually exclusive with base_url base_urlstring — Full Foundry base URL. Mutually exclusive with resource api_key_envstring 'ANTHROPIC_FOUNDRY_API_KEY'Environment variable holding the Foundry API key pin_models.opusstring — Pin the Opus deployment name pin_models.sonnetstring — Pin the Sonnet deployment name pin_models.haikustring — Pin the Haiku deployment name
Used by claude.models.
Field Type Default Description developerstring 'claude-opus-4-8'Model used for the developer agent reviewerstring 'claude-opus-4-8'Model used for the reviewer agent analyzerstring 'claude-sonnet-4-6'Model used for the analyzer agent plannerstring 'claude-opus-4-8'Model used for the planner agent mergerstring 'claude-sonnet-4-6'Model used for the merger agent
Used by claude.scaling. A map with keys small, medium, and large, each a ClaudeScalingEntry .
Field Type Default (built-in) Description developer_max_turnsnumber 80 / 150 / 250 (small/medium/large)Maximum Claude turns for a developer invocation at this complexity modelstring claude-sonnet-4-6 (small) / claude-opus-4-8 (medium/large)Override the model for this complexity level effort'low' | 'medium' | 'high' | 'max'high (small/medium) / max (large)Effort level hint passed to the Claude CLI planning_max_turnsnumber 500Maximum turns for planning sub-tasks at this complexity no_progress_windownumber — (75 for large only) Turns without measurable progress before aborting backstop_max_turnsnumber 500Hard turn ceiling regardless of other limits
Controls PR review behavior — deterministic check commands, LLM review rounds, CI gating, and merge policy.
Field Type Default Description checksRecord<string, string> {}Named shell commands to run as deterministic review checks (e.g. test: 'npm test'). Do not leave empty — without checks Colony uses LLM judgment alone timeout_per_checknumber 120Seconds allowed for each check command before it is killed max_review_cyclesnumber — Maximum LLM review rounds before giving up. Unlimited if unset max_reimplement_cyclesnumber — Maximum re-implement cycles after a review rejection. Unlimited if unset max_diff_linesnumber 3000Truncate the PR diff at this many lines when sending to the LLM reviewer rebase_before_checkboolean trueRebase the PR branch onto the base branch before running checks auto_merge_on_approvalboolean falseAutomatically merge the PR after the reviewer approves it require_ci_passboolean trueWait for all required CI checks to pass before merging ci_check_timeoutnumber 300Seconds to wait for CI checks to complete ci_required_checksstring[] []Names of CI checks that must pass. When empty, all checks must pass format_commandstring — Formatting command to run before review checks (e.g. 'npm run format:fix') empty_verdict_auto_approveboolean trueAuto-approve when the LLM returns an empty or unparseable verdict and all deterministic checks passed external_prsExternalPrReviewConfig mode: offExternal PR review settings
Used by review.external_prs. Controls how Colony handles PRs not part of its own pipeline.
Field Type Default Description mode'off' | 'on_request' | 'on_ready' | 'auto''off'When to review external PRs. off — disabled. on_request — only when a human comments /colony:review. on_ready — automatically when a PR is opened or transitions from draft to ready. auto — same as on_ready, with auto_approve flag available author_filterstring[] ['*']Allowlist of GitHub usernames to review. ['*'] means any author label_filterstring[] []Require all listed labels to be present on the PR before reviewing exclude_botsboolean trueSkip PRs authored by bot accounts exclude_draftsboolean trueSkip draft PRs auto_approveboolean falseReserved for future use — only valid with mode: auto
Configures the Colony agent processes.
All agent types share these base fields:
Field Type Default Description enabledboolean trueWhether the agent runs poll_intervalnumber 30Seconds between poll cycles (minimum 5) health_portnumber (per agent) HTTP health check port effort'low' | 'medium' | 'high' | 'max'— Claude effort level for this agent
Field Type Default Description Common fields health_port: 9100See Common AgentConfig Fields intake_mode'all' | 'tagged''tagged''all' picks up every new issue automatically; 'tagged' requires the colony:enqueue labelheartbeat_timeout_minutesnumber 5Minutes before reclaiming stale tasks from workers that stopped heartbeating sweep_cooldown_minutesnumber 10Minutes to suppress re-enqueueing a sweep task after completion label_sync_limitnumber 25Max issues to reconcile labels for per poll cycle projection_drain_limitnumber 50Max queued VCS write projections to drain per poll cycle
Uses bare AgentConfig with no additional fields. health_port: 9101.
Uses bare AgentConfig with no additional fields. health_port: 9103.
Field Type Default Description Common fields health_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 max_tooling_retriesnumber 2Poll-level retries for transient push failures forbidden_pathsstring[] — Glob patterns the agent may not read or write read_only_pathsstring[] — Glob patterns the agent may read but not write
Field Type Default Description enabledboolean — Enable repository context injection max_tokensnumber — Maximum tokens for the context payload tree_depthnumber — Depth of the directory tree to include
forbidden_paths and read_only_paths restrict which files the developer agent may access or modify. Paths are repo-relative and use minimatch glob syntax with { dot: true }.
forbidden_paths.env*, secrets/**).read_only_pathsinfrastructure/**, .github/workflows/**).
Field Type Default Description Common fields health_port: 9105See Common AgentConfig Fields max_turnsnumber 200Max Claude turns for planning modelstring — Override model for the planner
Field Type Default Description enabledboolean — Enable automated conflict resolution max_conflict_filesnumber — Maximum number of conflicting files to attempt resolution on max_conflict_regionsnumber — Maximum number of conflict regions to attempt resolution on timeoutnumber — Timeout in seconds for conflict resolution modelstring — Override model for conflict resolution auto_merge_high_confidence_resolutionsboolean — Automatically merge when conflict resolution has high confidence
Pipeline observability, self-healing, and Prometheus metrics. Disabled by default.
Field Type Default Description Common fields enabled: false, health_port: 9106See Common AgentConfig Fields agent_down_timeoutnumber 120Seconds before alerting that an agent is down pipeline_stall_timeout_minutesnumber 60Minutes before alerting a pipeline stall error_rate_thresholdnumber (0–1) 0.5Alert if error rate exceeds this fraction error_rate_windownumber 30Minutes, rolling window for error rate calculation cost_alert_thresholdCostAlertThreshold — Cost alerting thresholds alert_cooldownnumber 30Minutes, deduplication window for alerts alert_channelsMonitoringAlertChannel [][]Alert delivery channels metrics_refresh_minutesnumber 10How often to refresh pipeline metrics sweep_cooldown_minutesnumber 10Minutes to suppress re-enqueueing a sweep task agent_health_hoststring 'localhost'Host for polling agent health endpoints authMonitorAuth — Basic auth for the monitor HTTP API self_healingSelfHealingConfig (see below) Self-healing automation settings
Field Type Default Description daily_usdnumber — Alert when daily cost exceeds this USD amount monthly_usdnumber — Alert when monthly cost exceeds this USD amount
Field Type Default Description usernamestring required Username for basic auth password_envstring required Name of the environment variable containing the password
Field Type Default Description type'github_issue' | 'webhook' | 'slack' | 'pagerduty'required Alert 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)
Field Type Default Description auto_relabel_orphansboolean falseAutomatically relabel issues that have fallen out of the state machine worktree_cleanup_interval_hoursnumber 6Hours between worktree cleanup sweeps auto_unblock_transientboolean falseAutomatically unblock issues blocked by transient failures max_auto_unblocks_per_issuenumber — Maximum automatic unblocks per issue before requiring manual intervention auto_restartboolean falseEnable automatic agent restart on failure restart_strategy'pid' | 'systemd' | 'pm2''pid'Process restart mechanism restart_cooldownnumber 300Seconds between restart attempts max_restart_attemptsnumber 3Maximum restart attempts before giving up restart_dry_runboolean falseLog restart actions without executing them work_task_retention_daysnumber 31Days to retain completed work tasks before pruning
Per-repo worker pool configuration. Workers claim tasks from the Postgres work_tasks queue.
Field Type Default Description heartbeat_intervalnumber — Seconds between task heartbeats max_task_retriesnumber 3Max failures for a repo+issue+taskType combination within 60 minutes before dropping re-enqueue
When a field can be set both globally and per-repo, Colony resolves the value using this fallback chain:
repoConfig.<field> ?? config.<field> ?? default
Field Type Default Description enabledboolean falseEnable 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
Field Type Default Description lookback_daysnumber 7Days of historical issues to consider when calibrating complexity estimates
Executor-specific settings distinct from agent process infrastructure (poll_interval, health_port). If not set, values are auto-populated from the corresponding agents.* fields for backward compatibility.
Field Type Default Description effort'low' | 'medium' | 'high'— Claude effort level for the analyzer
Field Type Default Description repo_contextRepoContextConfig — Repository context injection settings pr_overlap_thresholdnumber — Number of overlapping files with another open PR before blocking development max_tooling_retriesnumber — Maximum retries for transient tooling errors effort'low' | 'medium' | 'high'— Claude effort level for the developer forbidden_pathsstring[] — Glob patterns the agent may not read or write read_only_pathsstring[] — Glob patterns the agent may read but not write self_validation_max_cyclesnumber (1–10) 3Maximum self-validation repair cycles before escalating to human review ci_repair_max_cyclesnumber (1–10) 2Maximum CI repair cycles before escalating to human review
Field Type Default Description effort'low' | 'medium' | 'high'— Claude effort level for the reviewer
Field Type Default Description max_turnsnumber — Maximum turns for the planner’s Claude session effort'low' | 'medium' | 'high'— Claude effort level for the planner modelstring — Override the Claude model used by the planner
Colony workers support an optional operator-mounted credential file at /colony/keys/credentials.yaml for authenticating against private package feeds.
Field Type Required Description schemanumber required Schema version. Must be 1 credentials.azure_devops.patstring required Azure DevOps Personal Access Token with Packaging read scope credentials.azure_devops.organizationstring — Azure DevOps organization name (informational only) credentials.azure_devops.feedsarray — List of feed entries feeds[].kind'npm' | 'nuget'required Package manager for this feed feeds[].urlstring required Full registry/feed URL feeds[].scopestring — npm scope to bind (e.g. "@acme"). For kind: npm only
For networks that perform TLS interception, mount PEM-format root CA certificates under /colony/keys/ca-certs/. The entrypoint propagates trust to the system trust store, Node.js (NODE_EXTRA_CA_CERTS), dotnet, and standard CLI tools before starting any agent.
For multi-repo and multi-tenant deployments. Single-repo deployments do not need these sections.
Field Type Default Description ownerstring required GitHub organization or user repostring required Repository name token_envstring — PAT for this repo. Either token_env or app is required appGitHubAppConfig — Per-repo GitHub App credentials for the coder identity ops_appGitHubAppConfig — Per-repo GitHub App credentials for the ops identity ops_token_envstring — PAT for the ops identity bot_usernamestring — Display name for bot-authored content for this repo workspaceRepoWorkspaceConfig required Per-repo workspace settings reviewRepoReviewConfig — Per-repo review overrides self_improvementSelfImprovementConfig — Per-repo self-improvement override intake_mode'all' | 'tagged'— Overrides global sprint master intake mode for this repo pattern_memoryPatternMemoryConfig — Per-repo pattern memory settings slaSlaConfig — Per-repo SLA thresholds workersWorkerPoolConfig — Per-repo worker pool settings dependabotDependabotConfig — Per-repo Dependabot integration settings
Field Type Default Description enabledboolean required Enable pattern memory for this repo max_resultsnumber (≥1) required Maximum pattern results to include in prompts lookback_daysnumber (≥1) required Days of history to search for patterns
Field Type Default Description warn_after_minutesRecord<string, number>— Map of pipeline state name to warning threshold in minutes
Field Type Default Description pool_sizenumber (integer ≥1) — Number of worker processes to run for this repo memorystring — Container memory limit (e.g. '4g') health_port_startnumber — Starting port for health check endpoint allocation
Field Type Default Description auto_reviewboolean — Automatically trigger a review cycle for Dependabot PRs auto_merge_patchboolean falseAuto-merge patch updates after deterministic checks pass auto_merge_minorboolean falseRequire LLM review for minor updates before merging auto_migrate_breakingboolean falseAutomatically create migration issues for breaking major updates bot_usernamesstring[] ['dependabot[bot]']GitHub usernames to treat as Dependabot
Field Type Default Description repo_dirstring required Path to the local git clone for this repo base_dirstring required Base directory for this repo’s worktrees branchstring 'main'Default branch name for this repo setup_commandstring — Command to run after creating a worktree setup_timeoutnumber 300Seconds to allow the setup command to run prebuild_commandstring — Command to run after setup_command review_workspace_basestring — Container-local path for ephemeral reviewer worktrees skip_pre_push_hookboolean — Pass --no-verify to git push for this repo secret_env_varsstring[] — Names of environment variables to inject into worker processes for this repo timeoutsTimeoutsConfig — Fine-grained clone and tooling timeouts
Field Type Default Description clonenumber 600 Seconds before git clone is timed out mise_installnumber 600Seconds before mise install is timed out mise_reshimnumber 30Seconds before mise reshim is timed out submodule_initnumber 120Seconds before git submodule update --init is timed out
The following review fields can be overridden per-repo. Fields not listed here are global-only.
Field Type Description checksRecord<string, string>Override review check commands for this repo timeout_per_checknumber Seconds to allow each check to run rebase_before_checkboolean Rebase before running checks require_ci_passboolean Require all CI checks to pass before merging ci_check_timeoutnumber Seconds to wait for CI checks ci_required_checksstring[] Names of CI checks that must pass format_commandstring Command to auto-format code before review auto_merge_on_approvalboolean Auto-merge the PR when the reviewer approves external_prsExternalPrReviewConfig External PR review settings
Groups repositories by tenant. Cannot coexist with top-level repos[].
Field Type Default Description idstring required Unique identifier for this tenant namestring — Human-readable tenant name appGitHubAppConfig — Tenant-level GitHub App credentials for the coder identity ops_appGitHubAppConfig — Tenant-level GitHub App credentials for the ops identity anthropic_api_key_envstring — Environment variable containing the Anthropic API key for this tenant cost_budgetobject — Cost budget settings (monthly_usd: number) defaultsobject — Default settings cascaded to repos in this tenant (currently supports timeouts) reposRepoConfig[] required List of repositories belonging to this tenant
The following fields are still accepted but will be removed in a future release.
Fields: llm.analyzer_max_turns, llm.reviewer_max_turns, llm.developer_max_turns
Migration: Use claude.scaling instead.
Migration: Move all fields under agents.monitor. The loader still accepts monitoring: as a top-level key for backward compatibility.
Migration: Manage tracks via the Colony Cloud dashboard or the monitor REST API (POST /api/si/tracks). YAML track definitions in the config file are ignored.