Skip to main content
Routing decides which model serves each request an engineer’s harness makes. You set it once per coding key, and it applies to everyone using that key. With SSO sign-in, an engineer who signs in holds no key: they route on the selection that covers them, and each selection has routing of its own, set the same way as a key’s. Coding keys keep their own routing beside it.

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.
If a key’s or a selection’s routing cannot be read, ValarCode falls back to the frontier Claude tiers instead of failing the request, so a misconfiguration never blocks an engineer.

Auto mode vs. Manual mode

ValarCode has two ways to decide the split.
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.
On the Claude Code tab, Map Anthropic models to Valar’s Auto-router decides what happens when you pick a Claude model, such as Opus or Sonnet in /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 as Valar 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 answers it itself, with no model call, and every later request in the session goes to that model:
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, so Valar Opus fix the flaky test pins Opus as well. What follows is your request.
Valar removes the command before the model reads your message. The model answers only the request after it.

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:
Steps where the agent calls a tool carry no label. Valar removes these labels from the conversation history before your next request reaches the model. When the pin cannot be set, Valar says so and the session stays where it was: 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:
  1. Pick the coding key or selection in the Configuring picker. With SSO sign-in on, it lists groups and people first, then your keys.
  2. 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.
  3. 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.
A split holds 1 to 5 cohorts, and their shares add up to 100%. Engineers are spread across cohorts by the sticky assignment above, so a cohort set to 30% gets about 30% of your engineers and keeps them there rather than re-rolling on every request. That is what makes a controlled comparison possible. Put 70% of engineers on a cohort that targets Claude and 30% on an open-weight cohort, then compare cost and outcomes between the two in Analytics.

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-model response header, and
  • a served_model field in the response body, beside model.
On a non-streaming response the field is top-level on every lane. On a stream it sits wherever that lane’s dialect puts 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:
The line names the routing strategy that picked the model (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.