Claude Code Router: Setup, Model Switching and Risks
Claude Code Router explained: what the open-source gateway does, how to install it, connect providers and switch models, and the trade-offs to know first.
Josh Pocock8 min read
AI Coding
Code Router
Stride AI Academy
Claude Code Router (CCR) is an open-source gateway that runs on your own machine and sits between Claude Code and the model providers you pick. Claude Code sends its requests to the router at http://127.0.0.1:3456, and the router passes them on to whichever provider and model you've configured, including non-Anthropic ones. It's a community project, not an Anthropic product, and Anthropic doesn't support running Claude Code on non-Claude models.
This guide covers what the router does, how to install it, how to connect Claude Code and switch models, what it's useful for and what you give up. It also covers Anthropic's own documented way to point Claude Code at a gateway. Everything here was checked against the project's GitHub repository, the project's official docs, and Anthropic's LLM gateway docs, gateway connection guide and environment variable reference on November 18, 2026.
What Claude Code Router does
Despite the name, the project now describes itself as a local control plane for coding agents in general. Its README lists Claude Code, Codex, OpenCode and several other agents it can connect. The main features are:
- Providers: add a provider from a preset or a custom API address, with model discovery and a connectivity check.
- Agent profiles: a saved setup for each coding agent, with model overrides and launch settings.
- Routing: rules with conditions, request rewrites, retries and ordered fallback models.
- Client keys: separate keys for each client of the gateway, with limits.
- Logs: request logs with latency, token usage, cost estimates and errors.
It's MIT licensed. The router talks to providers in five formats, detected automatically: OpenAI Chat, OpenAI Responses, Anthropic Messages, Gemini generation and Gemini Interactions.
How a request moves through the router
- 1You send a prompt in Claude Code
- 2Claude Code calls the router on 127.0.0.1:3456
- 3The router applies your profile and routing rules
- 4The chosen provider and model answer
How to install Claude Code Router
You need Claude Code installed first. If you haven't done that, see how to install Claude Code.
The README recommends the desktop app. Download the build for your system from the repository's GitHub Releases page: .dmg or .zip for macOS, .exe for Windows, .AppImage for Linux.
For the command line version you need Node.js 22 or newer:
npm install -g @musistudio/claude-code-router
ccr uiccr ui starts the background service and opens the management screen at http://127.0.0.1:3458. The model gateway itself listens on port 3456. On a machine without a desktop, use ccr ui --no-open. The other service commands are:
ccr start # start the management service and gateway
ccr stop # stop the background service
ccr serve # run in the current terminal, useful for watching logsThere's also a Docker option. From the root of a clone of the repository, run docker compose up -d --build. The project's docs say to read their deployment guide before exposing the router beyond your own machine.
Where the configuration lives
You set the router up through its management screen rather than by editing a file. According to the CLI docs, it stores everything in a config folder:
| System | Folder |
|---|---|
| macOS and Linux | ~/.claude-code-router |
| Windows | %APPDATA%\claude-code-router |
Inside it, config.sqlite holds the app configuration and service.json holds the background service state and its private token. Treat that folder like any other place that stores API keys.
How to connect Claude Code
The setup follows the order in the project's install and agent profile docs:
- Add a provider. On the Providers page, click Add provider. Pick a preset or choose a custom API address, then paste your API key for that provider.
- Check connectivity. The check sends one real request with your key and model, so it can use a few tokens. Save the provider once it passes.
- Create a client key on the API Keys page.
- Start the service on the Services page.
- Add a Claude Code profile. Choose Claude Code, give the profile a name and pick its scope: only when opened from the router, or as the system default for Claude Code.
- Launch it from the terminal with the profile name:
ccr "my-profile"The desktop app's terminal button copies the equivalent ccr-app command. To confirm it worked, send a message in Claude Code and open the router's Logs page. Each request shows the model asked for, the provider and model that answered, the status code and the duration.
How to switch models
There are four places to control which model answers:
- In the profile. Set a default model, plus separate overrides for the Fable, Opus, Sonnet and Haiku tiers Claude Code uses. Models are written as
provider/model, such as the docs' exampleMoonshot/kimi-k3. Leave a field blank and Claude Code's own default applies. - Inside Claude Code. Run
/modelto see and switch between the models the router exposes. For how Claude Code's own model picker works, see Claude Sonnet vs Opus. - With routing rules. A rule can rewrite the model on matching requests to a different
provider/model. - For subagents. The routing docs describe a
<CCR-SUBAGENT-MODEL>provider/model</CCR-SUBAGENT-MODEL>tag for sending a subagent to a specific model.
You can also set what happens when a model fails. Retry mode retries the same model on 408, 409, 429 and 5xx errors. Fallback mode moves down an ordered list of backup models on any 4xx or 5xx. Waits start at one second and double, up to 30 seconds. The response headers x-ccr-fallback-attempts and x-ccr-fallback-model show whether a fallback happened.
What it's good for
- Trying other models in a workflow you already know. You keep Claude Code's commands, CLAUDE.md and habits while testing another provider.
- Watching cost per request. The logs estimate cost and token usage, which helps when you pay a provider per token. For what Claude Code itself costs on each plan, see how much Claude Code costs.
- Keeping work moving when a provider limits you. Fallback chains switch to a backup model instead of stopping.
- One place for keys. Provider keys live in the router, and each client gets its own key with limits.
The trade-offs
It's unofficial. Anthropic's gateway docs say it "doesn't endorse, maintain, or audit third-party gateway products". They also say Anthropic doesn't support routing Claude Code to non-Claude models through any gateway. If something breaks, the project's issue tracker is your support line.
Behaviour changes with other models. Claude Code is built and tested with Claude. Another model may follow instructions, edit files or call tools differently, so results you get with Claude won't automatically carry over. Anthropic also notes that each Claude Code release adds capabilities, and a gateway that doesn't forward them breaks the matching features.
Your code goes to whoever you route to. Every prompt, file Claude Code reads and command output in the conversation is sent to the provider that answers. That provider's data and retention terms apply, not Anthropic's. On client work, check the provider's terms and get the client's agreement before you send their code anywhere new.
Some Claude Code features switch off. Anthropic's docs say Remote Control is disabled while ANTHROPIC_BASE_URL points at a host other than Anthropic's, and voice dictation is unavailable while a gateway credential such as ANTHROPIC_AUTH_TOKEN is active.
Your subscription may not apply. When Claude Code sends a gateway credential, requests carry that credential instead of your claude.ai login, so your plan's usage limits don't cover them. You pay whoever issued the credential.
Anthropic's own way to use a gateway
Claude Code has a documented setting for routing through a proxy or gateway: the ANTHROPIC_BASE_URL environment variable. Pair it with a credential, either ANTHROPIC_AUTH_TOKEN (sent as a bearer token) or ANTHROPIC_API_KEY (sent as x-api-key):
export ANTHROPIC_BASE_URL=https://llm-gateway.example.com
export ANTHROPIC_AUTH_TOKEN=sk-gateway-keyTo make it stick, put the same values in the env block of ~/.claude/settings.json or a project's .claude/settings.local.json. Anthropic warns not to put the credential in a project's .claude/settings.json, because that file is committed and shared:
{
"env": {
"ANTHROPIC_BASE_URL": "https://llm-gateway.example.com",
"ANTHROPIC_AUTH_TOKEN": "sk-gateway-key"
}
}Run /status inside Claude Code to confirm. An Anthropic base URL line shows the gateway address. Other documented settings help with gateways too. ANTHROPIC_MODEL sets the model, and ANTHROPIC_DEFAULT_OPUS_MODEL, ANTHROPIC_DEFAULT_SONNET_MODEL and ANTHROPIC_DEFAULT_HAIKU_MODEL set what each alias resolves to. CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 adds the gateway's models to the /model picker.
This is the supported path when your organization runs a gateway in front of Claude models, for central keys, usage tracking or budgets. Claude Code can also connect to Claude models on Amazon Bedrock, Google Cloud's Agent Platform and Microsoft Foundry, as the connection guide shows.
| Claude Code Router | Official gateway setup | |
|---|---|---|
| Made by | Open-source community project | Anthropic documents the Claude Code side |
| Non-Claude models | Yes, that's the main use | Not supported by Anthropic |
| Setup | App or npm, configured in a UI |
Environment variables or settings env block |
| Best for | Experiments and personal cost control | Teams putting Claude behind a company gateway |
For locking down what Claude Code may do once it's running, see Claude Code permissions. If you're weighing Claude Code against Google's agent instead, read Claude Code vs Gemini CLI.
Learn to build with Claude Code
The Stride AI Coding course teaches Claude Code and Codex for building client tools, written for non-programmers, with weekly live calls to review your builds. Many of the free guides cover Claude Code setups, and the Claude Code community is where members compare theirs.
FAQ
Is Claude Code Router made by Anthropic?
No. It's an open-source community project on GitHub under the MIT license. Anthropic's docs say it doesn't endorse, maintain or audit third-party gateway products, and doesn't support routing Claude Code to non-Claude models.
Is Claude Code Router free?
The software is free and open source under the MIT license. You still pay each provider you route to, at that provider's rates, and the router's logs estimate that cost per request.
How do I switch models in Claude Code Router?
Set a default model and per-tier overrides in your Claude Code profile, using the provider/model format. Inside Claude Code, run /model to see and switch between the models the router exposes. Routing rules can also rewrite the model for matching requests.
Can I point Claude Code at another endpoint without the router?
Yes. Anthropic documents ANTHROPIC_BASE_URL plus ANTHROPIC_AUTH_TOKEN or ANTHROPIC_API_KEY for sending Claude Code through a gateway. It's meant for gateways in front of Claude models, and Anthropic doesn't support non-Claude models through it.
Is it safe to use Claude Code Router on client projects?
It can be, if the client agrees to their code going to the provider you route to and that provider's data terms are acceptable. Keep the router bound to your own machine, protect its config folder, and test results carefully, since other models behave differently in Claude Code.