Claude Code

Claude Code talks the Anthropic Messages API to whatever ANTHROPIC_BASE_URL points at. Point it at Mesh and every request runs through the same gateway as the rest of your traffic — spend caps, per-key rate limits, usage logging and retry/fallback all apply, with no change to how you use the tool.

Because /v1/messages is not restricted to Anthropic models, this also lets Claude Code run against any model in the Mesh catalog.

Configuration

Add this to ~/.claude/settings.json (or a project’s .claude/settings.json):

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.meshapi.ai",
    "ANTHROPIC_AUTH_TOKEN": "rsk_YOUR_KEY",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "anthropic/claude-opus-4.8",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "anthropic/claude-sonnet-4.6",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "anthropic/claude-haiku-4.5"
  }
}

All three model variables matter. Claude Code picks a model per task, and any variable you leave unset falls through to an Anthropic-native id that Mesh does not serve.

Model ids use dots, not hyphens. Mesh serves anthropic/claude-sonnet-4.6. Anthropic’s native form — claude-sonnet-4-6 — returns 404 Model ... is not supported or is invalid. Copy the ids exactly as written above, or from Available Models.

The three things that catch people out

1. If you are signed in to Claude Code, `ANTHROPIC_AUTH_TOKEN` is ignored

This is the most common failure, and the error does not hint at the cause:

Failed to authenticate. API Error: 401 Invalid or missing API key.

A signed-in Claude Code prefers its stored credential over the environment variable, so it sends that credential to Mesh — which correctly rejects it as not being a Mesh key. Use a separate config directory so the CLI has no stored login to prefer:

CLAUDE_CONFIG_DIR=~/.claude-mesh claude

Wrap it in a shell alias if you switch between the two regularly:

alias claude-mesh='CLAUDE_CONFIG_DIR=~/.claude-mesh claude'

Signing out of Claude Code also works, but costs you the direct-Anthropic setup. A second config directory keeps both.

2. `ANTHROPIC_DEFAULT_OPUS_MODEL` is not optional

Claude Code’s default model is Opus. Set only Sonnet and Haiku and the first request fails:

There's an issue with the selected model (claude-opus-4-8[1m]).
It may not exist or you may not have access to it.

Note the [1m] suffix Claude Code appends for its long-context variant — another reason to map the variable explicitly rather than relying on a default.

3. Haiku carries real traffic

ANTHROPIC_DEFAULT_HAIKU_MODEL is easy to skip because you never select Haiku yourself. Claude Code uses it for background work — conversation titles, summaries — so leaving it unset sends a steady trickle of requests to an id Mesh does not serve. In a short verification session, roughly a third of the requests were Haiku.

Verify it works

CLAUDE_CONFIG_DIR=~/.claude-mesh claude -p 'Say OK'

Then confirm the traffic actually reached Mesh — this is the check that distinguishes “configured” from “working”, since a misconfigured client can still answer from a direct Anthropic connection:

Dashboard
API

Open Usage. Requests from Claude Code appear with endpoint messages.

curl https://api.meshapi.ai/v1/usage/events?limit=5 \
  -H "Authorization: Bearer rsk_YOUR_KEY"

Look for rows with "endpoint": "messages".

Model discovery (optional)

Claude Code can populate its /model picker from the Mesh catalog instead of its built-in list:

{
  "env": {
    "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY": "1"
  }
}

Two caveats:

Discovery calls GET /v1/models, which accepts Authorization: Bearer only — not x-api-key. With ANTHROPIC_AUTH_TOKEN (as configured above) this is already correct; if you switch to ANTHROPIC_API_KEY, inference keeps working but discovery returns 401.
The catalog is large — the response covers the full model list and is fetched on start-up.

What runs through the gateway

Everything, which is the point of routing Claude Code this way:


Spend caps	A Claude Code session cannot exceed the key’s cap
Rate limits	Per-key RPM/RPD apply
Usage logging	Every request lands in `usage_events` with endpoint `messages`
Retry & fallback	Resilient routing applies
BYOK	Your own provider keys are used when configured

Troubleshooting

Symptom	Cause
`401 Invalid or missing API key`	Signed-in CLI overriding the token — use `CLAUDE_CONFIG_DIR` (§1)
`issue with the selected model (claude-opus-4-8[1m])`	`ANTHROPIC_DEFAULT_OPUS_MODEL` unset (§2)
`404 Model ... is not supported`	Hyphenated id — Mesh uses dots (`claude-sonnet-4.6`)
Works, but no rows in Usage	Requests are not reaching Mesh — re-check `ANTHROPIC_BASE_URL`
`402` mid-session	Key’s spend cap reached, or the account balance is exhausted

Messages API — the endpoint Claude Code uses
Available Models — exact ids for the model variables
Rate Limits — what applies to a session
Retry & Fallback — behaviour on provider failure

Introduction

Accounts & Access

Core Inference

Retrieval & Search

Multimodal

Operations

Mesh CLI

Platform

Reference

Configuration

The three things that catch people out

1. If you are signed in to Claude Code, `ANTHROPIC_AUTH_TOKEN` is ignored

2. `ANTHROPIC_DEFAULT_OPUS_MODEL` is not optional

3. Haiku carries real traffic

Verify it works

Model discovery (optional)

What runs through the gateway

Troubleshooting

​Configuration

​The three things that catch people out

​1. If you are signed in to Claude Code, ANTHROPIC_AUTH_TOKEN is ignored

​2. ANTHROPIC_DEFAULT_OPUS_MODEL is not optional

​3. Haiku carries real traffic

​Verify it works

​Model discovery (optional)

​What runs through the gateway

​Troubleshooting

​Related

Configuration

The three things that catch people out

1. If you are signed in to Claude Code, `ANTHROPIC_AUTH_TOKEN` is ignored

2. `ANTHROPIC_DEFAULT_OPUS_MODEL` is not optional

3. Haiku carries real traffic

Verify it works

Model discovery (optional)

What runs through the gateway

Troubleshooting

Related