Install Claude Code Router v3 in WSL

Run Claude Code Router in WSL when Claude Code, Node.js, and your working repository also live there. This keeps the agent, router, shell, and project in one environment. Installing CCR only on Windows does not create a Linux ccr command inside WSL.

CCR v3 no longer uses the old manual config.json workflow for normal operation. The current CLI opens a management interface, stores live settings in SQLite, and connects Claude Code through Agent Profiles.

Install Node.js inside WSL#

Open your WSL distribution and check whether Node.js 22 or newer is available:

node --version

If Node is missing or too old, install a current release with your preferred Linux Node version manager. For example, with nvm already installed:

nvm install 22
nvm use 22
node --version

Install Claude Code and CCR#

Install both packages inside WSL:

npm install -g @anthropic-ai/claude-code
npm install -g @musistudio/claude-code-router@latest
claude --version
ccr --help

Start the management service and open its interface:

ccr ui

WSL normally forwards the local URL to your Windows browser. If the browser does not open, copy the management URL printed in the terminal. For a terminal-only session, use:

ccr ui --no-open

Know where CCR stores its data#

The Linux CLI stores data under:

~/.claude-code-router

Current configuration is held in config.sqlite. Do not edit that file. A legacy config.json is used only when CCR needs to migrate an older installation and no SQLite database exists.

This differs from a native Windows installation, which uses %APPDATA%\claude-code-router. If you install CCR in both environments, you have two separate configurations.

Add a provider#

In the management interface, open Providers and select Add Provider. Choose a preset if CCR lists the service. Otherwise, use the custom endpoint option and enter:

• The provider’s API base URL
• Its supported protocol
• Your provider API key
• One or more exact model IDs

Run the protocol and model connection checks before saving. These checks can send billable requests, so test only the models you plan to use.

Create a CCR key and start the gateway#

Open API Keys and create a client key for requests sent to CCR. This is not your provider key.

Then open Server and start the model gateway. The npm CLI uses separate local ports:

If port 3458 is occupied, CCR may choose another management port and print it in the terminal. Do not point Claude Code at the management address.

Check that the gateway is running:

curl -i http://127.0.0.1:3456/health

Connect Claude Code#

Open Agent Profiles, choose Claude Code, and create a profile. Select the main model and the settings file that CCR should manage. Apply and enable the profile.

For the first test, limit the configuration to Claude Code sessions opened from CCR. This avoids changing the default behavior of Claude Code sessions you start normally.

Launch the enabled profile from the interface or by name:

ccr "Claude - WSL"

Replace Claude - WSL with your profile name. Send a small request, then open Logs in CCR. Confirm the provider, requested model, resolved model, and response status.

Keep projects in the Linux file system#

WSL can work on files under /mnt/c, but coding agents perform many small reads, searches, and writes. Those operations are generally faster in the Linux file system.

A simple layout is:

~/projects/my-app

Open that directory from WSL before launching the profile:

cd ~/projects/my-app
ccr "Claude - WSL"

Use /mnt/c when a Windows-only application needs direct access to the same files. Avoid moving CCR’s own database there.

Common WSL problems#

• ccr: command not found: confirm that CCR was installed inside the current WSL distribution. Open a new shell after the npm installation.
• Node reports a version below 22: switch the active version in the Linux shell, then reinstall or rerun CCR.
• The browser does not open: copy the URL printed by ccr ui, or use ccr ui --no-open and open the address manually.
• The UI works but model requests fail: start the gateway under Server and confirm that the agent uses port 3456.
• Windows CCR has providers but WSL CCR does not: the two installations use separate data directories. Configure the WSL instance independently.
• A profile name is not found: make sure it is enabled, save it again, or launch it by its profile ID.
• An old background process keeps stale options: run ccr stop, then start it again with ccr ui.

Once the first request works, add routing or fallback rules one at a time. If a later rule breaks the request path, the logs will show which model CCR selected and where the failure occurred.