Claude Code

Connect Anthropic's terminal coding agent to PleumRouter with a single key.

Claude Code is a coding agent that reads and edits your codebase and runs commands from the terminal. Point ANTHROPIC_BASE_URL at PleumRouter and Claude Code keeps speaking its native Anthropic Messages protocol (/v1/messages) while PleumRouter takes the request and sends it to the model. No local proxy is needed. For the desktop app, see Claude Desktop.

Quick start#

1
Install Claude Code
Skip this if it is already installed. The native install is recommended; the npm install needs Node.js.
install.sh
curl on macOS, Linux and WSL; the PowerShell command on Windows.
```
# macOS · Linux · WSL
curl -fsSL https://claude.ai/install.sh | bash

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

claude --version
```
Requires Node.js. Do not install with `sudo`.
```
npm install -g @anthropic-ai/claude-code
claude --version
```
Create an API key
In the dashboard's API keys page, create a key that starts with plm_ and copy it. Set daily, weekly or monthly budgets on it while you are there.
3
Connect to PleumRouter
Pick one of the three. You need three values: the address (ANTHROPIC_BASE_URL), the key (ANTHROPIC_AUTH_TOKEN) and an ANTHROPIC_API_KEY that must be empty. You do not have to choose models — Claude Code's default Claude models work as they are.
pleum launch
Applies to this run only and touches no config file.
```
npm i -g pleumrouter
pleum login            # sign in with the browser
pleum launch claude    # runs Claude Code pointed at PleumRouter
```
Add these to `~/.zshrc` or `~/.bashrc` and open a new terminal. If the key comes from another variable, define that variable first. `.env` files are not read.
```
export PLEUM_API_KEY="plm_xxxxxxxxxxxxxxxx"

# ANTHROPIC_BASE_URL is the origin WITHOUT /v1 — Claude Code appends /v1/messages itself.
export ANTHROPIC_BASE_URL="https://apirouter.pleum.ai"
export ANTHROPIC_AUTH_TOKEN="$PLEUM_API_KEY"
export ANTHROPIC_API_KEY=""   # must be explicitly empty

# then reload:  source ~/.zshrc   (or open a new terminal)
```
The `env` block of `~/.claude/settings.json` applies to every project. `pleum wire claude` merges the address, the key, `API_TIMEOUT_MS` and `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1` into this file, and removes `ANTHROPIC_API_KEY` instead of setting it to an empty value.
```
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://apirouter.pleum.ai",
    "ANTHROPIC_AUTH_TOKEN": "plm_xxxxxxxxxxxxxxxx",
    "ANTHROPIC_API_KEY": "",
    "API_TIMEOUT_MS": "3000000"
  }
}
```
4
Clear a saved Claude login
If you ever signed in to Claude Code with a Claude account, run /logout once and restart Claude Code. With both a saved login and a PleumRouter key present, Claude Code warns about an auth conflict and can fail with model-not-found errors. Skip this if you never signed in.
Claude Code
```
> /logout

# then quit and start claude again
```
5
Run it and check
/status should show Auth token: ANTHROPIC_AUTH_TOKEN and the PleumRouter address. If a Login method line shows a Claude account instead, the environment did not reach the session — open a new terminal and start again. Your requests show up right away in Usage.
Terminal
```
cd your-project
claude

> /status
Auth token: ANTHROPIC_AUTH_TOKEN
Anthropic base URL: https://apirouter.pleum.ai
```

Why use PleumRouter with Claude Code?#

Pay only for what you use from prepaid credits. Credits are deducted separately from the tool maker's subscription.
Set budgets and limits per key. Daily, weekly and monthly budgets, model allow-lists and team budgets help you manage what an agent spends.
One key, many models. Pick Claude, GPT, Gemini or open models; automatic retries and fallback cover provider outages; usage shows up in the dashboard.

How it works#

Claude Code sends Anthropic Messages requests (POST /v1/messages) to whatever ANTHROPIC_BASE_URL points at. PleumRouter accepts that format as is, translates streaming (SSE), tool calls, images, cache breakpoints and effort (/effort) into the chosen model provider's format, and returns the answer in Anthropic format. Authentication uses ANTHROPIC_AUTH_TOKEN (Authorization: Bearer). ANTHROPIC_API_KEY stays empty because Claude Code treats a value there as a direct Anthropic key (x-api-key), which can clash with a saved login. Usage is deducted from your PleumRouter credits, and thinking tokens are billed as part of output tokens.

Configuration reference#

Setting	Notes
ANTHROPIC_BASE_URLhttps://apirouter.pleum.ai	The origin without `/v1`. Claude Code appends `/v1/messages`.
ANTHROPIC_AUTH_TOKEN$PLEUM_API_KEY	Your PleumRouter API key, sent as `Authorization: Bearer`.
ANTHROPIC_API_KEY""	Must be empty so Claude Code does not fall back to direct Anthropic auth.
API_TIMEOUT_MS3000000	Request timeout (50 minutes) so long tasks are not cut off.
ANTHROPIC_DEFAULT_OPUS_MODELclaude-opus-5-5	Optional. Model for the Opus slot (hard reasoning).
ANTHROPIC_DEFAULT_SONNET_MODELclaude-sonnet-5	Optional. Model for the Sonnet slot (everyday coding).
ANTHROPIC_DEFAULT_HAIKU_MODELclaude-haiku-4-5	Optional. Model for the Haiku slot (light helper tasks such as titles).
ANTHROPIC_DEFAULT_FABLE_MODELclaude-fable-5-1	Optional. Fable slot (the hardest long-horizon work). Set it if Fable does not appear in `/model`.
CLAUDE_CODE_SUBAGENT_MODELclaude-sonnet-5	Optional. Model for sub-agents.
CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY1	Optional. Adds the whole catalog (`GET /v1/models`) to `/model`, which gets very long.

Choosing models#

Unless you set anything, Claude Code requests its default Claude model IDs and PleumRouter routes them to the same models in the catalog. To use another model or pin a version, put a model catalog ID in a slot variable. Add -latest (as in claude-sonnet-latest) to always get the newest release of a family, or @provider (as in claude-opus-5-5@anthropic) to send to that provider only — this turns off automatic fallback to other providers. For a 1M-context model, append [1m] to the ID; without it Claude Code assumes 200K and compacts early. PleumRouter strips the marker before routing.

~/.zshrc

# Optional — catalog IDs from router.pleum.ai/models
export ANTHROPIC_DEFAULT_OPUS_MODEL="claude-opus-5-5"
export ANTHROPIC_DEFAULT_SONNET_MODEL="claude-sonnet-5[1m]"   # [1m] = 1M context
export ANTHROPIC_DEFAULT_HAIKU_MODEL="claude-haiku-4-5"
export ANTHROPIC_DEFAULT_FABLE_MODEL="claude-fable-5-1"
export CLAUDE_CODE_SUBAGENT_MODEL="claude-sonnet-5"

# Newest release of a family, or one provider only:
# export ANTHROPIC_DEFAULT_SONNET_MODEL="claude-sonnet-latest"
# export ANTHROPIC_DEFAULT_OPUS_MODEL="claude-opus-5-5@anthropic"

These steps assume Claude models. GPT, Gemini and open models connect too, but tool-calling quality can vary by model.

Compatibility#

Feature	Status	Notes
Streaming (SSE)	Yes	`stream: true` is returned as Anthropic SSE events.
Tool calling	Yes	`tool_use` / `tool_result` are converted both ways.
Image input	Yes	Works when the chosen model accepts images.
Prompt caching	Yes	Claude Code's cache breakpoints reach Claude models as sent (the lifetime is always 5 minutes). Without them, automatic prompt caching applies.
Effort (`/effort`)	Yes	`output_config.effort` is translated to the chosen model's reasoning-effort setting.
1M-context marker (`[1m]`)	Yes	The `[1m]` suffix is stripped before routing.
Extended thinking	Partial	Thinking runs and is billed, but its content is not shown (`display: omitted`).
`/v1/messages/count_tokens`	Partial	Returns an estimate, not an exact tokenizer count.
Fast mode (`/fast`)	Partial	When claude-opus-5-5 is sent to the Anthropic provider (pinned with `claude-opus-5-5@anthropic`), a faster output tier can be requested, and those requests are billed at 2x ($8 in / $40 out per 1M tokens). Other models and providers, and requests the tier is not applied to, run at standard speed and standard price.
Remote Control, voice input	No	They need a Claude account login and are off when connected through a gateway (per Claude Code's docs).
Non-Claude models	Partial	They connect, but tool calling and reasoning display differ by model.

GitHub Actions#

The official Claude Code GitHub Action connects the same way. Store your plm_ key as the repository secret PLEUM_API_KEY and use it in both places below. The action will not start without the anthropic_api_key input, while the actual requests follow ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN in env to PleumRouter.

.github/workflows/claude.yml

- name: Run Claude Code
  uses: anthropics/claude-code-action@v1
  with:
    anthropic_api_key: ${{ secrets.PLEUM_API_KEY }}
  env:
    ANTHROPIC_BASE_URL: https://apirouter.pleum.ai
    ANTHROPIC_AUTH_TOKEN: ${{ secrets.PLEUM_API_KEY }}

Claude Agent SDK#

The Claude Agent SDK (Python and TypeScript) runs on Claude Code, so the same three environment variables connect it to PleumRouter.

Troubleshooting#

Symptom	Cause and fix
Claude Code shows a login screen	No gateway credential was found. Put `ANTHROPIC_AUTH_TOKEN` in your shell environment or the `env` block of `~/.claude/settings.json`. A project's `.claude/settings.json` only applies after the first-run wizard.
An auth-conflict warning appears	Both a saved Claude login and a PleumRouter key are present. Run `/logout` and restart Claude Code. An old Anthropic key left in your shell's `ANTHROPIC_API_KEY` is not cleared by `/logout` — override it with an empty value.
404 `/v1/v1/messages`	`ANTHROPIC_BASE_URL` ends in `/v1`. Use the bare origin `https://apirouter.pleum.ai`.
401 Unauthorized	Check that `/status` shows `Auth token: ANTHROPIC_AUTH_TOKEN`. If the key arrives empty, make sure the line that defines the key comes before the line that uses it in your shell profile.
model not found	Claude Code is using a new default model ID the catalog does not have yet, or a slot variable has a typo. Put a catalog ID in the slot variable.
The context always shows 200K	Append `[1m]` to the model ID (1M-context models only), for example `claude-sonnet-5[1m]`.
Long tasks get cut off	Raise `API_TIMEOUT_MS` to `3000000`. `pleum wire claude` sets it for you.
`/fast` does not speed things up	The faster output tier applies only when claude-opus-5-5 is sent to the Anthropic provider (pinned with `claude-opus-5-5@anthropic`). Other models and providers run at standard speed and standard price, so nothing extra is charged.
Thinking content is not shown	Thinking content is not displayed by design. Thinking still runs, so answer quality is unaffected.
`/model` lists hundreds of models	`CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1` is on. Remove it to see only the built-in entries.
Changes have no effect	Close every Claude Code session and terminal, then start a new terminal. If the same variable is in both your shell and `settings.json`, the `settings.json` value wins.

Cost & security tips#

Set a budget on the key. A coding agent calls the model many times per task and resends long context. Daily, weekly or monthly budgets on your API key make costs easier to predict.
Keep the key out of git. Make sure a key in your shell profile or config file never gets committed, and if you suspect a leak, revoke it in the dashboard and issue a new one.
Check where sensitive code goes. Prompts and code are sent to the provider of the model you pick. Use Data residency and PII masking to control that.