Ekamyth Agent OS docs
Added for agents / Right model, right cost

How routing works

Routing chooses the model that answers each model call your agents make. You see every choice with hero route.

How does routing work?

Routing is one part of how Ekamyth Agent OS runs your agents' work, next to rules, records, verdicts and the other efficiency levers. It's on after setup.

Your agents' model calls pass through the model gateway on their way to your provider. Routing sends each kind of work to the least expensive model we expect to do it well, and it keeps learning from outcomes. Every call shows the model you asked for and the model that answered, so you can always see what happened. The call goes to your provider with your own key or sign-in, and hero route shows you what happened.

Five numbered steps. Your agent makes a model call. Agent OS keeps the requested model or the call may move, and with routing off it always keeps it. The call goes to your provider. A moved call that fails is replayed once on the requested model. You see each call in hero route.
The numbers match the steps below.

Routing concepts

TermWhat it means
Model gatewayThe Agent OS process on 127.0.0.1 that your agents' model calls pass through.
Requested modelThe model your agent asked for.
Served modelThe model that answered the call.
KeptThe call was served by the requested model. hero route prints (kept).
MovedThe call was served by a different model. hero route prints the model your agent asked for, then a reason word, such as reason right_sized. right_sized: moved to a smaller model because measured evidence says it does this kind of work as well.
CensusA check of which of your agents send their model calls through this install's model gateway. Run it with hero route census.

The path of a routed call, step by step

  1. Your agent makes a model call. hero setup pointed Claude Code and Codex at the model gateway.
  2. Agent OS chooses the model. With routing on, it keeps the requested model or the call may move. With routing off, it always keeps the requested model. See Turn routing off.
  3. The call goes to your provider, with your own key or sign-in. Your provider's own limits apply.
  4. If a moved call fails, Agent OS replays it once on the model your agent asked for.
  5. You see the result. hero route lists each call, the model that served it, and whether it moved.

Where you see routing

WhereWhat it shows you
hero routeRecent calls, the model that served each one, which calls moved, and where your tokens went.
hero route censusWhich of your agents send model calls through the model gateway, and which don't.
hero efficiencyThe Route lever and the top model changes, next to the other levers.
hero healthRouting findings, which point to hero help route.
/hero:route in your agentInstalled by hero setup. Your agent runs hero route and explains the result.

How routing chooses a model

Routing data, and what leaves your machine

DataWhere it's keptLeaves your machine?
Your model callsSent through the model gatewayYes, to your own provider, as with any call your agent makes. A moved call stays with the provider your agent asked for, unless you ask for model auto or set HERO_ROUTE_LOCAL_MODEL to use a local model.
A record of each call: requested and served model, whether it moved, tokens and estimated cost. No prompt or response text.Your machineNo, not by default. Agent OS sends call records only if you opt in by setting HERO_LEARN_URL.

Agent OS also keeps a record of each call on your machine: the requested and served model, whether it moved, tokens and estimated cost. It holds no prompt or response text.

When part of routing fails

What failsWhat you seeWhat happens to the work
A moved call failshero route lists the call as kept. See Limits.Agent OS replays it once on the requested model, and your agent gets that answer.
The routing step itself failsThe requested model serves the call.The call keeps going.

Routing on Claude Code and Codex

Claude CodeCodex
Calls pass through the model gateway after setupYesYes
Shown in hero route censusYes, as claude-codeYes, as codex
How calls may moveSee Which calls may move.See How Codex calls may move.

What you can change in routing

SettingDefaultEffect
Routing offRouting onStart or restart the model gateway with HERO_ROUTE=0 in its environment to turn automatic routing off.
HERO_BILLING_RATES=<path>Public list pricesPoints at your own rate card. The cost and saving figures in hero route use it. Without it, figures are at public list prices, and the output says so. See Use your own rates.

See routing for yourself

Run these on your own machine to watch each step.

# Step 1: which agents send their calls through Agent OS
hero route census

# Steps 2 to 5: recent calls, the model that served each, moved or kept
hero route

To read the output line by line, see How to read the output.

Routing limits and next steps

Routing limits

LimitBehaviourWhat to do
A moved call the provider rejectsWhen the provider rejects a moved call, for example at a rate limit, Agent OS retries it on the model your agent asked for, so your agent still gets an answer. hero route lists that call as kept, and hero route list --only failed doesn't show it.Read the call in hero trace.
Refused calls in the route listhero route list can name a model as having served a call that Agent OS refused before sending it, for example when no agent session was ready or sign-in failed.Read the call in hero trace, which shows how it ended.
Savings figuresRoute savings can show as not measured. When a moved call fails, or calls move because a model was unavailable, the net saving at public list rates figure can overstate savings.Treat it as an estimate.
Monitor's route boardThe board can label a step down as "Moved to a larger model" and count failed calls as "Kept".Use hero route.

See Limits of hero route.

Checked against Agent OS 0.1.36rc14 (build 599c5e120c18) on 17 Nov 2026.