Agents & Editors
Claude Code
Connecting Claude Code to a Claude Proxy with the Anthropic, Amazon Bedrock or Google Vertex format.
Claude Code is Anthropic's coding agent for the terminal. It connects to Multi-Router through a Claude Proxy, using a few settings that point it at Multi-Router and name the proxy. Claude Code then works as usual: it sends its requests in the Anthropic, Amazon Bedrock or Google Vertex format, and the Claude Proxy serves them from the route and region the organization chose, with the organization's limits applied.
Installing Claude Code
Claude Code is installed with Anthropic's installer. On macOS, Linux and WSL, run the command below; Windows and other options are covered in Anthropic's Claude Code documentation.
Choosing a setup
The setup follows from two settings of the Claude Proxy: its route, which is the provider that serves the requests, and its credential source, which decides whose login pays. Each combination uses one of four sets of settings:
| Setup | Route | Credential source | Claude Code sends |
|---|---|---|---|
| Anthropic, developer login | Anthropic | Developer | Anthropic format, with the developer's own Claude login |
| Anthropic, organization key | Anthropic | Organization | Anthropic format |
| Bedrock | Any Amazon Bedrock route | Organization | Amazon Bedrock format |
| Vertex | Any Google Vertex route | Organization | Google Vertex format |
The Claude Proxy's page in the dashboard shows the settings for its own setup under Claude Code setup, filled in with the proxy's id, with a Copy button. Replace the API key placeholder with the developer's Multi-Router API key.
Where the settings go
Claude Code reads its Multi-Router settings as environment variables, set either in the shell or under "env" in a settings file. The user settings file is the most common choice, because it applies to every Claude Code session for that user:
| Place | Location | Applies to |
|---|---|---|
| User settings file | ~/.claude/settings.json on macOS, Linux and WSL | Every session for that user. |
| User settings file on Windows | %USERPROFILE%\.claude\settings.json | Every session for that user. |
| Project settings file | .claude/settings.json in a repository, shared with the team | Sessions started in that project. |
| Local project settings file | .claude/settings.local.json in a repository, kept out of version control | Sessions started in that project, for one person. |
| Shell environment | export lines in ~/.zshrc or ~/.bashrc | Sessions started from that shell. |
| Managed settings on macOS | /Library/Application Support/ClaudeCode/managed-settings.json, deployed by IT | Every user on the machine, and takes precedence over user settings. |
| Managed settings on Linux | /etc/claude-code/managed-settings.json, deployed by IT | Every user on the machine, and takes precedence over user settings. |
| Managed settings on Windows | C:\Program Files\ClaudeCode\managed-settings.json, deployed by IT | Every user on the machine, and takes precedence over user settings. |
When the same setting appears in several places, managed settings take precedence, then local project settings, then project settings, then user settings. A settings file usually holds other settings too, such as permissions or apiKeyHelper; add the Multi-Router values to its "env" block and keep the rest of the file as it is. The settings for the Anthropic route with the organization key look like this:
ANTHROPIC_CUSTOM_HEADERS holds one header per line. In a settings file, lines are separated with \n; in a shell, the value is written across two lines inside quotes.
Anthropic route with the developer's login
With the Developer credential source, each developer signs in to Claude Code with their own Claude account or Anthropic API key, as they would without Multi-Router. Multi-Router passes that login to Anthropic as sent, without storing it, and usage is billed to the developer's own Claude plan or Anthropic account. The Multi-Router API key travels in its own header, X-MR-Api-Token, next to the router id:
Leave ANTHROPIC_AUTH_TOKEN unset in this setup, so that Claude Code sends the developer's own login. The Developer credential source is available on the Anthropic route.
Anthropic route with the organization key
With the Organization credential source, the Claude Proxy sends each request to Anthropic with the organization's Anthropic key, and usage is billed to the organization's Anthropic account. The Multi-Router API key is the developer's only credential:
CLAUDE_CODE_SKIP_FAST_MODE_ORG_CHECK lets Claude Code use fast mode when it signs in with a Multi-Router API key. Managed settings that require a Claude login, forceLoginMethod and forceLoginOrgUUID, suit the Developer setup only; leave them out of managed settings for the organization key, Bedrock and Vertex setups, which sign in with the Multi-Router API key through ANTHROPIC_AUTH_TOKEN or apiKeyHelper.
Amazon Bedrock routes
On a Bedrock route, Claude Code sends requests in the Amazon Bedrock format to the Claude Proxy's Bedrock endpoint, and the Claude Proxy signs them with the organization's Bedrock key. The Multi-Router API key is the developer's only credential:
Claude Code can name a model by its Bedrock model id, inference profile id or ARN. The Claude Proxy resolves the name and builds the Bedrock request for the route's own region, so a region inside an ARN is replaced by the route's region. See AWS Bedrock.
Google Vertex routes
On a Vertex route, Claude Code sends requests in the Google Vertex format to the Claude Proxy's Vertex endpoint, and the Claude Proxy authenticates with the organization's Vertex key. The Multi-Router API key is the developer's only credential:
Claude Code needs ANTHROPIC_VERTEX_PROJECT_ID and CLOUD_ML_REGION to build its request paths. The Claude Proxy replaces both with the Vertex key's project and the route's region, so the values shown in the Claude Code setup on the proxy's page are the ones to use. See Google Vertex.
Keys from a script with apiKeyHelper
apiKeyHelper is a Claude Code setting that names a script whose output is the API key. Claude Code runs the script when it starts and again when the key needs refreshing, so the Multi-Router API key can come from a secrets manager or vault and be rotated there, with no key written in the settings file. The helper replaces ANTHROPIC_AUTH_TOKEN in the organization key, Bedrock and Vertex setups, and the other settings stay the same:
The script prints the Multi-Router API key and nothing else. For example, reading it from HashiCorp Vault:
The helper works as follows with Multi-Router:
| Behavior | Detail |
|---|---|
| Header | Claude Code sends the helper's key in the x-api-key header, which a Claude Proxy accepts on the Anthropic, Bedrock and Vertex routes. |
| Refresh | Claude Code runs the helper again after 5 minutes, or after a request is refused with 401. CLAUDE_CODE_API_KEY_HELPER_TTL_MS sets a different refresh interval in milliseconds. |
| Rotation | A new key returned by the helper is used from the next refresh, so rotating the key in the vault and then disabling the old key in Multi-Router changes keys with no restart. |
| Setups | The organization key, Bedrock and Vertex setups. The Developer setup carries the Multi-Router key in X-MR-Api-Token and keeps the developer's own Claude login, so it uses no helper. |
| Other key settings | Set only one of apiKeyHelper, ANTHROPIC_AUTH_TOKEN and ANTHROPIC_API_KEY. |
| Model discovery | Model discovery is reliable with ANTHROPIC_AUTH_TOKEN. Claude Code has a known issue reading the model list with helper keys, so with a helper, models are chosen with /model. |
In managed settings, apiKeyHelper lets IT deploy one settings file to every machine, with each person's key coming from their own vault entry.
Models
Claude Code chooses its models as it does with Anthropic directly, including when a developer switches models with /model. The Claude Proxy accepts any spelling of a model's name, such as the Anthropic model id, the Multi-Router catalog slug anthropic/claude-opus-5, a Bedrock inference profile id or an ARN, and serves it on the route's provider. Each response carries the x-mr-upstream-wire-id header with the model id sent to the provider.
A developer chooses the model in three ways:
| When | How | Example |
|---|---|---|
| At launch | The --model option | claude --model claude-opus-5 |
| During a session | /model with a model name, keeping the conversation | /model claude-sonnet-4-5 |
| Current model | /model with no name | /model |
Claude Code uses three model tiers, Opus, Sonnet and Haiku, and picks a tier for each task, such as Haiku for quick background work. Each tier can be pinned to a specific model, for example to keep a team on one version while a newer one is evaluated. Pinning is optional; without it, Claude Code uses its own default for each tier:
| Setting | Tier |
|---|---|
ANTHROPIC_DEFAULT_OPUS_MODEL | Opus |
ANTHROPIC_DEFAULT_SONNET_MODEL | Sonnet |
ANTHROPIC_DEFAULT_HAIKU_MODEL | Haiku, used for quick background tasks |
A pinned model must be one the Claude Proxy serves.
A Claude Proxy serves the models of its route that are switched on, and answers a request for any other model with a message naming the model and the reason, such as a model switched off on the router or outside the route's model group. See Troubleshooting.
Model discovery
Model discovery lets Claude Code's model picker list exactly the models the Claude Proxy serves. It is turned on with one more setting, and works on the Anthropic route with an API key that has the models:read scope:
Claude Code then reads the list from GET /v1/models on the proxy, which returns one entry for each model the route serves and the router has switched on. After the route, its model group or its switched-off models change, run /model to refresh the list. Setting CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC also turns discovery off.
Token counting
Claude Code counts tokens before some requests to manage its context window. A Claude Proxy answers token counts on the Anthropic route and Vertex routes whenever it would serve the matching request, at no cost and outside Traffic and budgets. On Bedrock routes, Claude Code estimates token counts itself.
Sessions in Traffic
Claude Code sends a session id with each request, and Traffic records it, so the requests of one Claude Code session can be viewed together. A tool or script can set its own session id with the x-mr-session-id header, which takes precedence. See Observability.
Features that need a direct Anthropic connection
A few Claude Code features work only when Claude Code connects to Anthropic directly. Remote Control is available when no base URL points to a gateway, and voice dictation is available when ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN and apiKeyHelper are unset. Every other feature, including subagents, tools, plan mode, prompt caching and fast mode, works through a Claude Proxy.
Switching an existing installation
An installation that was used with Anthropic directly can carry settings that take precedence over the Multi-Router ones. Before the first session through Multi-Router:
- Remove the
modelfield from every settings file, so that model selection follows the Claude Proxy and/model. - For the organization key, Bedrock and Vertex setups, run
/logoutin Claude Code, so that a stored Claude login gives way to the Multi-Router API key. - Restart Claude Code, which reads its settings when it starts.
The Developer setup keeps the developer's Claude login, so it needs only the first and last steps.
Checking the setup
A working setup is confirmed from inside Claude Code:
- Run
/status. It shows the base URL, which ishttps://api.multi-router.ai, or the Bedrock or Vertex address on those routes, and how Claude Code is signed in. - Run
/modelwith no name. It shows the model the session uses, which matches the model in the settings or the one chosen with/model. - Ask Claude Code to say hello. The request then appears in Traffic under the Claude Proxy.
When Claude Code shows its login screen instead, the settings did not reach the Claude Code process; check that they are in a settings file or in the shell Claude Code was started from. When /model shows a different model than expected, look for a model field in a project or local settings file, or choose the model again with /model.