A Claude Code router that is just an environment variable
TheRouter.ai is a Claude Code router. Claude Code uses Anthropic's native Messages API, and TheRouter implements a compatible /v1/messages endpoint, so setting ANTHROPIC_BASE_URL to https://api.therouter.ai routes every Claude Code request through the gateway. Configure all three model tiers — Haiku, Sonnet, and Opus — with one API key, get automatic failover when a provider fails, and enforce per-team spend controls. No proxy binary and no patched client.
Claude Code speaks Anthropic's Messages API. TheRouter implements it. Set ANTHROPIC_BASE_URL and every Claude Code request routes through one key — with failover and spend controls. No proxy binary, no patched client.
What a Claude Code router does
Out of the box, Claude Code sends every request straight to Anthropic using a single account credential. That is fine for one developer on one machine. It gets awkward as soon as you have a team: there is no shared budget, no per-developer usage breakdown, and a provider incident stops work outright.
A router sits between Claude Code and the upstream. Because Claude Code reads its endpoint from ANTHROPIC_BASE_URL, no patching or wrapper process is needed — you redirect the SDK and the gateway takes over authentication, model resolution, failover, and usage accounting. Claude Code's behaviour is unchanged; only what happens behind the request changes.
Setup
Install Claude Code, then set six environment variables — as shell exports or in ~/.claude/settings.json.
npm install -g @anthropic-ai/claude-code
export THEROUTER_API_KEY="sk-..." # Point Claude Code at TheRouter (root domain — no /v1) export ANTHROPIC_BASE_URL="https://api.therouter.ai" export ANTHROPIC_AUTH_TOKEN="$THEROUTER_API_KEY" export ANTHROPIC_API_KEY="" # Model names — use Anthropic-native format, not brand/model export ANTHROPIC_MODEL="claude-sonnet-4-6" export ANTHROPIC_DEFAULT_HAIKU_MODEL="claude-haiku-4-5" export ANTHROPIC_DEFAULT_OPUS_MODEL="claude-opus-4-6"
{
"env": {
"ANTHROPIC_BASE_URL": "https://api.therouter.ai",
"ANTHROPIC_AUTH_TOKEN": "sk-...",
"ANTHROPIC_API_KEY": "",
"ANTHROPIC_MODEL": "claude-sonnet-4-6",
"ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-4-5",
"ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-4-6"
}
}claude # inside Claude Code: /status # expect: # Model: claude-sonnet-4-6 # Small/fast model: claude-haiku-4-5 # Opus model: claude-opus-4-6 # API base: https://api.therouter.ai
The two mistakes that account for most failed setups
- Using
https://api.therouter.ai/v1as the base URL. Claude Code uses the Anthropic SDK, which appends the path itself — use the root domain. Only OpenAI-compatible tools take the/v1suffix. - Forgetting
ANTHROPIC_API_KEY="". If an Anthropic key already exists on your system, Claude Code may silently keep using it and your traffic never reaches the router.
What each variable does
ANTHROPIC_BASE_URL
Redirects all Anthropic SDK requests to TheRouter. Use the root domain — no /v1 suffix.
ANTHROPIC_AUTH_TOKEN
Your TheRouter API key, sent as the Bearer token.
ANTHROPIC_API_KEY
Set to an empty string. Prevents Claude Code from falling back to a direct Anthropic account using any key already on your system.
ANTHROPIC_MODEL
The default model for normal tasks (Sonnet tier).
ANTHROPIC_DEFAULT_HAIKU_MODEL
The model for lightweight and fast background tasks (Haiku tier).
ANTHROPIC_DEFAULT_OPUS_MODEL
The model for complex reasoning tasks (Opus tier).
Which models can Claude Code route to?
Claude Code validates ANTHROPIC_MODEL against its own list of known Anthropic model names, so the three tier variables must use Anthropic-native names such as claude-sonnet-4-6. That is a constraint of the client, not of the router — TheRouter resolves those names and dispatches to whichever upstream is serving them.
For the authoritative list of what your key can reach right now, call the catalog endpoint rather than trusting any fixed list on a marketing page:
curl https://api.therouter.ai/v1/models \ -H "Authorization: Bearer $THEROUTER_API_KEY"
Or browse the catalog on the models page, and see which upstreams back it on providers.
Fallback behaviour during a coding session
A long Claude Code session makes many requests. If any one of them fails because an upstream is degraded, the agent loop stalls at exactly the wrong moment. TheRouter handles this at the gateway: when an upstream returns an error, the request is rerouted to a healthy provider serving the same model, and Claude Code receives a normal successful response.
Which provider actually served a request is an internal routing decision, not something your session has to reason about or reconfigure. Read how routing decisions are made for the mechanics, or the high-availability use case for the broader picture.
Why route Claude Code at all?
Automatic failover
An upstream degrades mid-session → TheRouter reroutes to a healthy equivalent instead of breaking the agent loop.
One key for the whole toolchain
The same TheRouter key backs Claude Code and every OpenAI-compatible tool your team uses. No per-tool credential sprawl.
Team spend controls
Set per-team and per-key spending limits, and see token usage and cost per key in real time instead of one opaque account bill.
No data stored
TheRouter passes requests through without storing prompt or response content — your source code is not retained.
Claude Code router — FAQ
What is a Claude Code router?
Claude Code talks to Anthropic's native Messages API. A Claude Code router is a gateway that implements that same /v1/messages endpoint, so you can point Claude Code at it with the ANTHROPIC_BASE_URL environment variable. Every request Claude Code makes then flows through the gateway, which handles authentication, model resolution, failover, and usage accounting on your behalf.
How do I point Claude Code at TheRouter?
Set ANTHROPIC_BASE_URL to https://api.therouter.ai, set ANTHROPIC_AUTH_TOKEN to your TheRouter API key, and set ANTHROPIC_API_KEY to an empty string so Claude Code cannot silently fall back to a direct Anthropic connection. You can set these as shell exports or in the env block of ~/.claude/settings.json.
Why is the base URL the root domain and not /v1?
Claude Code uses the Anthropic SDK, which appends /v1/messages to whatever base URL it is given. So the correct value is https://api.therouter.ai with no /v1 suffix. OpenAI-compatible tools such as Cursor and Cline use https://api.therouter.ai/v1 instead. Mixing the two up is the most common setup failure.
Which model names should I use?
Use Anthropic-native names such as claude-sonnet-4-6, claude-haiku-4-5, and claude-opus-4-6. Claude Code validates ANTHROPIC_MODEL against its own list of known Anthropic models and will reject TheRouter's brand/model format. TheRouter resolves the native names automatically when the request arrives. Avoid date-suffixed names like claude-sonnet-4-6-20250514.
Can I configure all three Claude Code model tiers?
Yes. Claude Code uses three tiers, and each maps to its own variable: ANTHROPIC_MODEL for the default Sonnet-tier model, ANTHROPIC_DEFAULT_HAIKU_MODEL for lightweight and fast tasks, and ANTHROPIC_DEFAULT_OPUS_MODEL for heavy reasoning. Set all three so no tier silently falls back to a direct Anthropic connection.
What happens when an upstream provider fails?
TheRouter reroutes the request to a healthy equivalent for that model rather than surfacing the upstream error. From Claude Code's point of view the request simply succeeds, so a provider incident does not interrupt a coding session.
How do I verify the routing is actually working?
Open a new terminal so the environment variables take effect, run claude, and type /status. The status panel should show your configured model names and https://api.therouter.ai as the API base. If it still shows date-suffixed Anthropic model names, the overrides did not take effect.
Does routing Claude Code through a gateway change how it behaves?
No. TheRouter implements the same Messages API contract, including streaming and tool use, so Claude Code's agentic loop, file editing, and tool calls work as they normally do. What changes is billing, key management, and failover — all handled at the gateway rather than in the client.
Route Claude Code in under 2 minutes
Get a free TheRouter API key, set three environment variables, and run /status to confirm.