Skip to content
Colony Docs

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:

  1. model_routing.override, when set;
  2. a matching model_routing.routes cell, when routing is enabled;
  3. 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-4-6
      large: claude-opus-4-8
    review:
      small: claude-sonnet-4-6

Empty cells inherit. Use provider-supported model identifiers for your deployment.

Understand the limits

Section titled “Understand the limits”
  • claude.max_cost_per_issue limits 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_usd limits aggregate spend for the UTC day. The Worker claim loop reserves budget_headroom_pct below 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 a limit to leave it unset. Do not use YAML null for max_daily_usd; the current validator expects a positive number when the key is present.

Apply the settings

Section titled “Apply the settings”
  1. Open Settings → Agents (/settings/agents).
  2. Configure role defaults under Models and tier-specific development behavior under Scaling.
  3. Enable Model Routing only for task/tier cells that should override those defaults. Treat the global override as a temporary force-model control.
  4. Under Costs, set the per-issue and daily limits. Leave a field blank to omit that limit.
  5. Save the configuration. New task invocations use the updated effective settings after configuration propagation.

Repository settings currently offer selected per-role model overrides and a separate monthly repository budget. They are not a full per-repository copy of the task/tier routing matrix, and a monthly budget should not be confused with max_daily_usd.

Verify behavior

Section titled “Verify behavior”

Run several representative issues; a single issue is too noisy for a routing conclusion. In Cloud Insights, compare cost by model and task over the same window and repository mix as the baseline. 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”