Install and connect

Choose your deployment

Use the CLI that matches your workspace. Production, staging and development keep separate saved accounts and settings.

The guides use tokamak in examples. On staging, replace it with tokamak-stag; on development, use tokamak-dev. This applies to authentication, launch, status, usage and restore commands.

Install the CLI

For production on macOS or Linux:

curl -fsSL https://tokamak.sh/install.sh | bash

For staging on macOS or Linux:

curl -fsSL https://stag.tokamak.sh/install.sh | bash

For production in Windows PowerShell:

iwr -useb https://tokamak.sh/install.ps1 | iex

For staging in Windows PowerShell:

iwr -useb https://stag.tokamak.sh/install.ps1 | iex

For development, use the same installer path on dev.tokamak.sh. You can also find deployment-specific commands in your workspace's Setup guide.

The installer verifies the download against the release checksum, installs the command and then runs auth for you (see below). It prints only what you need. To also see the download URL, parts and hash, pass TOKAMAK_DEBUG=1 to the installer: curl -fsSL https://tokamak.sh/install.sh | TOKAMAK_DEBUG=1 bash, or in PowerShell $env:TOKAMAK_DEBUG = "1" before the iwr line.

• Windows: the command works in the same PowerShell window straight away. Terminals that were already open need a restart.
• macOS and Linux: curl … | bash cannot change the shell you typed into. Open a new terminal, or run the export PATH=… line the installer prints.

Authenticate

Run the command for your deployment and complete browser approval in the intended account and organization:

tokamak auth
tokamak status

On staging:

tokamak-stag auth
tokamak-stag status

For another deployment, explicitly choose its API origin:

tokamak auth --api-url https://YOUR_API_HOST

Use the API endpoint here, not the documentation URL. An API credential remains bound to its organization even when you switch organizations in the web workspace. Never put a real key in command arguments or committed configuration.

What happens after you approve

Login does not ask you to choose a default model. It saves the credential, then checks that you are ready to send requests:

✓ Authenticated as: [email protected]
  Organization: Acme (billed for your requests)
✓ 15 models available
✓ Credits: $25.00
✓ Claude Code 2.1.282

Start a coding agent through Tokamak:
  tokamak launch claude
  tokamak launch codex
Guides for every agent: https://tokamak.sh/docs/getting-started/coding-agents

• Models: how many models this account can use. With none, ask your organization's administrator to enable one. A server that routes Claude natively reports Claude models are routed by this server instead.
• Credits: shown when your organization's balance can be read. When an enforced wallet is empty, or the wallet is frozen, you get a warning and a link to Billing, because requests would be refused. A balance you are not allowed to see is skipped.
• Claude Code: the installed version, or a note that launching it installs it.
• Next: login ends there and never starts an agent itself. Run tokamak launch claude or tokamak launch codex in your terminal when you are ready, so the agent gets a normal interactive session for choosing a model.

Choose and launch an agent

Open the agent directory and follow your client's guide. Install desktop apps, Oh My Pi and Jan Agent separately. Other supported CLI launchers can install their package when missing; npm-based clients need a working Node.js/npm installation.

For a catalog model, use the interactive picker or replace YOUR_MODEL_ID with an exact model ID from your deployment. The picker groups models under headings (Claude, Codex, OpenAI, DeepSeek, Gemini, Jan, then other vendors) and shows each model's display name and context window. An ID ending in a tag such as [1m] is an alias your administrator published, marked alias.

With no saved default model, the first interactive launch of OpenCode, Pi or another agent that needs one asks you to choose and saves your pick. It asks again when your saved default is no longer in the model catalog. Codex CLI keeps its own model selection instead. Without a terminal, pass --model explicitly; most agents stop with Select a model with --model <catalog-id> when they have none.

tokamak launch codex --model
tokamak launch opencode --model YOUR_MODEL_ID

Match the model to the client's API: Messages, Responses or Chat Completions. Being listed in a catalog does not guarantee every dialect, image, tool or reasoning feature.

Claude Code's ordinary launch uses the server's native Claude route. Cowork discovers eligible models inside the desktop app:

tokamak launch claude
tokamak launch claude-cowork

Cowork does not accept --model.

Check setup and usage

Inspect local configuration without installing, writing settings or launching a client:

tokamak launch codex --model YOUR_MODEL_ID --check

This is an offline check, not a server or inference test. After a small request in your agent, inspect the client's response and your workspace's Analytics:

tokamak usage

Requests can consume credit. Usage costs, usage limits and wallet credit are separate measures. A successful launch or zero exit code does not establish that inference succeeded. See troubleshooting for authentication, model, credit and desktop issues.