| name | switch-models |
| description | Use when someone wants to change which OpenRouter (or Claude) models the proxy routes to — swapping a model behind an alias, retargeting an agent, overriding at runtime, or checking that slugs are still live. |
Switching models
The model menu lives in routes.toml under [models]: friendly aliases →
"<upstream>:<slug>". Everything below is a way to change that mapping or which
alias an agent uses. The proxy hot-reloads routes.toml on save (and keeps
the previous config if an edit is invalid), so most changes need no restart.
The mux CLI
bin/mux models
bin/mux set flagship openrouter:z-ai/glm-6
bin/mux use glm-researcher reasoner
bin/mux check-latest
set <alias> <upstream:slug> rewrites just that alias's value in
routes.toml, validating the spec first (anthropic: or openrouter:).use <agent> <alias> rewrites the <<route:alias>> tag inside
.claude/agents/<agent>.md, so that agent now routes to a different alias.
Runtime override (no file edit)
Override any alias for a single proxy run with an env var named
MUX_MODEL_<ALIAS> (uppercase; hyphens become underscores):
MUX_MODEL_FLAGSHIP=openrouter:qwen/qwen3.7-max bun run proxy
MUX_MODEL_CLAUDE_REVIEW=anthropic:claude-opus-4-8 bun run proxy
Handy for trying a model without touching tracked files.
How an agent chooses its model
An agent's model comes from the <<route:alias>> tag on the first content line
of its .claude/agents/<name>.md. The tag → alias → upstream:slug. To change
it, either edit the tag, bin/mux use, or repoint the alias with
bin/mux set.
Adding a new model or route
- Add an alias under
[models] in routes.toml
(myalias = "openrouter:vendor/slug").
- Optionally add a
routes entry (e.g. { when = { tag = "myalias" }, use = "myalias" }) — remember it's first-match, most-specific-first.
bin/mux models to confirm it loaded; the loader fails loud if an alias
is unknown.
After changing anything
Give it a quick real check:
bin/mux check-latest
bun run test:live
