Claude Code

Claude Code talks to Actualyze over the Anthropic Messages API. You set three environment variables: the base URL, your Actualyze API key, and a flag that loads the models your key can call into the /model picker. Nothing else about Claude Code changes.

#Before you start

• An Actualyze API key with the inference scope and read-write permission. Workspace Admins, Members and FinOps Managers who belong to a team can create one: in the Actualyze app, select API Keys under ADMIN in the sidebar (every role that can hold keys sees this page, not only admins), then select Create API Key. Keep the default Read & Write permission. The key's budget is the one your Claude Code usage draws down.
• At least one model in your workspace that your key can call.

#Install

If Claude Code isn't installed yet, use Anthropic's native installer. On macOS, Linux or WSL:

curl -fsSL https://claude.ai/install.sh | bash

In Windows PowerShell:

irm https://claude.ai/install.ps1 | iex

Anthropic's setup guide covers Homebrew, WinGet, npm and the Linux package managers.

#Connect to Actualyze

Add these lines to your shell profile, then open a new terminal and run claude:

export ANTHROPIC_BASE_URL="https://app.actualyze.ai/anthropic"
export ANTHROPIC_AUTH_TOKEN="<your-actualyze-api-key>"
export CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1

• ANTHROPIC_BASE_URL is the Anthropic-compatible endpoint. Keep the trailing /anthropic and add nothing after it: Claude Code appends /v1/messages itself.
• ANTHROPIC_AUTH_TOKEN sends your Actualyze API key in the Authorization: Bearer header. Use it rather than ANTHROPIC_API_KEY, which Claude Code makes you approve once before it uses the key.
• CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 makes Claude Code ask Actualyze for the models your key can call each time it starts and add them to the /model picker. Without it, the picker shows only Claude Code's built-in models.

To set this once for every terminal, or on Windows, put the same values in the env block of ~/.claude/settings.json instead (%USERPROFILE%\.claude\settings.json on Windows). Values there take precedence over shell exports. Don't put your key in a project's .claude/settings.json, which is committed with the repository.

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://app.actualyze.ai/anthropic",
    "ANTHROPIC_AUTH_TOKEN": "<your-actualyze-api-key>",
    "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY": "1"
  }
}

The VS Code extension checks your credentials before it reads that file, so in VS Code set the same three variables in claudeCode.environmentVariables in your user settings.

To check the connection, run /status in Claude Code. The Status tab should show an Anthropic base URL line with the Actualyze URL and an Auth token line naming ANTHROPIC_AUTH_TOKEN.

#Choose a model

With discovery on, you don't list models anywhere. Open /model and pick a model marked From gateway. A discovered model that Claude Code already has a row for, such as the model its built-in Opus row points at, is folded into that row instead of being listed twice. The list is computed for your key and refreshes each time Claude Code starts, so a model your team gains access to later shows up on its own. Picking a model with Enter saves it as your default for later sessions.

Until you pick one, Claude Code uses its own default Anthropic model. If your workspace doesn't serve that model, the first request fails with a model-not-found error. To start on a specific model instead, set a catalog model ID or a Virtual Model slug. ANTHROPIC_MODEL takes precedence over a model you saved with /model:

export ANTHROPIC_MODEL="<model-id>"

The picker only keeps discovered models whose ID contains claude or anthropic (case-insensitive). Claude Code applies that filter, not Actualyze. A Virtual Model called prod-claude-router shows up; one called general-chat doesn't, but it still works when you name it in ANTHROPIC_MODEL, and you can add it to the picker with ANTHROPIC_CUSTOM_MODEL_OPTION="general-chat". If you create a Virtual Model for Claude Code users, put claude in its slug.

#Troubleshooting

• 402: a spend limit stopped the request before any model ran, so nothing was charged. The message says which limit: usually the key's budget, or the key's own monthly limit.
• 401: the key was rejected. It may be mistyped, revoked or expired, lack the inference scope, or belong to someone who is no longer on the key's team.
• 403: the request was refused. If the message says read-write permission is required, the key is read-only; create a read-write key. Otherwise your team can't use the model you asked for; check its access in the Model Catalog or pick another.
• 402 saying Budget required: the key's budget was deleted, archived or retired, or you no longer have access to it. Create a new key bound to a budget you can use.
• Every request fails right after setup: check the base URL. It must end in /anthropic.
• Claude Code asks you to log in, or /status has no Anthropic base URL line: the variables didn't reach the session. Open a new terminal after editing your profile, or use the settings file.
• A startup warning names two credential sources: a saved claude.ai login or ANTHROPIC_API_KEY is set as well as your Actualyze key. Run /logout to clear the saved login, and unset ANTHROPIC_API_KEY.
• Model not found on the first request: Claude Code asked for its built-in default. Pick a model marked From gateway in /model or set ANTHROPIC_MODEL.
• No models marked From gateway in /model: check that CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 reached the session, then restart Claude Code. To see why discovery failed, start claude --debug and look for [gatewayDiscovery] lines in the debug log under ~/.claude/debug/. Discovery gives up after 3 seconds; raise CLAUDE_CODE_GATEWAY_MODEL_DISCOVERY_TIMEOUT_MS on a slow connection.
• A model is missing from /model: its ID doesn't contain claude or anthropic. Call it through ANTHROPIC_MODEL.
• 503 saying the model can't serve Anthropic (Claude Code) requests: that model has no route that speaks the Anthropic protocol. Pick a model that does.
• 400 saying an Actualyze guardrail changed the request before dispatch: a guardrail changed an earlier turn, so the conversation history no longer lines up. Start a new conversation.
• 422 naming a tool: a guardrail's tool policy blocks that tool, so the request stops instead of running it.

#Reference

Requests you cancel mid-stream still draw down the usage they consumed. Actualyze labels this traffic as Claude Code in the Client column of the Observability Activity tab, which Workspace Admins, FinOps Managers and Auditors can see.

For Claude Code's own settings and gateway behavior, see Anthropic's guide to connecting Claude Code to an LLM gateway.