Skip to main content
The Coding Agents experience is in beta.
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:
(or your distro’s package manager)
2. Install the Verlon CLI (-g recommended — it gives you the verlon command used throughout these docs):
(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 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) — and if you only use the VS Code extension, that’s fine: the path below covers you.

​
Check your setup

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.

​
Setup

In a terminal (not inside Claude Code), from the project directory you want to connect:
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:
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:
(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, either way:
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:
Then connect (the settings are written into the current project, so make sure you opened the right one):
…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:
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):
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:
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”.

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