How a request is routed
Every request goes through three steps:1
Classify the request
The harness asks for an Opus-, Sonnet-, Haiku-, or Fable-class model, and Valar sorts the request into one of those four aliases. Anything that matches none of them is treated as Sonnet, the working tier for most coding traffic.
2
Assign the engineer to a cohort
Using the client id on the request (most harnesses send it as an
X-Valar-Client-Id header; Cursor, which cannot set headers, rides it as a token suffix), Valar assigns the engineer to one cohort in the key’s split. The assignment is deterministic and sticky, so the same engineer always lands in the same cohort for a given key and split. Their experience stays consistent from one request to the next.3
Resolve the target model
The cohort pins each alias to a target model. Valar looks up the target for the request’s alias and routes there. For example, an engineer whose cohort maps Sonnet to GLM-5.2 has their Sonnet-class calls served by GLM-5.2.
Auto mode vs. Manual mode
ValarCode has two ways to decide the split.- Auto (default)
- Manual
Valar picks the target model for you. A new coding key starts on Auto, so routing works before you configure anything. It starts on Balanced unless an organization admin picks another default under Settings > ValarCode settings > Default routing for new keys (Balanced, Max savings, Max quality, US only or Custom). The default applies to keys created after the change, including the ones engineers create with
valar login; existing keys keep their routing. With Custom, the admin names a model for each difficulty from the models every tool offers, and every tool on a new key starts on that same line-up. You can change any tool on the key afterwards.Auto runs the objective you pick under Optimize for, set per key and per tool on the routing screen:- Balanced (default): the best answer for the lowest cost.
- Max savings: the most cost-effective model that can do the work, using a stronger model for the hardest requests.
- Max quality: the strongest model for each request’s difficulty, prioritizing answer quality over cost, at a high reasoning effort. The dashboard shows what applies for the tab you are on. The effort level is a floor: a request that asks for more keeps its own setting, and a request that turns thinking off stays off.
- Custom: your own model for each difficulty. Valar still grades every request (hardest, hard, everyday, simple) and sends it to the model you chose for that level. If that model cannot take a request, the Balanced line-up for the level serves it. Each tool has its own four picks, and every level needs one. A fifth row, Side calls, names the model for Claude Code’s hidden permission and safety checks; leave it on Auto-routing to let Valar pick.
/model. On (the default), Auto-routing answers that request like any other. Off, the Claude model you picked serves it, and anything else you pick still uses the strategy above. The setting applies to the Claude Code CLI only: Claude Code Desktop keeps Auto-routing either way.On every tool’s tab, Pin a model by typing “Valar <model>” lets engineers keep one model for a session from inside their tool. It is one setting for the whole key, so it shows the same state on each tab. See Pin a model for a session.Pin a model for a session
On a key that routes on Auto, an engineer can keep one model for the rest of a session by sending “Valar” and the model’s name, such asValar Opus. It works in Claude Code, Claude Desktop, Cursor and Codex.
Turn it on
The setting is off by default. Under ValarCode → Setup → Model routing, pick the coding key or selection and turn on Pin a model by typing “Valar <model>”, then save with a reason. It applies to every tool on that key. While it is off, “Valar Opus” is ordinary text that the model reads like any other. Keys and people that follow the organization default use the default’s setting. An admin turns it on in Settings → ValarCode settings, under Default routing for new keys, or with SSO sign-in on, on Everyone else in Model routing. It takes effect at once, with no reason to save. New keys and selections start with the default’s setting.Pin, and switch back
Send the command as its own message:Valar Auto hands the session back to Auto. Another Valar <model> moves the pin.
The command can also open a message, with your request after it:
- “Valar” comes first, followed by a space, a dash, an underscore, a colon, a comma, a slash or a dot. The command may be wrapped in quotes or backticks.
- The model’s name can be its family (
Opus,Sonnet,GLM,Kimi), its family and version (Opus 5.5,glm5.3) or its model id (claude-opus-5-5). A family alone picks its newest model. - The command ends at a comma, colon, semicolon,
!, a period, a dash with spaces around it, a closing quote, a new line or the end of the message. Without one, it ends after the words that name a model, soValar Opus fix the flaky testpins Opus as well. What follows is your request.
What you see
The answer to the message that set the pin opens and ends with a label. Every later answer in the session ends with it:
A sentence that starts with Valar but names no model, such as “Valar status page is down”, is not a command. It reaches the model unchanged.
Scope
- A pin lasts for the session. A new session starts on Auto.
- Sub-agents and background requests keep Auto-routing.
- Spend limits, US only and your organization’s model access still apply. A model they rule out is not pinned.
- A request the pinned model cannot handle, such as an image for a model that cannot read one, is answered by a model that can.
Editing routing
Routing is set per coding key, or per selection with SSO sign-in on, in the dashboard under ValarCode → Setup → Model routing:- Pick the coding key or selection in the Configuring picker. With SSO sign-in on, it lists groups and people first, then your keys.
- Select the tool and routing mode. Under Manual, choose a target for each class on Claude Code or LibreChat, or one model for all requests on OpenCode. To compare mappings, split traffic across cohorts. Under Auto, choose an objective or use Custom to set a model for each difficulty.
- Enter a reason and save. If you use multiple cohorts, their shares have to total 100%.
Changes are versioned and take effect for new requests once you save. Because assignment is sticky to the current split, changing a cohort’s share can move some engineers to a different cohort. That is expected when you rebalance an experiment.
Cohorts
A cohort is one arm of a split. Each cohort has:- a share, the percentage of engineers it covers, and
- a target model for each alias: Opus, Sonnet, Haiku, and Fable, or one model for all requests on OpenCode.
Seeing which model answered
Under Auto mode the model that answers is usually not the one the harness asked for, and the response keeps echoing the requested id so the harness can restore a session. To see the real answer, an organization admin turns on Show serving model name in the response metadata headers under Settings → ValarCode settings. Valar then adds both of these to every coding response, whichever tool sent it:- an
x-valar-served-modelresponse header, and - a
served_modelfield in the response body, besidemodel.
model:
Both surfaces name the same model, so use whichever your tooling can read. A body that reports an
error carries no
served_model, because no model answered it.
A response served on one of your organization’s own provider keys also carries an
x-valar-served-byok header naming which one: see Bring your own key.
Under each answer
Claude Code, Cursor and Codex show neither response headers nor extra body fields. A second switch beneath the first, Show serving model name in the response body, adds a line at the end of each answer Auto routed:auto-balanced, auto-max-savings,
auto-max-quality, auto-us-only or auto-custom), then the model. An answer routed through a
manual mapping names the model alone.
The line is added only to a finished answer. It is never added to a step where the agent calls a
tool, or when you picked a specific model yourself. Valar also leaves it off the background
requests it recognizes in Claude Code, Claude Desktop, OpenCode, Pi, Oh My Pi and GitHub Copilot,
such as sub-agents, conversation titles and compaction summaries. One exception: in GitHub Copilot,
a general sub-agent’s answer can still carry the line. Valar removes the line from the
conversation history before your next request reaches the model, so the model never sees it.
Turning the first switch off turns this one off with it.
Once the switch is on, every coding key carries the line by default. A key can opt out on its own:
under ValarCode > Setup > Model routing, pick the key and turn off Name the serving model in
responses. With SSO sign-in on, a selection has the
same switch. It applies, in every coding tool, to the people the selection routes, and only admins
can change it. A request made with a coding key follows that key’s switch. While the organization
switch is off, these controls are locked. Copy routing from carries this switch with the
mapping, between keys and selections alike, as it does headroom compaction.
Some harnesses, Claude Desktop among them, expose neither headers nor raw bodies. For those, run
valar usage, which lists your recent requests
with the model that answered each one.Next steps
Models
Which models you can route to, and how each harness’s traffic is served.
Analytics & savings
Compare cohorts and see what each split saved.