Guide · Open source

How to use claude-code-router: install, set up and route models

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

Claude Code Router (CCR) is an open-source local model gateway for coding agents such as Claude Code, Codex and Kimi CLI. It gives these agents one local address and forwards their requests to the model providers you configure. This guide shows you how to install it, add a provider, start the gateway and connect an agent, so you can manage models from one place.

Claude Code Routermusistudio/claude-code-router · ★ 38k · MIT Install options & downloads

Quick start

1Install CCR. Download the desktop app for your system, or install the CLI with npm install -g @musistudio/claude-code-router on Node.js 22 or newer.
2Open the management UI. Launch the desktop app, or run ccr ui to open the browser-based interface at http://127.0.0.1:3458.
3Add a provider. Go to Providers, choose Add Provider, pick a preset or custom endpoint, enter your API key, select protocol and models, then save.
4Start the server. Open Server and click Start. The gateway listens on http://127.0.0.1:3456 by default.
5Apply an agent profile. Open Agent Config, select your agent and a model, and apply the profile.
6Check requests in Logs. Open Logs to confirm the provider, model, status, tokens, latency and any errors.

What Claude Code Router does

CCR runs on your own machine. Agents send their requests to one local endpoint, and CCR forwards them to the providers you set up. You manage providers, models, routing rules and request logs in one place instead of editing each agent's settings separately.

Connects Claude Code, Codex, Grok CLI, Kimi CLI, Kilo Code, OpenCode, Pi, ZCode, WorkBuddy and compatible API clients.
Supports OpenAI Chat / Responses, Anthropic Messages, Gemini, OpenRouter, DeepSeek, SiliconFlow, Moonshot, Kimi Code, Mistral, Z.AI, Bailian and custom compatible providers.
Adds retries, credential pools, key rotation and ordered fallback models.

Install Claude Code Router with the desktop app

The desktop app is the recommended route. Download the build for macOS, Windows or Linux from the project's releases page, then launch the app.

Windows, Linux, macOS (Apple Silicon) and macOS (Intel) builds are listed in the README.
Once launched, you use the app's Providers, Server, Agent Config and Logs screens.

Install the CLI with Node.js 22 or newer

If you prefer the command line, the npm CLI requires Node.js 22 or newer. It starts the same gateway and a browser-based management UI without Electron.

Check that your Node.js version is 22 or newer before installing.

npm install -g @musistudio/claude-code-router
ccr ui

Add a provider and start the gateway

In the app, open Providers and choose Add Provider. Pick a built-in preset or a custom endpoint, enter your API key, select the protocol and models, then save.

Next, open Server and click Start. The local model gateway listens on http://127.0.0.1:3456 by default. With the CLI, the management UI is at http://127.0.0.1:3458 and the gateway stays at http://127.0.0.1:3456.

Provider setup: built-in preset or custom endpoint, API key, protocol and models.
Default gateway address: http://127.0.0.1:3456.

Connect your agent and confirm requests in Logs

Open Agent Config, choose your agent (for example Claude Code or Codex), select a model and apply the profile. Then start using the agent as normal.

Open Logs to check the resolved provider, model, status, tokens, latency and errors for each request.

Agent Config: choose the agent, select a model, apply the profile.
Logs: confirm provider, model, status, tokens, latency and errors.

Set up routing rules and fallbacks

Your agent is connected once a profile is applied. To add conditions, retries, request rewrites or fallback models, open Routing. Fallback is useful when a request fails and you want another model to take over.

Conditions, retries, request rewrites and ordered fallback models are configured under Routing.

What people use it for

Using Claude Code and Codex with the same set of providers, managed in one place.
Switching models or providers without reconfiguring each agent.
Setting up ordered fallback models so a failed request moves to another model.
Reviewing request logs, token usage and latency across several agents.

Frequently asked questions

Is Claude Code Router free?

CCR is released under the MIT licence, which is an open-source licence. The source does not list prices for the providers you connect, so check each provider's own pricing.

What do I need to install Claude Code Router?

For the CLI route you need Node.js 22 or newer. The desktop app is available for macOS, Windows and Linux from the project's releases page.

How do I install claude-code-router with npm?

Run npm install -g @musistudio/claude-code-router, then run ccr ui to open the management interface in your browser.

Where does the local gateway run?

By default the model gateway listens on http://127.0.0.1:3456, and the CLI management UI is at http://127.0.0.1:3458.

Which agents does CCR work with?

The README lists Claude Code, Claude Design, Codex, Grok CLI, Kimi CLI, Kilo Code, OpenCode, Pi, ZCode, WorkBuddy and compatible API clients.

Is CCR worth it if I only use one agent?

Probably not. The gateway adds setup, and the benefit is mostly for people who use several agents or want to switch providers without reconfiguring each one.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Claude Code Router suits developers who use several coding agents and want one place to manage providers, fallbacks and request logs. It is less useful if you use one agent with one provider, or if you do not want a local server running on your machine. The README excerpt does not cover security or compliance, so check those yourself before using it in a regulated setting.

Install options & downloads