Setting up Claude Code with a custom base URL (ANTHROPIC_BASE_URL guide for 2026)

Anthropic shipped Claude Code with first-class support for routing through an external gateway via the ANTHROPIC_BASE_URL environment variable. This is the documented, supported way to use a proxy — for cost-cutting, observability, compliance, or to run through a corporate egress point.

This is the complete 2026 setup, every flag you'll actually use, and a short list of the gotchas that send people in circles.

The two-variable minimum

If your gateway speaks the Anthropic Messages format, two env vars are all you need:

export ANTHROPIC_BASE_URL=https://api.anvat.app/v1
export ANTHROPIC_AUTH_TOKEN=sk-anvat-your-key-here
claude

That's it. Claude Code uses ANTHROPIC_BASE_URL as the root for every API call and sends ANTHROPIC_AUTH_TOKEN as a bearer token. The wire format, streaming protocol, tool-use semantics, and prompt caching all stay identical — your gateway just needs to accept the same shape of request on the other side.

Verify it's working

One command:

claude "say the word 'gateway' and stop"

If the call succeeds and your gateway logs show a request to /v1/messages, you're good. If you want zero ambiguity, watch the live network in another terminal:

# macOS
sudo tcpdump -A -i any host api.anvat.app
 
# Linux
sudo tcpdump -A -i any host api.anvat.app

You should see TCP traffic to the gateway, none to api.anthropic.com.

Persisting the config

Two patterns work, pick the one that matches your team's discipline.

Per-project (recommended)

Drop a .env in the project root and source it:

# .env
ANTHROPIC_BASE_URL=https://api.anvat.app/v1
ANTHROPIC_AUTH_TOKEN=sk-anvat-...

# shell-rc or per-session
set -a; source .env; set +a
claude

Per-project keeps the gateway choice colocated with the code that depends on it — important if different repos route through different providers.

Per-shell

For a single-gateway setup, just append to your shell rc file:

# ~/.zshrc or ~/.bashrc
export ANTHROPIC_BASE_URL=https://api.anvat.app/v1
export ANTHROPIC_AUTH_TOKEN=sk-anvat-...

Restart the terminal (or source the rc) and claude works from anywhere.

Optional flags worth knowing

CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1

When set to 1, Claude Code calls your gateway's /v1/models endpoint at startup and adds the returned models to the /model picker — labeled "From gateway". Useful when your gateway exposes models the built-in catalog doesn't list. Off by default to avoid leaking every model your shared gateway key can access to every user.

Requires Claude Code v2.1.129+.

ENABLE_TOOL_SEARCH=true

Anthropic disables MCP tool search by default for non-first-party hosts. If your gateway forwards tool_reference blocks correctly (most modern ones do), set this to true to re-enable on-demand tool loading instead of eager-loading every MCP tool upfront.

ANTHROPIC_CUSTOM_HEADERS

Add custom HTTP headers on every request. Format is RFC 822 (one Header: Value per line). Useful for gateway-specific routing hints or trace propagation:

export ANTHROPIC_CUSTOM_HEADERS="X-Tenant-Id: acme
X-Cost-Center: engineering"

CLAUDE_CODE_PROPAGATE_TRACEPARENT=1

Propagates W3C trace context (traceparent header) to your gateway and to the TRACEPARENT env var inside any Bash, PowerShell, or hook subprocess Claude Code spawns. Set this if your gateway feeds traces into Datadog, Honeycomb, or any OTel collector.

What if your gateway isn't Anthropic-format?

Two cases worth distinguishing:

OpenAI-format only. Claude Code does not currently support OpenAI-format gateways. You need an Anthropic-format endpoint (/v1/messages). If your gateway only speaks OpenAI's /v1/chat/completions schema, look for a translation layer — most modern gateways (Anvat, LiteLLM, Portkey) expose both formats on different paths.

Bedrock / Vertex. Don't use ANTHROPIC_BASE_URL — Anthropic ships first-class support for both via dedicated flags. See the official Bedrock docs↗ and Vertex docs↗.

Standard HTTP proxy vs LLM gateway

These solve different problems and can be combined:

• HTTP_PROXY / HTTPS_PROXY — pure network-layer proxy. Every HTTP request gets tunneled through. Use this for corporate egress rules, packet inspection, or compliance setups. Doesn't change the destination — still hits api.anthropic.com underneath.
• ANTHROPIC_BASE_URL — destination override. Talks to your gateway directly, which may or may not forward to Anthropic. Use this for cost-cutting, multi-provider routing, or running through your own infra.

You can set both. The HTTP proxy handles the network egress; the base URL handles where the request actually lands.

Common gotchas

1. Trailing slashes. https://api.example.com and https://api.example.com/ behave the same. https://api.example.com/v1/ (with trailing slash) sometimes double-slashes the final URL — most gateways tolerate it, but if you see 404s, strip the trailing slash.

2. Wrong path prefix. Most gateways expect the base URL to point at /v1 (e.g. https://api.anvat.app/v1). Some pass-through endpoints expect just the host root. Check your gateway's docs.

3. Certificate errors. Corporate networks with TLS-inspecting proxies will error with UNABLE_TO_GET_ISSUER_CERT_LOCALLY. Fix:

export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca-bundle.pem

4. Streaming hangs. Some load balancers buffer responses. Gateways must forward Server-Sent Events without buffering. If completions hang for several seconds before printing, suspect a buffering issue at your gateway — not Claude Code.

5. MCP tool errors with custom gateway. If MCP tools that worked with direct Anthropic suddenly fail through your gateway, set ENABLE_TOOL_SEARCH=false to force eager-loading. Some gateways don't fully support deferred tool loading.

Worked example: pointing at Anvat

End to end, on a fresh machine:

# 1. Install Claude Code (skip if already done)
npm install -g @anthropic-ai/claude-code
 
# 2. Sign up + create an API key
open https://anvat.app/signup
 
# 3. Export the gateway env
export ANTHROPIC_BASE_URL=https://api.anvat.app/v1
export ANTHROPIC_AUTH_TOKEN=sk-anvat-your-key
 
# 4. Smoke test
claude "in one sentence, what does ripgrep do?"

You should see a normal Claude response, billed at the gateway's rate (30% off Anthropic list for Anvat). Your existing Claude Code config (~/.claude/), MCP servers, and skills all keep working unchanged — only the network hop changes.

When to not use a custom base URL

Three legitimate reasons to stay direct:

• Enterprise SLA requirements that specifically name api.anthropic.com as the contracted endpoint.
• Beta features that ship to first-party only (rare, but Anthropic occasionally gates new tool types or beta models).
• Audit requirements where a third party in the request path is disallowed.

For the other 95% of teams, a discounted gateway is a free 30–50% margin on the same workload.