Claude Code on SoxAI

Claude Code is Anthropic's CLI coding agent. Pointed at SoxAI, it keeps working when the primary Anthropic API returns 429s — SoxAI routes the same request to Amazon Bedrock or a backup provider in milliseconds, with no retry logic in your code.

This guide covers the full setup: single-user, team, and troubleshooting. If you just want the two lines, jump to Quick setup.

Why use SoxAI with Claude Code?

Claude Code is powerful, but Anthropic's direct API has hard rate limits that hit during peak developer hours. When that happens, Claude Code stops working mid-session — exactly the moment you need it most.

SoxAI sits between Claude Code and Anthropic's backend, with three upgrades:

1. Automatic failover — when Anthropic direct throws 429 or 5xx, SoxAI reroutes to Amazon Bedrock's Claude or a pooled backup channel. Claude Code sees a normal response.
2. Per-developer API keys with budgets — every engineer on your team gets their own key. Revoke, rotate, or cap monthly spend independently.
3. Unified billing — one invoice across all upstream Claude sources, plus the other 200+ models you might want to try.

See SoxAI for Teams for the full feature list, or the vs-OpenRouter comparison if you're evaluating alternatives.

Quick setup

Claude Code reads two environment variables that SoxAI overrides:

export ANTHROPIC_BASE_URL="https://api.soxai.io"
export ANTHROPIC_API_KEY="sox-..."   # from console.soxai.io → API Keys

That's it. Claude Code still speaks the Anthropic Messages API; SoxAI accepts it as-is, routes to an upstream Claude provider, and streams the response back unchanged. Prompt caching, tool use, and extended thinking all pass through.

Verify it works:

claude "write me a python hello world"

You should get the usual Claude Code response. If you want to confirm it went through SoxAI, check the request log in your SoxAI console — you'll see the request and which upstream served it.

Per-shell setup (persistent)

Add the two exports to your shell profile so Claude Code always uses SoxAI:

bash / zsh — add to ~/.bashrc or ~/.zshrc:

export ANTHROPIC_BASE_URL="https://api.soxai.io"
export ANTHROPIC_API_KEY="sox-..."

fish — add to ~/.config/fish/config.fish:

set -x ANTHROPIC_BASE_URL "https://api.soxai.io"
set -x ANTHROPIC_API_KEY "sox-..."

Reload your shell (source ~/.zshrc or open a new terminal) and Claude Code will use SoxAI from here on.

Team setup

If you have a team on SoxAI, every developer should get their own API key rather than sharing one. This unlocks per-developer budgets, audit trails, and the ability to revoke one person's key without disrupting everyone.

1. Team admin: create a group in your team (e.g. "Engineering") and attach a quota policy. See Team Management for the full flow.
2. Each developer: generate their own API key at console.soxai.io/my-tokens. Name it after their machine (e.g. alice-laptop) so revoking is clear.
3. Each developer: set the two env vars above with their personal key.

From that point every Claude Code request is attributed to the individual developer. You'll see per-engineer spend in the team dashboard, and kill -9 on a runaway agent session becomes a one-click revoke instead of rotating a shared key.

Failover behavior

SoxAI's routing for Claude traffic follows the priority order configured on your account. A typical setup:

Priority 1 → Anthropic direct (lowest latency, newest models first)
Priority 2 → Amazon Bedrock (same Claude, different infra — model availability may lag direct)
Priority 3 → Backup third-party Claude channel

When priority 1 returns 429, 5xx, or times out, SoxAI automatically retries on priority 2, then 3. The client sees a single response — no retry logic needed in Claude Code. Which upstreams are available depends on the channels configured in your SoxAI account; self-host customers can plug in their own Bedrock credentials directly.

Two knobs you can tune (in your SoxAI admin panel):

• CHANNEL_RETRY_PER_LEVEL — how many times to retry one priority level before falling back (default 3).
• Session stickiness — keeps a conversation on the same upstream after the first hit, so mid-conversation you don't flip between Bedrock and direct. Send the id in any one of X-Session-ID, X-Session-Affinity, or session_id; the first one present wins, and any other request header whose name contains session also works as a fallback. Claude Code doesn't send one by default, but you can add it via a wrapper script if your team cares about conversation coherence.

Troubleshooting

401 Unauthorized

Your SoxAI API key is wrong or revoked. Generate a new one at console.soxai.io/tokens and update ANTHROPIC_API_KEY. SoxAI keys start with sox-, not sk-ant-.

429 Too Many Requests persisting

If every upstream Claude provider is rate-limited simultaneously (rare, happens during global Anthropic incidents), SoxAI exhausts its failover chain and returns 429 to Claude Code. When this happens:

1. Check SoxAI status for incident reports.
2. Consider adding more fallback channels to your account — open a SoxAI admin → Channels → enable additional Claude providers.
3. Teams on the self-host tier can add their own Bedrock credentials directly.

404 Not Found on a Claude model

Claude Code sometimes uses a very recent model alias (e.g. claude-opus-4-7). SoxAI supports aliases that map to the current Anthropic model name, but a just-released model may take 24h to propagate. Workaround: pin to an older model via ANTHROPIC_MODEL=claude-sonnet-4-6 until SoxAI adds the alias (usually same-day).

Slower responses than direct Anthropic

SoxAI targets under 5 ms P50 overhead for auth + routing + billing — invisible for normal Claude Code use. If you're seeing noticeably slower responses:

• Run curl -w '%{time_total}\n' -o /dev/null https://api.soxai.io/healthz to check network latency to SoxAI.
• If you're in a region far from SoxAI's primary deployment, the latency is network-bound, not gateway-bound. Self-hosting SoxAI in your region eliminates the hop entirely.

Claude Code ignores the env var

Some shells don't export to subprocesses by default. Make sure you use export (bash/zsh) or set -x (fish), and start Claude Code from the same shell. Verify with:

echo "$ANTHROPIC_BASE_URL $ANTHROPIC_API_KEY"

Both should print your values.

Response body logging

SoxAI retains full request and response bodies for 7 days for debugging, then auto-purges. Metadata (token count, cost, latency) is retained long-term. If you're running sensitive workloads, the self-host option keeps this data in your own database so you control retention end-to-end.

Rolling back to direct Anthropic

If you ever need to bypass SoxAI temporarily:

unset ANTHROPIC_BASE_URL
export ANTHROPIC_API_KEY="sk-ant-..."   # your direct Anthropic key

Claude Code defaults to https://api.anthropic.com when ANTHROPIC_BASE_URL is unset. The switch takes effect on the next claude invocation.

Next steps

• Team Management — set up per-developer keys, groups, and quota policies
• Migration from OpenAI / OpenRouter — if you're moving from another gateway
• SoxAI for Teams — feature overview for team leads