| name | getting-started |
| description | Use when someone has just cloned modelmux and wants to plug in OpenRouter and see heterogeneous routing working. Walks clone → install → key → run → verify, checking each step. |
Getting started with modelmux
Walk the user through these steps in order. Run the checks yourself where you
can, and confirm each step before moving on. Never print the value of an API key.
This is the from-source path (clone the repo, run with Bun). Running a prebuilt
binary instead? Skip install and run ./modelmux — see the README. The fuller
dev workflow is in docs/development.md.
1. Prerequisites
Confirm Bun is installed:
bun --version
If it's missing, either curl -fsSL https://bun.sh/install | bash or use DevBox
(devbox shell). Then install dev dependencies:
bun install
2. Plug in your OpenRouter key
The proxy needs an OpenRouter key for any non-Claude route
(https://openrouter.ai/keys).
cp .env.example .env
.env is gitignored — never commit it.
3. Start the proxy
bun run proxy
You should see modelmux listening on http://localhost:8787. Leave it
running in its own terminal.
4. Opt Claude Code into the proxy
Routing only happens when Claude Code points at the proxy:
cp .claude/settings.json.example .claude/settings.json
This sets ANTHROPIC_BASE_URL=http://127.0.0.1:8787. Restart Claude Code —
that env var is read once at startup, so an already-running session won't pick
it up.
5. See it route
In a fresh Claude Code session (proxy running, settings enabled), dispatch a
subagent — e.g. the bundled glm-researcher (tagged <<route:flagship>>) — then
inspect the decision log:
tail -n 5 decisions.jsonl
You want to see the subagent land on OpenRouter and the main loop stay on Claude:
{ "isSubagent": true, "matchedRule": "tag:flagship", "upstream": "openrouter", "resolvedModel": "z-ai/glm-5.2" }
{ "isSubagent": false, "matchedRule": "default", "upstream": "anthropic", "resolvedModel": "passthrough" }
6. (Optional) confirm the model slugs are live
bin/mux check-latest
Shortcut
You can also dispatch the setup-assistant agent to auto-check Bun, the key,
config validity, and the proxy, and report what's left.
Troubleshooting
OPENROUTER_API_KEY is not set (HTTP 400) → set the key in .env (step 2).- Connection refused → the proxy isn't running (step 3).
- Subagent still on Claude → you didn't restart Claude Code after step 4.
