Claude Code Router (CCR): Install and Route Any Model

Claude Code Router (CCR) is musistudio's local control plane. It sits on your machine, accepts Claude Code (and other agents) on a local gateway, and decides which upstream provider and model should handle each request.

This page is the CCR install: current UI, SQLite config, provider setup, verification, Ollama, Docker, and VS Code. It is not the "point Claude Code at RouterPlex" page. If you only need one Anthropic-compatible upstream, skip CCR and use the Claude Code with RouterPlex docs.

What Claude Code Router does #

CCR listens on a local model-gateway endpoint and decides which upstream provider and model should handle a request. It can centralize provider credentials, model selection, conditional routes, retries, fallbacks, client keys, logs, and cost estimates.

That is useful when you want routing policy on your machine. It is unnecessary when one upstream already accepts Claude Code's native Anthropic Messages request and you do not need local routing rules.

Install the current Claude Code Router #

The npm CLI requires Node.js 22 or newer:

node --version
npm install -g @musistudio/claude-code-router
ccr --help

Start the background service and open the browser UI:

ccr ui

For an SSH or headless session, use ccr ui --no-open and open the printed authenticated URL through a secure tunnel.

The management UI prefers http://127.0.0.1:3458. The model gateway prefers http://127.0.0.1:3456. CCR can choose a following port when one is occupied, so trust the URL it prints instead of assuming a port.

Desktop installers for macOS, Windows, and Linux are available from GitHub Releases. The desktop and npm distributions share the same local data directory.

Do not edit a legacy config.json #

Current CCR stores live configuration in config.sqlite:

• macOS and Linux: ~/.claude-code-router/config.sqlite
• Windows: %APPDATA%\claude-code-router\config.sqlite

A legacy config.json is read only as a one-time migration source when no SQLite configuration exists. Use the UI to add providers and routes. For backups, stop CCR or use its export function instead of copying a live SQLite file.

Add RouterPlex as an upstream provider #

Create a dedicated RouterPlex API key before opening CCR. Give it a hard $5 or $10 budget for the first test. A local router can retry, fall back, or run several agent profiles, so the upstream key should enforce the real financial limit.

In CCR:

1. Open Providers and choose Add Provider.
2. Select Other / custom API endpoint.
3. Name the provider RouterPlex.
4. Choose the OpenAI-compatible chat protocol.
5. Use https://api.routerplex.com/v1 as the API base URL.
6. Paste the dedicated RouterPlex key.
7. Add model IDs from the live RouterPlex model catalog.
8. Run CCR's protocol probe or connectivity test, then save.

Use exact model IDs. A display name such as "Claude Opus" is not interchangeable with an API ID such as claude-opus-4-8.

Create a CCR client key and Claude Code profile #

CCR separates upstream provider credentials from local gateway client keys. The RouterPlex key pays for upstream model calls. A CCR client key authorizes Claude Code to call the local gateway. Do not paste one where the other belongs.

Open API Keys and create a client key. Then open Agent Config, add a Claude Code profile, select the RouterPlex-backed model and desired scope, and apply the configuration. Keep the gateway running under Server.

An enabled profile can be launched from the CLI:

ccr "Claude - RouterPlex" cli

Use the exact profile name or ID shown by CCR. The generated profile keeps Claude Code pointed at the local gateway while CCR resolves the upstream provider and model.

Verify the resolved route #

Start with an empty directory and a read-only prompt. Before giving the agent a real repository, confirm both sides of the route:

1. CCR Logs show the expected request model, resolved provider, resolved model, status, tokens, and latency.
2. The RouterPlex dashboard shows the same upstream model and a plausible cost under the dedicated key.
3. The RouterPlex key budget decreases by the billed amount.
4. Stopping CCR makes the local route fail, proving Claude Code is not silently calling another endpoint.

Only then increase the budget or enable fallback models.

Skip CCR when one gateway is enough #

Do not install CCR only because an old tutorial says every non-Claude model needs a local translation proxy. Claude Code can talk to an Anthropic-compatible gateway directly. RouterPlex exposes that route for its chat models, including non-Anthropic models translated at the gateway.

That setup — ANTHROPIC_BASE_URL, a budgeted key, and ~/.claude/settings.json — lives in Claude Code with RouterPlex. Use this CCR page when you actually want local routing policy: several upstreams, conditional routes, fallbacks, or Ollama.

Routing Claude Code Router to specific backends #

CCR treats every upstream the same way: a provider profile with a protocol, a base URL, and a set of model IDs. Once you know that pattern, the common variations are small changes to those three fields.

Claude Code Router with Ollama

Point a provider profile at the local Ollama OpenAI-compatible endpoint and add the model tags you have pulled. Because the models run locally, there is no per-token cost and no upstream budget to cap. The tradeoff is capability: local models are generally weaker at long agentic tool loops than hosted frontier models, so mixed setups are common. Use CCR's routing rules to send heavy reasoning to a hosted provider and cheap or private work to Ollama.

Claude Code Router with Kimi

Kimi K3 is a common CCR target because its 1M-token context suits repository-scale work. Add kimi-k3 as a model ID on an OpenAI-compatible provider profile. See Kimi K3 API pricing and setup for current rates before pointing an agent loop at it.

Claude Code Router in Docker

The project publishes container images so the gateway can run as a service rather than a desktop app. The important detail is network exposure: CCR is a local control plane holding upstream provider credentials, so bind it to localhost or a private network. Do not publish the gateway port to a public interface. Check the repository release notes for the current image name and tag, which change more often than the configuration model.

Claude Code Router with VS Code

CCR intercepts at the API boundary, not the editor, so a VS Code Claude Code session follows the same route as the terminal one as long as the extension inherits the environment CCR sets. If the extension still reaches Anthropic directly, the usual cause is that it was launched from a shell without the router's environment. Restart the editor from a shell where the CCR profile is active, then confirm with the log check below.

When you do not need CCR at all

If you use one upstream and no conditional routing, CCR is a moving part with no payoff. Use the direct Claude Code docs instead. Choose CCR when you genuinely want local routing policy across several providers.

Common Claude Code Router problems #

ccr code profile was not found or is disabled

CCR is launching a named Agent Config profile that does not exist or is turned off. Open Agent Config, copy the exact profile name or ID, enable it, and rerun ccr "That Exact Name" cli. A generic name such as code only works if you created a profile with that name.

ccr is not found

Confirm Node.js 22 or newer, run npm prefix -g, and make sure npm's global binary directory is on PATH.

The UI opens but model calls fail

Add a provider and model, create a CCR client key, and confirm the gateway is running under Server. Run ccr serve in the foreground when you need startup logs.

Old settings keep returning

Run ccr stop before changing listener options. Do not expect edits to a legacy config.json to update the live SQLite configuration.

RouterPlex rejects the model

Check the provider's base URL, the exact model ID, and which credential is being used. CCR client keys and RouterPlex upstream keys serve different boundaries.

The local gateway is exposed remotely

Keep CCR on 127.0.0.1 unless remote access is intentional. A remote deployment needs a fixed strong management token, TLS, firewall or private-network controls, and protected storage because CCR holds upstream credentials.

Cost controls for coding agents #

• Route cheap work to a cheap model — the cheapest models ranking orders the catalog by what a real agent turn costs, not by input price alone.
• Give every coding tool or repository its own RouterPlex key.
• Set a hard upstream budget before enabling retries or fallbacks.
• Start with one model and one profile.
• Review CCR's estimate against the upstream billed amount.
• Rotate any key that appears in shell history, logs, screenshots, or a committed file.

Start with a $5 RouterPlex balance, cap the dedicated key, and verify one small CCR-routed request before trusting an autonomous coding session.