getting-started

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
# then edit .env and set OPENROUTER_API_KEY=sk-or-v1-...

.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.