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

# Claude Code Integration

> Run Claude Code on any model through a Verlon coding gate

<Note>
  The Coding Agents experience is in **beta**.
</Note>

Claude Code speaks the Anthropic Messages API, and Verlon provides an Anthropic-compatible endpoint — so Claude Code can run through a Verlon coding gate, backed by any model in the registry (GPT, Gemini, Mistral, or Claude). You get dashboard-controlled model switching, per-session observability with turn-by-turn timelines, and cost tracking for every coding session, with no changes to Claude Code itself.

## How it works

Claude Code reads a handful of environment variables that redirect its API traffic. You point its base URL at Verlon, authenticate with a Verlon API key, and put a **gate id** where Claude Code expects a model name. One gate covers the whole session:

* The gate's **coding model** answers your sessions (Claude Code's main-model traffic).
* Claude Code's automatic housekeeping calls (session titles, summaries — its "haiku tier") carry a `/background` suffix on the gate id and run on the gate's **background model**, which you'll typically point at something cheap.
* Subagent traffic carries a `/subagents` suffix so it's attributed separately; it runs on the coding model unless you route it elsewhere in the dashboard.

Claude Code decides which role each call belongs to on its own — you only decide what each role means, and you can change that from the dashboard at any time, mid-session.

## Setup

### One command (recommended)

From the project you want to connect:

```bash theme={null}
npx -y @verlon-ai/cli@latest connect claude-code
```

It authenticates (browser device flow, or reuses `VERLON_API_KEY`), creates or picks your coding gate, mints a dedicated API key, writes the settings into `.claude/settings.local.json` (git-ignored, so the key stays out of your repo), and enables usage telemetry. **Restart Claude Code** — settings are read at startup — and your next session appears on the dashboard within seconds.

Verify any time with `verlon doctor --gate <gate-id>` (traffic arriving, sessions grouping, costs accruing), switch models mid-session with `verlon switch <model-id>` (takes effect next turn, no restart — `verlon models` lists the ids), and undo everything with `verlon disconnect`.

Prefer staying inside Claude Code? Install the [Verlon plugin](https://github.com/verlon-ai/claude-plugin):

```
/plugin marketplace add verlon-ai/claude-plugin
/plugin install verlon
```

You get `/verlon:connect`, `/verlon:switch`, `/verlon:models`, and `/verlon:doctor` — thin wrappers over the same CLI — plus the bundled Verlon MCP server, so "switch my model to gemini-3-pro" works conversationally too.

### Manual setup (what connect does under the hood)

The dashboard also shows this block ready to copy: **Coding agents → New Claude Code gate**.

### Prerequisites

* Verlon AI account ([sign up](https://verlon.ai/signup)) and API key from your [Dashboard](https://verlon.ai/dashboard)
* A coding gate (Dashboard → Coding agents → New Claude Code gate): pick a coding model and a cheap background model; the gate id is on the page header

### Terminal

```bash theme={null}
export ANTHROPIC_BASE_URL=https://api.verlon.ai
export ANTHROPIC_AUTH_TOKEN=<your Verlon API key>
export ANTHROPIC_MODEL=<gate id>
export ANTHROPIC_DEFAULT_SONNET_MODEL=<gate id>
export ANTHROPIC_DEFAULT_OPUS_MODEL=<gate id>
export ANTHROPIC_DEFAULT_HAIKU_MODEL=<gate id>/background
export ANTHROPIC_SMALL_FAST_MODEL=<gate id>/background
export CLAUDE_CODE_SUBAGENT_MODEL=<gate id>/subagents

claude
```

The variables live only in that shell — other terminals keep talking to Anthropic directly.

### VS Code extension (per project)

The extension doesn't inherit shell exports. Put the same values in the project's `.claude/settings.local.json` (Claude Code keeps this file out of git, so the API key stays out of your repo):

```json theme={null}
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.verlon.ai",
    "ANTHROPIC_AUTH_TOKEN": "<your Verlon API key>",
    "ANTHROPIC_MODEL": "<gate id>",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "<gate id>",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "<gate id>",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "<gate id>/background",
    "ANTHROPIC_SMALL_FAST_MODEL": "<gate id>/background",
    "CLAUDE_CODE_SUBAGENT_MODEL": "<gate id>/subagents"
  }
}
```

Open the project and start a session as normal.

## What each variable does

| Variable                                                          | Purpose                                                                                                                          |
| ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `ANTHROPIC_BASE_URL`                                              | Sends Claude Code's requests to Verlon instead of Anthropic                                                                      |
| `ANTHROPIC_AUTH_TOKEN`                                            | Your Verlon API key (sent as a bearer token)                                                                                     |
| `ANTHROPIC_MODEL`                                                 | The gate id — main-model traffic runs on the gate's coding model                                                                 |
| `ANTHROPIC_DEFAULT_SONNET_MODEL` / `ANTHROPIC_DEFAULT_OPUS_MODEL` | Keep `/model` tier switches (and plan-mode hybrids) resolving to the gate                                                        |
| `ANTHROPIC_DEFAULT_HAIKU_MODEL` / `ANTHROPIC_SMALL_FAST_MODEL`    | Background/housekeeping traffic → the gate's background model (two spellings of one knob across Claude Code versions — set both) |
| `CLAUDE_CODE_SUBAGENT_MODEL`                                      | Attributes subagent traffic separately; runs on the coding model until you route it otherwise                                    |

## What you get

* **Sessions, not just logs** — every Claude Code conversation appears under the gate's Sessions tab, grouped into turns you can open: each model call with its role, model, duration, and cost.
* **Tool visibility** — with telemetry on (the connect default), the tools Claude Code runs locally (Bash, file edits) appear in the turn timeline between the model calls, with timing and status.
* **Live model switching** — `verlon switch <model>`, `/verlon:switch`, or the gate's Settings page; the running session switches on its next request, no restart.
* **Cost clarity** — spend per session and per turn, model mix, cache savings, and daily totals on the gate's Overview.
* **Failover** — optionally add a fallback model; sessions ride out a provider outage automatically. Note that failover sends session content to the fallback provider — it's opt-in for that reason.

## Privacy & security

* **Where your code goes:** routed sessions transit Verlon to reach the model provider. Payload storage follows your account's data controls — zero-data-retention is the default posture; see your dashboard's privacy settings for exactly what is stored and for how long.
* **Where your key lives:** `connect` writes it to `.claude/settings.local.json`, which Claude Code keeps out of git. The key is minted specifically for this machine — revoke it any time under **Settings → API Keys** without touching your other keys.
* **What telemetry sends:** metadata only — token counts, cost, model, tool names and timings, session ids. Your prompts, code, and tool outputs are **not** included (Claude Code redacts them by default; we don't ask you to change that). Remove the `OTEL_*` lines from the settings file — or run `verlon connect claude-code --no-telemetry` — to turn it off; the connector works either way.
* **Leaving:** `verlon disconnect` removes exactly what connect wrote and leaves your other Claude Code settings untouched. Your gate history stays on the dashboard; the key stays valid until you revoke it.

## Gotchas

* **Lots of MCP tools? Handled.** Sessions with many MCP servers can exceed OpenAI's legacy 128-tool limit — Verlon routes OpenAI-backed gates through the newer Responses API automatically, so large tool sets just work (500+ tools verified).
* **Use aliases, not full model ids, in subagent definitions.** A subagent whose frontmatter pins `model: haiku` resolves through the env mapping and stays on the gate; a literal id like `model: claude-haiku-4-5-20251001` bypasses it and fails with a clear error.
* **Model self-reports are unreliable.** Don't ask the assistant which model it is — the gate's request log records `model_used` for every call.
* **Experimental client features.** If you see 400s naming unfamiliar request fields, set `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1` to stop Claude Code sending pre-release capabilities.

To return to normal Claude Code, run `verlon disconnect` in the project (or close the terminal if you used shell exports) — no other state is kept.