Tune Model Routing and Cost Caps
Colony has three separate spend controls: role model defaults, optional task-and-tier routing, and cost limits. Measure a representative baseline before changing them so that lower spend is not confused with a change in issue mix.
Understand model resolution
Section titled “Understand model resolution”Model-routing rows are analyze, develop, review, merge, and plan; columns are small, medium, and large. Complexity begins with analysis and may be adjusted by routing signals such as decomposition or review history.
Resolution is:
model_routing.override, when set;- a matching
model_routing.routescell, when routing is enabled; - the configured model for the corresponding agent role and its built-in fallback.
The default is not one universal highest-capability model: defaults vary by role and, for development, can vary by scaling tier. Tasks such as external review are normalized to the appropriate routing row; tasks with no routing row use their role fallback.
model_routing: enabled: true routes: develop: small: claude-sonnet-5 large: claude-opus-5-5 review: small: claude-sonnet-5Empty cells inherit. Use provider-supported model identifiers for your deployment.
Understand the limits
Section titled “Understand the limits”claude.max_cost_per_issuelimits accumulated spend for one issue. Once enforcement detects the limit, further autonomous work is blocked. A final provider invocation can make recorded spend slightly exceed the configured value.max_daily_usdlimits aggregate spend for the UTC day. The Worker claim loop reservesbudget_headroom_pctbelow that number, so the effective stop threshold is lower than the headline cap. Work can resume after the next UTC reset or after the limit is raised.
Omit claude.max_cost_per_issue for no per-issue limit. Omit max_daily_usd and the $50 default daily cost cap applies. YAML null turns the daily ceiling off at runtime, but colony check fails its config stage because the schema expects a number, so do not use it unless you mean to run without a ceiling.
Apply the settings
Section titled “Apply the settings”- Open Standards → Settings (
/standards/settings). - Configure role defaults under Models and tier-specific development behavior under Scaling.
- Enable Model Routing only for task/tier cells that should override those defaults. Treat the global override as a temporary force-model control.
- Decide whether to keep Fall back to another model family on model-specific quota limits on (the default,
model_routing.quota_fallback). Leaving it on keeps work flowing during quota exhaustion. Turning it off keeps every task on the chosen model, at the cost of delays. See Quota fallback. - Under Costs, set the per-issue limit and, if you want, the budget headroom. Leave the per-issue field blank to omit that limit. The daily limit (
max_daily_usd) is the daily cost cap. It is shown read-only there, administrators change it in Budgets with a reason, and it defaults to $50. - Save the configuration. New task invocations use the updated effective settings after configuration propagation.
Repository settings currently offer only selected per-role model overrides. They are not a full per-repository copy of the task/tier routing matrix. Repository monthly caps and the monthly ceiling are set in Operations → Settings (see Dashboards), and a monthly budget should not be confused with max_daily_usd.
Set the fields in colony.config.yaml:
model_routing: enabled: true routes: develop: small: claude-sonnet-5 review: small: claude-sonnet-5
claude: max_cost_per_issue: 5
max_daily_usd: 50budget_headroom_pct: 10The configuration watcher can apply supported routing and cost changes to running processes. Check colony status for the latest reload result; redeploy if it reports keys that require one.
Verify behavior
Section titled “Verify behavior”Run several representative issues; a single issue is too noisy for a routing conclusion. In Colony Cloud, compare cost by model over the same window and repository mix as the baseline; see Cost & Budget (Cloud). In self-hosted telemetry, inspect model-resolution trace phases and cost events rather than searching for a model_selected log event—the runtime trace phase is model_resolved.
Also watch quality signals: clarification rate, review cycles, reimplementation, failures, and time to completion. A cheaper route that causes more retries may cost more overall.
What next
Section titled “What next”- Configuration Schema — model routing
- Triage a Stuck Issue
- Agents
- Cost & Budget (Cloud) — monitor live spend, review timeseries, and track budget burn rate after applying routing changes
- Cost & Budget concepts — how the three spend controls differ and what the projection figures assume