<!-- Source: https://ccr-cloud.uubright.com/docs/switch-models/ -->
# Switch models with CCR

Keep using your Claude account by default, and send tasks through
[Claude Code Router](https://github.com/musistudio/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](https://ccr-cloud.uubright.com/docs/getting-started/).
- CCR installed **on the same server**, with at least one provider and model set up.
  See CCR's [quick start](https://github.com/musistudio/claude-code-router#cli).

## 1. Set up the CCR gateway

On the server:

```sh
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:

```sh
ssh -N -L 3458:127.0.0.1:3458 USER@SERVER
```

> [!WARNING]
> **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.
1. **Providers:** add your provider with its base URL, API key, protocol and the
   model you want, for example an open-source model.
1. **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.
1. **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:

```sh
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:

```sh
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):

```sh
CCR_GATEWAY_URL=http://127.0.0.1:3456
CCR_GATEWAY_KEY=YOUR_CCR_CLIENT_KEY
```

Then [restart the service](https://ccr-cloud.uubright.com/docs/operations/#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](https://ccr-cloud.uubright.com/docs/api/#start-a-task).

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

1. Select **Stop session**.
2. Next to **Resume session**, set **Resume on** to the other route.
3. 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`](https://ccr-cloud.uubright.com/docs/api/#sessions).

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

1. Commit the old task's work on its branch, in a terminal on the server:

   ```sh
   cd ~/.local/share/ccr-cloud/host/SESSION_ID/workspace
   git add -A && git commit -m "Work in progress"
   ```

2. Start a new task in the same repository with the other **Model access** choice.
3. 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](https://ccr-cloud.uubright.com/docs/docker/).

## Next steps

- [Run and control tasks](https://ccr-cloud.uubright.com/docs/tasks/)
- [Configuration](https://ccr-cloud.uubright.com/docs/configuration/#ccr-gateway-and-docker-mode): `CCR_GATEWAY_URL`
  and `CCR_GATEWAY_KEY`
