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

## Step zero — two commands, once per machine

Everything on this page needs Node.js and the Verlon CLI. That's the whole dependency story: **the CLI is standalone and does everything; the plugin (later on this page) is an optional wrapper so you can stay inside Claude Code, and it bundles the Verlon MCP server. There is no install order — pick one path and follow it.**

**1. Make sure you have Node** — check with `node --version`. If it's missing:

<Tabs>
  <Tab title="macOS / Linux">
    ```bash theme={null}
    brew install node
    ```

    (or your distro's package manager)
  </Tab>

  <Tab title="Windows">
    ```powershell theme={null}
    winget install OpenJS.NodeJS.LTS
    ```

    Then open a new terminal and confirm with `node --version`.
  </Tab>
</Tabs>

**2. Install the Verlon CLI** (`-g` recommended — it gives you the `verlon` command used throughout these docs):

```bash theme={null}
npm install -g @verlon-ai/cli
```

(One-off alternative without installing: prefix any command in these docs with `npx -y @verlon-ai/cli@latest` instead of `verlon`.)

**New to Verlon?** Create an account at [verlon.ai/signup](https://verlon.ai/signup) and verify your email (verification activates your trial credit). You do **not** need an Anthropic API key — in routed mode your traffic runs on the gate's model through Verlon. Claude Code itself installs separately ([Anthropic's setup guide](https://code.claude.com/docs/en/setup)) — and if you only use the VS Code extension, that's fine: the path below covers you.

## Check your setup

```bash theme={null}
verlon preflight
```

This checks everything — Node, Claude Code (terminal or VS Code extension), your working directory, your account — and tells you exactly what's missing and how to fix it. `connect` runs the same checks automatically and stops with a remedy instead of failing halfway. If you're helping someone set up: have them run this and read you the output.

Then pick your mode:

* **Routed (default)** — Claude Code's traffic flows through Verlon to whatever model the gate selects. Model switching, payload observability, cost tracking.
* **Observability-only** — Claude Code keeps talking to Anthropic directly; only usage telemetry (never your code) streams to your dashboard. The minimal-trust way to try Verlon. See [Observability-only mode](#observability-only-mode).

## Setup

### Path 1 — terminal (recommended)

In a **terminal** (not inside Claude Code), from the project directory you want to connect:

```bash theme={null}
verlon connect claude-code
```

It checks your setup, prints the account it is acting as, authenticates (browser device flow, or reuses `VERLON_API_KEY`), resolves your coding gate, mints a dedicated API key **bound to that gate**, writes the settings into `.claude/settings.local.json` (git-ignored, so the key stays out of your repo), and enables usage telemetry.

**Which gate?** Nothing is ever picked silently. Your first connect creates a gate. After that, the terminal shows a menu of your claude-code gates — the project's current gate (on a re-connect) or your default gate pre-highlighted, "create a new gate" always an option. Keeping what you have is one Enter; switching is two arrow presses.

Then **restart Claude Code**. Settings are read at process start — starting a new chat is *not* a restart. In a terminal that means exit and re-run `claude`; in VS Code it means reloading the window (`Developer: Reload Window`). Your next session appears on the dashboard within seconds.

Already have a gate you want to use? Pass it explicitly:

```bash theme={null}
verlon connect claude-code --gate <gate-id>
```

Connect the same gate everywhere without picking each time? Mark it as your **default** — the menu pre-highlights it, scripts can rely on it, and the Claude Code plugin resolves to it without asking:

```bash theme={null}
verlon gate set-default <gate-id>
verlon connect claude-code --default   # non-interactive: uses the default, fails clearly if none is set
```

(Also settable from the dashboard: the gate's Settings → "Default for new connections". `verlon gate unset-default <gate-id>` clears it.)

Verify any time with `verlon doctor --gate <gate-id>` (traffic arriving, sessions grouping, costs accruing — plus which account you're acting as and which account this project's key belongs to). Switch models mid-session with `verlon switch <model-id>` (takes effect next turn, no restart — `verlon models` lists the ids). Undo everything with `verlon disconnect`.

### Path 2 — inside Claude Code (plugin; works for VS Code panel users)

Prefer never leaving Claude Code — or you only use the VS Code side panel? Open Claude Code **in the project you want to connect** and install the [Verlon plugin](https://github.com/verlon-ai/claude-plugin), either way:

<Tabs>
  <Tab title="Slash commands">
    Run these one at a time — the first registers Verlon's plugin source on your machine (nothing is published anywhere), the second installs from it:

    ```
    /plugin marketplace add https://github.com/verlon-ai/claude-plugin
    ```

    ```
    /plugin install verlon
    ```
  </Tab>

  <Tab title="VS Code panel (point-and-click)">
    Type `/plugins` in the prompt box to open the **Manage plugins** interface. In the **Marketplaces** tab, add `https://github.com/verlon-ai/claude-plugin`; then find **verlon** in the plugin list and click **Install**. No terminal needed.
  </Tab>
</Tabs>

Then connect (the settings are written into the **current** project, so make sure you opened the right one):

```
/verlon:connect
```

…and restart Claude Code as above (VS Code: reload the window). You get `/verlon:connect`, `/verlon:switch`, `/verlon:models`, `/verlon:doctor`, and `/verlon:disconnect` — thin wrappers over the same CLI — plus the bundled Verlon MCP server, so "switch my model to gemini-3-pro" works conversationally too.

### Observability-only mode

Don't want to route your traffic through anyone — but still want the usage picture? Connect in observability-only mode:

```bash theme={null}
verlon connect claude-code --observe-only
```

Claude Code keeps talking to Anthropic **directly** — zero added latency, no routing, nothing between you and the API. Its standard usage telemetry (tokens, cost, models, tool activity, session ids — **never your code or prompts**) streams to your Verlon dashboard, where sessions appear with the same turn-by-turn timelines. Your traffic never touches us, and the telemetry's own cost numbers are authoritative since nothing is being rerouted.

What you give up versus routed mode: model switching (traffic goes straight to Anthropic, so the gate's model doesn't apply) and per-call payload observability. Switching a project between modes is just re-running `connect` with or without `--observe-only` — same gate, same dashboard.

### Disconnecting

From a terminal in the project (or `/verlon:disconnect` inside Claude Code):

```bash theme={null}
verlon disconnect
```

It removes exactly what `connect` wrote from `.claude/settings.local.json` and touches nothing else. Then **restart Claude Code** — this is the step people miss: sessions already running keep routing through Verlon (and keep sending telemetry) until their *process* restarts, and a new chat is not a restart; in VS Code, reload the window. Your gate and its history stay on the dashboard, and the API key stays valid until you revoke it under **Settings → API Keys** — disconnecting never silently revokes anything.

### Manual setup

The dashboard shows a ready-to-copy settings block under **Coding agents → your gate → Setup**. If you'd rather wire it yourself: create a coding gate (Dashboard → Coding agents → New Claude Code gate), pick a coding model and a background model that is **cheap and large-context** (Claude Code's background summaries routinely exceed small context windows), grab an API key, and set the environment:

```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_FABLE_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
export ENABLE_TOOL_SEARCH=true
export CLAUDE_CODE_ENABLE_FINE_GRAINED_TOOL_STREAMING=1
export CLAUDE_CODE_ATTRIBUTION_HEADER=0

claude
```

The variables live only in that shell — other terminals keep talking to Anthropic directly. For the VS Code extension (which doesn't inherit shell exports), put the same values in the project's `.claude/settings.local.json` under `"env"` — this is exactly what `connect` writes.

## How it works

Claude Code reads 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**.
* 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.

**Direct model requests.** If Claude Code ever sends a literal model id instead of the gate id (a tier your env mapping missed, a subagent pinning a full model id), the request still resolves through your gate: keys minted by `connect` are bound to their gate, and the gate's **Direct model requests** policy decides what happens — **Remap** (default: route to the gate's model for that role, so the dashboard stays authoritative), **Honor** (serve the literal id, attributed through the gate), or **Block**. The requested id is always recorded, so the timeline shows "asked for X, served Y".

| 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` / `ANTHROPIC_DEFAULT_FABLE_MODEL` | Keep `/model` tier switches resolving to the gate (the Fable var requires a recent Claude Code; older clients are caught by the server-side remap) |
| `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                                                      |

## Switching accounts

The CLI's login is machine-global (like `gh`): the most recent `verlon login` wins in every terminal, and inside a connected session the project's key (injected via settings) outranks the login entirely. To see who you're acting as: `verlon whoami`. To keep multiple accounts: `verlon login --profile <name>` and `verlon auth switch <name>`. To reconnect a project under a different account from inside a connected session: `verlon connect claude-code --fresh` — it ignores the environment key and acts as your login. `verlon doctor` reports all of it: your acting identity, whether an environment key is shadowing your login, and which account the project's key belongs to.

## 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. Verlon does not store prompt or response content by default; customers opt in to encrypted payload storage from the dashboard — and note the opt-in covers failed requests too. 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 for this machine and bound to this gate — 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` (or `/verlon:disconnect`) removes exactly what connect wrote and leaves your other Claude Code settings untouched — then **restart Claude Code**: sessions already running keep routing (and keep sending telemetry) until their process restarts. Your gate history stays on the dashboard; the key stays valid until you revoke it.

## Gotchas

* **Restarts are per-process, not per-chat.** Connect and disconnect take effect when the Claude Code *process* restarts. A new conversation in the same window is not a restart; in VS Code, reload the window.
* **Pick a large-context background model.** "Cheap" isn't enough — Claude Code's background summarization calls routinely exceed small context windows (an 8K-context model fails them outright). Any modern mini-class model works.
* **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).
* **Subagent definitions can pin literal model ids.** A subagent whose frontmatter says `model: haiku` resolves through the env mapping; a literal id like `model: claude-haiku-4-5-20251001` reaches the server directly and follows your gate's Direct-model-requests policy (remapped to the background role by default).
* **Model self-reports are unreliable.** Don't ask the assistant which model it is — the gate's request log records what was asked for and what actually served 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.