<!-- Source: https://console.uubright.com/docs/bring-your-own-model/ -->
# Bring your own model

Tasks run Claude Code on your server. If you don't have a Claude subscription,
Claude Code still needs model access. Connect one of these:

| Choice | You need | Billing |
|---|---|---|
| **Claude Code Router (CCR)** | CCR running on this server with at least one provider and a routing rule. A client key only if your CCR uses them. See [Claude Code Router](#claude-code-router) below. | Whatever providers you set up in CCR |
| **Anthropic API key** | A key from [console.anthropic.com](https://console.anthropic.com) → API keys | Your Anthropic account, per token |
| **AWS Bedrock** | An AWS region that has Claude, with model access turned on in the Bedrock console, plus an AWS profile or access keys | Your AWS account |

You can connect a model in the app or with setup. Either way, the server checks it
live before saving it, and a running service uses it for the next task. You don't
need to restart.

If Claude Code on the server already works for your user (`claude -p "Reply OK"`
replies), you can skip this page. Tasks use that setup unless you connect another
model here.

## Claude Code Router

CCR is the quickest way to bring your own models: one gateway on this server, the
providers and models you set up in CCR, and your provider keys staying in CCR.

1. Set up CCR on the server: install it, start it with `ccr start`, add a provider
   and a routing rule. [Switch models with CCR](https://console.uubright.com/docs/switch-models/#1-set-up-the-ccr-gateway)
   has the steps, including the Agent Profiles setting to change first.
2. Open **⋯ → Settings → Model access**. **Claude Code Router** is the first
   choice. If the app's setup check finds CCR running on this server, it shows
   **Found Claude Code Router running at http://127.0.0.1:3456**.
3. Select **Use Claude Code Router**. If your CCR uses client keys (its **API
   Keys** page, or `APIKEY` in its `config.json`), the check says so; paste the key
   into **Client key** and select **Check and save**. A CCR on this computer
   without keys needs nothing more.

The check lists what CCR serves: its models and, with CCR's `config.json`, its
routes (default, background, thinking and planning, long context, web search),
each with its `provider,model`. It's free when the gateway lists its models.
Otherwise it sends one 1-token request through your routing.

With CCR connected:

- New tasks go through the gateway. Tasks that don't name a route, such as those
  started from Discord or the API, use it too. The **Model access** picker on a new
  task still offers the server's own Claude setup.
- A task's **Model** picker lists CCR's routes first, by what they're for (for
  example **deepseek,deepseek-reasoner · CCR route: thinking and planning**), then
  the other models it serves. Picking one sends that task's requests straight to
  that `provider,model`, past CCR's routing; **Default** follows CCR's default
  route. Switching between two models of the same provider happens between turns.
  Switching to another provider hands off to a new task; see
  [Switch models with CCR](https://console.uubright.com/docs/switch-models/#choose-a-model-on-the-ccr-route).
- If CCR isn't running, a new task or **Resume session** stops right away with
  **Claude Code Router at http://127.0.0.1:3456 isn't running**. Start it with
  `ccr start` and try again. If CCR stops during a task, Claude Code retries; the
  task's activity shows **Can't reach the model server, retrying**, then the same
  note. Once CCR is back, the turn continues or you can send your message again.
- Tasks get `ANTHROPIC_BASE_URL` and `ANTHROPIC_AUTH_TOKEN`. For a CCR without
  keys, the token is the placeholder `ccr-no-key`, so Claude Code doesn't fall
  back to the server user's own Claude login and send it to the gateway.

If `server.env` sets `CCR_GATEWAY_URL` and `CCR_GATEWAY_KEY`, those take precedence.
The app then shows the CCR gateway as managed by `server.env` and won't save another
one. Only a gateway on this computer is checked before a task starts; a remote one
is your own service.

## Connect in the app

When the server has no model access, **Needs you** opens with a **Connect your
model** card. You can also open **⋯ → Settings → Model access** at any time.

1. Choose **Claude Code Router**, **Anthropic API key** or **AWS Bedrock**.
2. Fill in its fields:
   - **Claude Code Router:** see [Claude Code Router](#claude-code-router) above.
   - **Anthropic API key:** paste the key.
   - **AWS Bedrock:** enter the **Region**, for example `us-east-1`. Under
     **Credentials**, choose **AWS profile on this server** and enter the profile
     name from `~/.aws/config` (default: `default`), or choose **Access keys** and
     enter the access key ID, the secret access key and, for temporary keys, the
     session token.
3. Select **Check and save**.

You then see either **✓ Connected**, with what the provider reported, or
**✗ Not saved**, with the reason and what to fix. If the check fails only because
this server can't reach the provider from here, select **Save without checking**.
Your first task then shows whether the model access works.

Then start a task with **＋ New**, for example a scratch task that says
`Reply OK`.

Only the owner token can open this page. Paired phones and relay devices see an
explanation instead, the same as for Messaging settings.

## Connect with setup

The same choices, checks and storage work from the server's shell. Secrets are read
from standard input, never from arguments, so they stay out of your shell history
and the process list. At a terminal, setup asks for them without echoing what you
type.

```sh
# Anthropic API key
npm run setup -- --anthropic-key-stdin < anthropic-key.txt

# AWS Bedrock with a profile
npm run setup -- --bedrock-region us-east-1 --aws-profile default

# AWS Bedrock with access keys: the secret on the first line, an optional session token on the second
npm run setup -- --bedrock-region us-east-1 --aws-access-key-id AKIA… --aws-secret-stdin < aws-secret.txt

# Claude Code Router (leave --ccr-key-stdin out for a local CCR without keys)
npm run setup -- --ccr-url http://127.0.0.1:3456 --ccr-key-stdin < ccr-client-key.txt
```

You can combine these options with `--start`. Add `--no-check` to save without the
live check. If the check fails, setup prints the reason, saves nothing and exits
with status 1. `npm run setup` and `npm run doctor` show which model new tasks use,
and warn when there's none.

## What each check costs

| Choice | Check | Cost |
|---|---|---|
| Anthropic API key | Lists your models (`GET /v1/models`) | Free, no tokens |
| AWS Bedrock | Lists Bedrock's Claude models in the region (`ListFoundationModels`), signed with your credentials | Free, no tokens |
| Claude Code Router | Lists the gateway's models (`GET /v1/models`) | Free, no tokens |
| Claude Code Router without a model list | One request of at most 1 output token through your routing rules | A fraction of a cent on your provider |

A Bedrock check proves that your credentials and region work. It doesn't prove that
your account may run the models (`bedrock:InvokeModel`). If your credentials can
run models but can't list them, the check saves with a warning and your first task
shows the result.

## Where your credentials go

- They're saved in `model-access.json` in the data folder
  (`~/.local/share/ccr-cloud` by default), readable only by the server user.
  The app and the API never send a saved secret back, and never write it to a
  task's events or to the server's logs.
- A task receives only Claude Code's own variables for the model you chose:

  | Choice | Variables a task gets |
  |---|---|
  | Anthropic API key | `ANTHROPIC_API_KEY` |
  | AWS Bedrock with a profile | `CLAUDE_CODE_USE_BEDROCK=1`, `AWS_REGION`, `AWS_PROFILE` |
  | AWS Bedrock with keys | `CLAUDE_CODE_USE_BEDROCK=1`, `AWS_REGION`, `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` and, if set, `AWS_SESSION_TOKEN` |
  | Claude Code Router | `ANTHROPIC_BASE_URL` and `ANTHROPIC_AUTH_TOKEN` (the client key). Your provider keys stay in CCR. |
  | Zhipu GLM | `ANTHROPIC_BASE_URL`, `ANTHROPIC_AUTH_TOKEN` (the Z.ai coding-plan key) and `ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL`, `ANTHROPIC_DEFAULT_HAIKU_MODEL` set to the model you saved. GLM does not replace the choice above. A task uses it only when you pick GLM, or when you choose **Switch to GLM** after a usage limit. |

  In host mode a task runs as your server user, so its agent can read these
  variables, as it can read the rest of that user's files. See the
  [Security model](https://console.uubright.com/docs/security/).
- With nothing connected here, or after **Forget**, tasks get the server's own
  values again, such as an `ANTHROPIC_API_KEY` in `server.env`.
- Codex tasks get none of them. A workspace with its own Claude login (see
  [Workspaces](https://console.uubright.com/docs/workspaces/)) keeps using that login.
- Containers ([Docker mode](https://console.uubright.com/docs/docker/)) only accept Claude Code Router, from
  `server.env`. Provider keys never enter a sandbox.

## Zhipu GLM

GLM is optional and off until you save a key. On **Connect your model**, under **Zhipu GLM**, paste the API key from your GLM coding plan (Z.ai → Personal Coding Plan or Team Coding Plan → Plan Overview), then **Check and save**.

- **Base URL.** The default is `https://api.z.ai/api/anthropic`, the Anthropic-compatible endpoint in [Z.ai’s Claude Code guide](https://docs.z.ai/devpack/tool/claude). For the China endpoint, set `https://open.bigmodel.cn/api/anthropic`.
- **Model.** The default is `glm-5.3-flash[1m]`, the flash model id that guide maps onto Claude Code’s opus, sonnet and haiku slots. Change it if your plan exposes a different id, such as `glm-5.3[1m]`.
- The key is saved on this server with your other model credentials. It is not shown again, not written to the task log, and not sent through the relay.
- Start a task and choose **GLM** under **Model access**. The task says **Running on GLM**. Work from that task still waits for the usual independent review before you merge it.
- Saving a GLM key does not move your other tasks off Claude or Codex. Automatic failover after a usage limit is not built yet. A workspace can store `limitPolicy.fallback: "glm"` for a later release; nothing switches on it today. **Switch to GLM** on a usage-limit card starts one new task on GLM and leaves the policy as it was.

## Change or remove it

Open **⋯ → Settings → Model access**:

- **Check again** runs the live check on what's saved.
- Choose another option and select **Check and save** to switch. The new choice
  applies to new tasks and to stopped tasks when they resume.
- **Forget** removes that choice's settings and secrets from the server. Tasks then
  use the server user's own Claude Code setup.

Fields for saved secrets stay empty and say **Saved · leave blank to keep it**.
Leave them blank to keep the saved value, for example when you only change the
Bedrock region.

## If it doesn't work

| What you see | What to do |
|---|---|
| A task fails with **Not logged in · Please run /login** | Nothing is connected. Connect a model above. |
| **Anthropic rejected this key (401)** | Copy the key again. Keys are shown only once in the Anthropic console, so you may need a new one. |
| **AWS rejected these credentials** | Check the access key ID and secret. For an SSO profile, run `aws sso login` on the server first. |
| **lists no Claude models** | Choose a region that offers Claude, such as `us-east-1` or `us-west-2`. |
| **Nothing is listening at http://127.0.0.1:3456**, or **Claude Code Router … isn't running** | Start CCR with `ccr start`. |
| **This gateway needs a client key** | Your CCR uses client keys. Paste one from its **API Keys** page, or the `APIKEY` in its `config.json`. |
| **The gateway answered 4xx** with a message about `claude-…` models | Add CCR's Global Routing rule from [Switch models with CCR](https://console.uubright.com/docs/switch-models/#1-set-up-the-ccr-gateway). |
| **This server can't look up api.anthropic.com** | The server has no internet access or DNS. Use **Save without checking** only if tasks can reach the provider another way, such as a proxy. |
