Switch models with CCR
Keep using your Claude account by default, and send tasks through Claude Code Router (CCR) when you want another model, for example an open-source model while you're at a Claude usage limit. Switch back when the limit resets.
Tasks still run Claude Code on your server. Only where its model requests go changes: to your Claude account directly, or to the CCR gateway, which forwards them to the provider and model you chose in CCR.
You choose the route for each task with Model access when you start it, and you can move a stopped task to the other route when you resume it.
#Before you begin
- ccr-cloud running in host mode, with a task that works on your Claude account. See Getting started.
- CCR installed on the same server, with at least one provider and model set up. See CCR's quick start.
#1. Set up the CCR gateway
On the server:
npm install -g @musistudio/claude-code-router
ccr startccr start runs CCR in the background. Its management UI is at http://127.0.0.1:3458 and its model gateway at http://127.0.0.1:3456. Reach the UI from your laptop through an SSH tunnel:
ssh -N -L 3458:127.0.0.1:3458 USER@SERVERBy default, CCR takes over Claude Code and Codex on the whole server. When you first save a provider, CCR applies its Agent Profiles: it rewrites ~/.claude/settings.json and ~/.codex/config.toml so that every claude and codex, including your own terminal and ccr-cloud's Claude-account tasks, goes through CCR. Do the first step below before adding a provider.
In the CCR UI:
- Agent Profiles: open the Claude Code profile and set Effect scope to Only opened from CCR, or remove the profile. Do the same for Codex if it's installed. CCR then keeps its settings in its own folder and leaves yours alone.
- Providers: add your provider with its base URL, API key, protocol and the model you want, for example an open-source model.
- Global Routing: add a rule so Claude Code's model names go to that model. Without it, CCR rejects requests for
claude-…models withModel "claude-…" is not configured for target provider. Add a Condition rule whererequest.body.modelstarts withclaude, and setrequest.body.modeltoPROVIDER/MODEL(your provider's name and model). Claude Code asks for more than one Claude model (a main model and a smaller one for quick steps), so match the prefix rather than one model name. - API Keys: create a client key for ccr-cloud.
If CCR already changed your settings, ~/.claude/settings.json has an apiKeyHelper line and an ANTHROPIC_BASE_URL entry under env that you didn't add. CCR saves the original next to it as settings.json.ccr-original. Turning the profile off later doesn't reliably restore it, so restore the original yourself:
cp ~/.claude/settings.json ~/.claude/settings.json.ccr-managed
cp ~/.claude/settings.json.ccr-original ~/.claude/settings.jsonIf there's a settings.json.ccr-original-missing file instead, you had no settings file before; remove CCR's apiKeyHelper line and the env entries it added. Then check that claude -p "Reply OK" uses your Claude account again.
#2. Check the route
Send one request through CCR with the client key, as the ccr-cloud service user:
ANTHROPIC_BASE_URL=http://127.0.0.1:3456 ANTHROPIC_AUTH_TOKEN=YOUR_CCR_CLIENT_KEY claude -p "Reply OK"A reply means the gateway, key and model work. CCR's Logs page shows which provider and model answered. This doesn't change how `c## 3. Make CCR available to ccr-cloud
Add these lines to server.env in your data directory (~/.local/share/ccr-cloud/server.env by default):
CCR_GATEWAY_URL=http://127.0.0.1:3456
CCR_GATEWAY_KEY=YOUR_CCR_CLIENT_KEYThen restart the service. This makes CCR available; it doesn't change any task by itself.
#4. Choose the route for a task
When you start a task, choose Model access:
| Choice | Where model requests go |
|---|---|
| Claude account | Your server user's Claude login or API configuration. The default. |
| CCR gateway | CCR, which forwards them to the model your routing rule picks. |
The Model access picker appears only after a gateway is configured, and your browser remembers your last choice. The task shows its route, for example Model access: CCR gateway. Run a scratch task with Reply OK on the CCR route and check CCR's Logs to confirm.
Tasks started from Discord or through the API without modelRoute use the Claude account. See HTTP API.
#Switch a task to the other route
A task keeps its route until you change it. To move a task, for example one that hit a Claude usage limit:
- Select Stop session.
- Next to Resume session, set Resume on to the other route.
- Select Resume session.
The task continues the same conversation and files on the new route, and its activity shows Model access changed. Switch back the same way when your limit resets. Through the API, send {"modelRoute": "ccr"} or {"modelRoute": "account"} to POST /api/sessions/:id/start.
#If the other model can't continue the conversation
A model may not be able to pick up a conversation another model started, for example one that used extended thinking. If the resumed task fails, start a fresh task instead:
Commit the old task's work on its branch, in a terminal on the server:
SHELLcd ~/.local/share/ccr-cloud/host/SESSION_ID/workspace git add -A && git commit -m "Work in progress"- Start a new task in the same repository with the other Model access choice.
- Ask it to continue from the old branch, for example: "Merge branch
ccr/SESSION_ID, then finish the remaining work: …".
Task branches share one repository, so the new task can see the old one's commits.
#Things to know
- Different models behave differently. Tools, long contexts and extended thinking may work less well on other models. Check CCR's Logs if a task stalls or errors.
- Keep CCR on loopback. ccr-cloud and CCR run on the same server, so the gateway never needs to be reachable from outside. Your provider keys stay in CCR; tasks receive only the client key.
- The client key is visible to tasks. Claude Code needs it to reach the gateway, so the agent's shell can read it. Give the key limits in CCR if that matters.
- For isolated containers that always use CCR, see Docker and CCR sessions.
#Next steps
- Run and control tasks
- Configuration:
CCR_GATEWAY_URLandCCR_GATEWAY_KEY