ccr-cloudOPEN SOURCE / MIT

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.

Today the route is a server setting: it applies to every new task, and changing it needs a restart. Choosing the route for each task, and switching an existing task, are planned, not implemented.

#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:

SHELL
npm install -g @musistudio/claude-code-router
ccr start

ccr 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:

SHELL
ssh -N -L 3458:127.0.0.1:3458 USER@SERVER

By 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:

  1. 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.
  2. Providers: add your provider with its base URL, API key, protocol and the model you want, for example an open-source model.
  3. Global Routing: add a rule so Claude Code's model names go to that model. Without it, CCR rejects requests for claude-… models with Model "claude-…" is not configured for target provider. Add a Condition rule where request.body.model starts with claude, and set request.body.model to PROVIDER/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.
  4. 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:

SHELL
cp ~/.claude/settings.json ~/.claude/settings.json.ccr-managed
cp ~/.claude/settings.json.ccr-original ~/.claude/settings.json

If 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:

SHELL
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 claude behaves anywhere else.

#3. Send new tasks through CCR

Add these lines to server.env in your data directory (~/.local/share/ccr-cloud/server.env by default):

SHELL
CCR_GATEWAY_URL=http://127.0.0.1:3456
CCR_GATEWAY_KEY=YOUR_CCR_CLIENT_KEY

Then restart the service. Tasks you start from now on use CCR. Run a scratch task with Reply OK and check CCR's Logs to confirm.

#4. Switch back to your Claude account

Remove or comment out both lines in server.env:

SHELL
# CCR_GATEWAY_URL=http://127.0.0.1:3456
# CCR_GATEWAY_KEY=YOUR_CCR_CLIENT_KEY

Then restart the service. New tasks use your Claude account again.

#What happens to existing tasks

A task keeps the route it started with, even after Stop and Resume. Restarting the service doesn't move running or stopped tasks to the new route.

To carry work from a task that hit a usage limit onto the other route:

  1. Commit the task's work on its branch. Open a terminal on the server:

    SHELL
    cd ~/.local/share/ccr-cloud/host/SESSION_ID/workspace
git add -A && git commit -m "Work in progress"
  2. Switch the route (step 3 or 4) and start a new task in the same repository.
  3. Ask the new task 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. The new task starts a new conversation, so describe what's left to do.

#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

Edit this page on GitHub ↗