Use Claude Code with the Gateway¶

Claude Code is Anthropic's agentic coding tool that works directly in your terminal. By routing it through the Gateway, you get access to Claude models hosted in your region — with your data staying in your chosen geography and your usage tracked through your Gateway workspace.

Why use Claude Code with the Gateway?¶

Data residency. Claude Code requests are processed through your regional endpoint. Pick Switzerland, Germany, the US, Australia, or the UK.

Team budget controls. Set spending limits per team, user, and key from my.amazee.io. No surprise invoices.

Usage visibility. All Claude Code activity shows up in your usage dashboard — per key, per user, per team.

Quick start¶

Step 1 — Install Claude Code¶

macOS / Linux / WSLWindows PowerShell

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

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

Step 2 — Get your endpoint and key¶

Log in at my.amazee.io, go to your workspace, and copy:

Your API endpoint: https://llm.[your-region].amazee.ai
Your API key

Step 3 — Connect Claude Code to the Gateway¶

Add these environment variables to your shell profile (~/.zshrc, ~/.bashrc, or ~/.config/fish/config.fish):

export AMAZEEAI_API_KEY="your-api-key-here"
export ANTHROPIC_BASE_URL="https://llm.[your-region].amazee.ai"
export ANTHROPIC_AUTH_TOKEN="$AMAZEEAI_API_KEY"
export ANTHROPIC_API_KEY=""  # must be explicitly empty

# Required: map Claude Code's model roles to Gateway model IDs
export ANTHROPIC_DEFAULT_OPUS_MODEL="claude-4-5-opus"
export ANTHROPIC_DEFAULT_SONNET_MODEL="claude-4-5-sonnet"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="claude-4-5-haiku"
export CLAUDE_CODE_SUBAGENT_MODEL="claude-4-5-sonnet"

Then reload your shell:

source ~/.zshrc   # or ~/.bashrc

Set the model lines

Claude Code asks for its own default model name, which the Gateway doesn't have. Without the four model lines, your first prompt fails with Failed to authenticate. API Error: 403 team not allowed to access model. Use IDs exactly as /v1/models returns them (claude-4-5-sonnet, not claude-sonnet-4-5).

ANTHROPIC_API_KEY must be empty — not unset

Claude Code falls back to direct Anthropic authentication if this variable is unset. Set it to an empty string "" to prevent that.

If you were previously logged in to Anthropic

Run /logout inside a Claude Code session to clear cached credentials before the new config takes effect.

To check your key can see those models:

curl -s https://llm.[your-region].amazee.ai/v1/models \
  -H "Authorization: Bearer $AMAZEEAI_API_KEY" | grep -o '"claude-[^"]*"'

Every model you set above should be in the list.

Step 4 — Start a session¶

cd /path/to/your/project
claude

Step 5 — Verify¶

Run /status inside Claude Code:

> /status
Auth token: ANTHROPIC_AUTH_TOKEN
Anthropic base URL: https://llm.[your-region].amazee.ai

You can also check the My usage card on the AI keys page to see requests appearing in real time.

How it works¶

The Gateway speaks the same protocol as the Anthropic API. When you set ANTHROPIC_BASE_URL, Claude Code routes all requests to your regional endpoint instead of Anthropic's servers. No local proxy needed.

Changing models¶

Claude Code uses a different model for each type of task. The variables you set in Step 3 pin each role:

Variable	Used for
`ANTHROPIC_DEFAULT_OPUS_MODEL`	Complex reasoning tasks
`ANTHROPIC_DEFAULT_SONNET_MODEL`	General coding
`ANTHROPIC_DEFAULT_HAIKU_MODEL`	Quick completions
`CLAUDE_CODE_SUBAGENT_MODEL`	Sub-agents spawned during a session

To use a different model, change the value to another ID from Available Models or your /v1/models list.

GitHub Actions¶

To use the Gateway in the Claude Code GitHub Action:

- name: Run Claude Code
  uses: anthropics/claude-code-action@v1
  with:
    anthropic_api_key: ${{ secrets.AMAZEEAI_API_KEY }}
  env:
    ANTHROPIC_BASE_URL: https://llm.[your-region].amazee.ai
    ANTHROPIC_DEFAULT_OPUS_MODEL: claude-4-5-opus
    ANTHROPIC_DEFAULT_SONNET_MODEL: claude-4-5-sonnet
    ANTHROPIC_DEFAULT_HAIKU_MODEL: claude-4-5-haiku

Store your key as a GitHub secret named AMAZEEAI_API_KEY.

Troubleshooting¶

"Failed to authenticate. API Error: 403 team not allowed to access model": Despite the wording, your key is usually fine. Claude Code asked for a model the Gateway doesn't have or your key can't use. Check the name after "Tried to access", then set the ANTHROPIC_DEFAULT_*_MODEL variables to IDs from /v1/models.
Auth errors / "invalid API key": Make sure ANTHROPIC_API_KEY is set to "" (empty string), not unset. Run echo $ANTHROPIC_API_KEY — it should print nothing. If it prints a key value, something in your shell config is still setting it.
Requests going to Anthropic instead of the Gateway: Run /logout in Claude Code, then verify ANTHROPIC_BASE_URL is set correctly with echo $ANTHROPIC_BASE_URL.
Model not found: Check Available Models. Use the exact model ID shown there. Model availability depends on your region and plan.
Context length errors: Break the task into smaller chunks or start a fresh session (/clear).