Pi

What you get

• Responses models, one key — use a compatible catalog model without managing separate provider keys
• Usage tracking per request
• Auto-generated config — a managed models.json and settings.json are written to Pi's home directory on each run

Prerequisites

• Complete Install and connect; use tokamak-stag instead of tokamak on staging
• Authenticated (tokamak auth)
• Node.js 22+ (Pi is installed from npm as @earendil-works/pi-coding-agent)

Setup

# Authenticate with your deployment's CLI
tokamak auth

# Launch Pi
tokamak launch pi

Tokamak installs Pi if it isn't present, writes its managed provider/defaults and routes that provider through your selected Responses model. Native model changes can select another provider.

Auto-generated config

On each run, tokamak launch pi writes two files under ~/.pi/agent/.

models.json — merged into any existing file under the tokamak provider key, so your other providers are preserved:

{
  "providers": {
    "tokamak": {
      "baseUrl": "https://api.tokamak.sh/v1/",
      "api": "openai-responses",
      "apiKey": "TOKAMAK_API_KEY",
      "headers": { "X-Client-Name": "pi" },
      "models": [{ "id": "<your-selected-model>" }]
    }
  }
}

settings.json — selects Tokamak as the default:

{ "defaultProvider": "tokamak", "defaultModel": "<your-selected-model>" }

apiKey is the name of the environment variable Pi reads at runtime — not a literal key and not a $VAR reference. Tokamak sets TOKAMAK_API_KEY in Pi's environment at launch, and Pi resolves it when calling the provider.

Changing your model

tokamak launch pi --model             # Interactive catalog picker
tokamak launch pi --model <model-id>  # Update the managed default model

With no saved default, the first interactive tokamak launch pi asks you to choose a model and saves it. You can also switch models from inside Pi with Ctrl+P.

Passing flags to Pi

Any arguments after -- are passed through to Pi directly:

tokamak launch pi -- --thinking high

Metering

The managed provider uses Responses. Server inference is authoritative; supported client OTLP configuration is supplemental and does not add token charges. --check inspects setup offline. Client-native model changes can select another provider.

View usage

# Last 30 days
tokamak usage

# Last 7 days
tokamak usage --period week

Troubleshooting

Connection errors

• Re-authenticate: tokamak auth
• Check tokamak status for reachability and auth validity
• Verify your account and credential's organization in your deployment's workspace
• See Troubleshooting agents for credit and model errors; the recorded Windows run reached Tokamak but encountered a reservation refusal

Config conflicts

If Pi is not using the expected provider, inspect the native configuration and rerun with an explicit model. Keep a backup before editing a registry containing other providers; do not delete the whole file. The legacy Pi adapter writes its managed provider/defaults in place. Oh My Pi is a separate launcher with its own directory contract.

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