> ## Documentation Index
> Fetch the complete documentation index at: https://developers.meshapi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Claude Code

> Route Claude Code through Mesh to reach every model in the catalog, with your spend caps, rate limits and usage logging applied.

Claude Code talks the [Anthropic Messages API](/docs/capabilities/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.

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

## Configuration

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

```json theme={null}
{
  "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.

<Warning>
  **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](/docs/reference/models-list).
</Warning>

## 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:

```bash theme={null}
CLAUDE_CONFIG_DIR=~/.claude-mesh claude
```

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

```bash theme={null}
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

```bash theme={null}
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:

<Tabs>
  <Tab title="Dashboard">
    Open [Usage](https://app.meshapi.ai/usage). Requests from Claude Code appear with
    endpoint **`messages`**.
  </Tab>

  <Tab title="API">
    ```bash theme={null}
    curl https://api.meshapi.ai/v1/usage/events?limit=5 \
      -H "Authorization: Bearer rsk_YOUR_KEY"
    ```

    Look for rows with `"endpoint": "messages"`.
  </Tab>
</Tabs>

## Model discovery (optional)

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

```json theme={null}
{
  "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](/docs/platform/retry-and-fallback) 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      |

## Related

* [Messages API](/docs/capabilities/messages-api) — the endpoint Claude Code uses
* [Available Models](/docs/reference/models-list) — exact ids for the model variables
* [Rate Limits](/docs/getting-started/rate-limits) — what applies to a session
* [Retry & Fallback](/docs/platform/retry-and-fallback) — behaviour on provider failure