Skip to content

Model Routing

Model Routing is a section of the tenant’s pipeline configuration, on the tenant view of Standards → Settings. It lets you pin a specific Claude model to each combination of task type and complexity tier, so cheaper models handle simple work while higher-capability models handle complex work. For a step-by-step walkthrough of how to configure and verify routing, see the Tune Model Routing and Cost Caps guide.

PropertyValue
Config keymodel_routing.enabled
Defaultfalse (off)

Master switch for task-type × complexity-tier model routing. Disabling it stops lookups in the per-task, per-tier routes table, but it does not disable the Global override: an override still applies to every task until the field is cleared. With routing disabled and no override set, Colony uses the per-role models configured under Standards → Settings › Models (the claude.models.* fallbacks) for every task. When enabled, Colony consults the routes table after the override.


PropertyValue
Config keymodel_routing.quota_fallback
Defaulttrue (on)

Shown in the dashboard as Fall back to another model family on model-specific quota limits. When a request hits a model-specific quota 429, Colony retries on a substitute model family. Unchecking the box makes Colony wait for the quota window to reset instead, so every task stays on the model you chose, at the cost of delays when that model’s quota runs out.


PropertyValue
Config keymodel_routing.override
Defaultempty (inactive)

Global force-model kill-switch. When non-empty, this model is used for every Colony task — analyze, develop, review, merge, and plan — regardless of task type, complexity tier, or the per-task matrix below. It unconditionally overrides all other routing logic and is checked first before any other routing rule, even when Enable model routing is off.

Use this as an emergency brake (for example, to force a cheaper model during a cost spike) or for a temporary experiment. Clear the field to restore normal routing.

The override covers pipeline tasks only. The Mayor and draft assists in Colony Cloud do not read it: with Mayor routing on, they use the Mayor conversation model, or its default, mapped through your provider’s pin_models.

See also: Cost & Budget concepts — the three budget controls for how the force-model override interacts with daily (max_daily_usd) and monthly (cost_budget.monthly_usd) spend limits.


PropertyValue
Config keymodel_routing.routes[task][tier]
Defaultempty (all cells fall through)

A 5 × 3 matrix where rows are task types and columns are complexity tiers. Each cell specifies the Claude model to use for that task-type / tier combination.

Task types (rows): analyze · develop · review · merge · plan

Complexity tiers (columns): small · medium · large — assigned by the analyzer agent based on estimated issue scope.

Empty cells fall through to the next level in the resolution precedence chain (see Resolution precedence below). You only need to fill in the cells you want to override; omitting a cell is equivalent to “inherit from the role model.”

When Colony selects a model for an agent invocation, it walks the following chain from highest to lowest priority and uses the first non-empty value:

  1. model_routing.override — global kill-switch; if set, all other levels are skipped.
  2. The workflow station’s model — a model declared on the station.
  3. model_routing.routes[task][tier] — the per-task, per-tier matrix cell (skipped when model_routing.enabled is false).
  4. The repository’s model — analyzer, developer or reviewer, set on the repository’s Standards → Settings.
  5. claude.scaling[tier].model — the developer’s model for the complexity tier.
  6. claude.models.<role> — the per-role model under Standards → Settings → Models.
  7. Built-in default — Colony’s hard-coded model default.

With Foundry or a gateway, pin_models sets what the opus, sonnet and haiku aliases resolve to. It is not a level in this chain.

Quota fallback is not a level in this chain: it substitutes a model family only after a model-specific 429, and never when model_routing.override is set.

ActionRequired role
View model routing configurationOwner or Admin
Save model routing configurationOwner or Admin

Model routing is part of the tenant’s pipeline configuration saved via PUT /api/orgs/:orgId/pipeline/config, which requires the tenant-administrator grant (org-pipeline-config-update).

Model routing is set per tenant, and repositories cannot override it. A repository can set its own analyzer, developer and reviewer models on Standards → Settings; a model set by routing still takes precedence over them.