Which model your agents run

Three things decide which AI model runs a given stage: the model tier the stage asks for, a specific model named on the launch config, and — if you turn it on — cost-aware routing choosing between models on your Allowed models list. This page walks through each one.

The tier a stage asks for

A launch config’s model:<tier> capabilities (model:opus, model:sonnet, or model:haiku) are a staffing requirement first: the engine only runs a stage on a config whose capabilities cover what that stage needs. See Capabilities for the full rule.

For the Claude harness, a model:<tier> capability does something more: if the config’s command doesn’t already name a specific model (see Naming a model outright below), CodeHerder launches the session on that tier. It prefers the tier the stage itself requires; if the stage names none, it falls back to the tier capability on the config, using the first one listed when the config carries more than one. This only applies to the Claude harness — a config running any other harness launches on whatever model that harness defaults to.

Naming a model outright

You can also pin a launch config to one exact model, rather than a tier, by passing --model and its value as two separate --arg flags, or with --env ANTHROPIC_MODEL=<model-id>, on ch agent config set or ch agent config add. If a config sets both, the --arg-based --model value wins.

ch agent config set <agent-id> --harness claude --arg --model --arg claude-sonnet-4-6

The rest of this page calls a config set up this way “pinned to a model.” A config that only carries a model:<tier> capability, with no --model/ANTHROPIC_MODEL of its own, is not pinned — it runs the tier’s default, as described above.

Allowed models

Allowed models is a list of models a pinned config is permitted to run. It exists for two reasons: it’s a safety rail — a session refuses to start if the model it’s told to run isn’t on the list — and it’s the set cost-aware routing picks from when it’s turned on.

config set always requires --harness or --command, and replaces the config’s command, arguments, and capabilities with exactly what that call provides — see What config set replaces vs. preserves. So set Allowed models on the same call as everything else you want the config to keep, including a --model pin from above:

ch agent config set <agent-id> --harness claude \
  --arg --model --arg claude-sonnet-4-6 \
  --cap model:sonnet \
  --allowed-model claude-sonnet-4-6 --allowed-model claude-sonnet-4-5

Allowed models itself is the exception in that call: leave --allowed-model off a later config set and the stored list is left exactly as it was, the same way persona, system prompt, and Credential refs are. Command, arguments, and capabilities have no such protection — this is the one asymmetry worth remembering, since the flag that survives an omitted update sits right next to flags that don’t. To clear Allowed models back to no restriction without losing anything else, repeat every value you want to keep and pass --allowed-model "" on its own:

ch agent config set <agent-id> --harness claude \
  --arg --model --arg claude-sonnet-4-6 \
  --cap model:sonnet \
  --allowed-model ""

From the web app, open the agent’s detail page, find its launch config in the Agent templates panel, and fill in the Allowed models field — a comma- or space-separated list with the same behavior as the CLI, without the replace-on-omit risk since the web form always shows and resubmits the launch config’s current values. Its hint text spells out the rule: “Empty = no restriction; a model outside this list is refused by the device at spawn time.” Leave it empty and the config can run any model; the read-only config view then shows (no restriction), or a chip per model when the list isn’t empty.

Include the model your config is pinned to. With cost-aware routing on — the default for new workspaces — CodeHerder tells the device which model to run on every spawn of a pinned config, even when that model is the pinned model itself, unchanged. If that model isn’t on a non-empty Allowed models list, the device refuses to start — the session you see ends immediately, with an exit reason telling you the model wasn’t in the allowed list. Whenever you set Allowed models on a pinned config, make sure the pinned model is one of the entries.

List at least two models of the same tier if you want routing to do anything. Cost-aware routing only ever chooses among Allowed models in the same tier as the model your config is pinned to. One entry — or an empty list — gives it nothing to choose between, so the pinned model always runs.

How cost-aware routing chooses

Cost-aware routing looks only at a stage whose config is pinned to a specific model, and only ever moves it to a cheaper model in the same tier from that config’s Allowed models — never up, and never across tiers. It only makes that move when the cheaper model has a recent track record on that same kind of stage that hasn’t done materially worse than the pinned model’s own; otherwise your pinned model runs, unchanged.

See Cost-aware model routing for how to turn it on and where to see what it has saved.

Escalation is a different thing

Automatic model escalation moves a stage to a more capable model after a rework attempt is rejected — the opposite direction from routing, and triggered by a different event. See Automatic model escalation on rework for what triggers it, and Understanding costs for its effect on spend.

Related guides

• Capabilities — the full rule for model:<tier> and every other capability label
• Agents and the CLI — creating agents and launch configs, and the full config set/config add flag reference
• Understanding costs — turning on cost-aware routing and reading what it has saved
• How work flows — stages, gates, and automatic model escalation on rework