Claude Code

What you get

Two modes — run Claude Code against the Tokamak router (the default), or with your own native Claude auth
One credential — your Tokamak API key replaces per-provider keys
Model pinning — explicit catalog selection pins model tiers and subagents; ordinary launch uses native routing when configured, otherwise offers a catalog picker
Usage tracking — token usage is recorded per request and visible via tokamak usage
Version pinning — every launch reconciles the installed Claude Code CLI against a Tokamak-vetted version

Prerequisites

Complete Install and connect; use tokamak-stag instead of tokamak on staging
Authenticated with tokamak auth

Setup

# Authenticate with your deployment's CLI
tokamak auth

tokamak auth opens your browser and asks you to approve the login. It then checks that you are ready to send requests: how many models your account can use, your organization's credits (with a link to add some when an enforced wallet is empty), and whether Claude Code is installed. Login finishes by printing the commands to start an agent (tokamak launch claude, tokamak launch codex) and a link to these guides; it never starts an agent itself.

Login does not ask for a default model. Claude Code picks from the catalog at launch, and Codex CLI keeps its own model selection unless you pass --model. Agents that need a saved model (OpenCode, Pi, Copilot CLI, DeepSeek Harness, Droid, Oh My Pi, Jan Agent and Codex App) ask the first time you launch them in a terminal and remember the choice. Without a terminal, or when the model catalog can't be read, they launch without a default and print how to pass --model <catalog-id>. Set TOKAMAK_DEBUG=1 to see the API key suffix, the config path and the installer's download details; tokamak launch --debug (or the same variable) shows every launch step.

Launch modes

Router mode (default)

tokamak launch claude

Claude Code runs against the Tokamak API router. The CLI sets routing/authentication for that process and resets the session model to Claude's native default through Tokamak, including server-enabled Claude Pool routing. When native routing is configured, saved Tokamak model and compaction defaults do not apply. Otherwise, interactive launch offers a catalog picker, grouped by vendor with each model's context window, with the saved default highlighted. The choice applies to this session only. For scripts, use an explicit --model <catalog-id>. Pool secrets remain on the server.

Routed launch uses a private temporary --settings overlay, preserving global/project files and managed-policy precedence. It sets the request timeout. Nonessential traffic and experimental betas are enabled by default unless explicitly disabled in saved preferences; tokamak config set claude_disable_nonessential_traffic true saves the nonessential-traffic opt-out (it survives tokamak auth; false restores the default). When every model the session can use is a Claude model, routed launch also turns on Claude Code's tool search (ENABLE_TOOL_SEARCH=true), so MCP tool definitions are not resent on every turn; a value you set yourself is kept. Setting "claude_prompt_cache_1h": true in ~/.tokamak/config.json asks for a one-hour prompt cache for the main conversation (subagents stay at five minutes); a one-hour cache write is billed at a higher rate, so it pays off only when sessions pause for more than five minutes between turns, and a fresh-credential tokamak auth turns it off again. Model/context/compaction settings apply only with explicit catalog selection. Conflicting client --settings options fail before update, authentication or installation. Temporary files are removed on normal exit and spawn failure; abrupt termination can leave them behind.

To pick a model for a single launch:

tokamak launch claude --model minimax  # Exact id, short form, or family prefix
tokamak launch --model                 # Interactive catalog picker
tokamak launch claude --tokamak        # Explicitly request router mode

The --model value resolves against the catalog (minimaxai/minimax-m2.7, minimax-m2.7, and minimax can all resolve to the same model; an ambiguous prefix opens a picker). Per-launch overrides never change your saved config.

The word after tokamak launch is always a tool name. The older tokamak launch <model-slug> shortcut is removed: tokamak launch minimax now fails with Unknown tool 'minimax' before anything runs, so use tokamak launch claude --model minimax instead.

Native Claude mode

tokamak launch claude --native

Use this when you want Claude Code to rely on your own Claude login or CLAUDE_CODE_OAUTH_TOKEN. Tokamak strips its own environment variables for that process, including inherited routing, auth and ANTHROPIC_CUSTOM_HEADERS, so a shell previously configured for Tokamak does not leak into native Claude. Configuration files remain intact; native inference is outside Tokamak metering.

--native cannot be combined with --model or other routed-model options, which are router-only.

Pinned Claude Code version

To keep every launch on a single Tokamak-vetted build of the Claude Code CLI (@anthropic-ai/claude-code), Tokamak pins a specific version. On each tokamak launch claude, the CLI compares the installed claude --version against the pin and reinstalls if they differ.

During a normal launch, the pin is resolved in this order: an explicit override, then the version published in Tokamak's CLI manifest (so older CLI installs pick up the current pin without reinstalling Tokamak), then a built-in fallback baked into the CLI. If the manifest is unreachable, the built-in fallback is used. This does not make routed model discovery or inference available offline.

Inspect what will run without launching anything:

tokamak launch claude --check     # Inspects local configuration and the enabled local pin; no version/API probe

Override or opt out for a launch:

# Pin a specific Claude Code version for this run
tokamak launch claude --claude-version 2.1.198

# Same, via environment variable
TOKAMAK_CLAUDE_VERSION=2.1.198 tokamak launch claude

# Skip pinning entirely — launch whatever 'claude' is already installed
tokamak launch claude --no-pin-claude

# Same, via environment variable
TOKAMAK_SKIP_CLAUDE_PIN=1 tokamak launch claude

Check your setup

tokamak status

tokamak status reports the CLI version and whether an upgrade is available, the configured API URL and account, your default model (none yet (chosen at first launch) until an agent's first launch saves one), whether local Claude auth is detected (Claude Local), and a live probe of the API: reachability, auth validity, latency, and how many models are visible.

Select catalog model metadata

tokamak launch claude --model-selection

Interactively pick catalog model metadata. The selection drives router runtime helpers such as context-window lookup, and pins Claude Code's model environment variables to your configured model.

Review advanced launch settings

tokamak launch claude --advanced-mode

Override per-run Claude settings before launch. Context and compaction controls require explicit catalog model selection. Advanced mode lets you move with the arrow keys, press Enter to choose, disable a setting for the current run, toggle the attribution header, or enter a custom timeout/compaction value.

Persist router mode in your shell

# Make plain `claude` use Tokamak in future shells
tokamak config claude

# Return to native Claude behavior
tokamak config claude --remove

tokamak config claude writes a delimited Tokamak block into your shell profile covering routing/auth and timeout. Ordinary shell setup leaves model/context/compaction choices unpinned. The API key is not written inline — the block reads it from ~/.tokamak/config.json at shell startup. --remove deletes the block.

Passing flags to Claude Code

Arguments after -- are passed through to Claude Code untouched:

tokamak launch claude -- --help

Metering and usage

Server AI API metering is authoritative, including Claude Pool. Authenticated client OTLP is separate activity and never an extra charge. The Tools tab includes unknown attribution and reports coverage; client-local cost estimates are not wallet debits.

View usage

# Last 30 days
tokamak usage

# Last 7 days
tokamak usage --period week

Troubleshooting

Connection errors

Re-authenticate with tokamak auth
Check tokamak status for reachability and auth validity
Verify your account and credential's organization in your deployment's workspace
Check Troubleshooting agents for unavailable Messages models, credit or output-bound errors

Timeout errors

For long-running tasks, review the timeout in advanced mode:

tokamak launch claude --advanced-mode

Switching back to native Claude

If Claude keeps using Tokamak when you want native auth, remove the persisted shell block and restart your shell:

tokamak config claude --remove
tokamak launch claude --native

"Unknown option" for a flag that used to work

The agent pool and board-issue integration were removed from the CLI. --pool, --pool-suffix, --issue, --new-issue, --no-issue, --pick-issue, --no-sync, --private, and --no-track now fail with an explanatory message. Drop the flag; launches route through the Tokamak API router.

On this page