OpenCode

Complete Install and connect, using tokamak-stag on staging. After authentication, run:

tokamak launch opencode --model <catalog-id>

Tokamak installs opencode-ai if missing. It merges a provider overlay into the child process's OPENCODE_CONFIG_CONTENT; it does not write or delete project opencode.json or opencode.jsonc files. Existing inline JSON/JSONC settings, plugins, permissions and other providers are retained. Invalid inline configuration is rejected before installation.

The tokamak provider uses @ai-sdk/openai-compatible, the configured Tokamak /v1 endpoint and {env:TOKAMAK_API_KEY}. The secret is supplied in the child environment. Both the main model and small_model are selected as tokamak/<catalog-id>. The chosen model must support Chat Completions and your required tools, images or reasoning; native plugins and explicit client routing retain their own behavior.

Models and native options

tokamak launch opencode --model              # Interactive catalog picker
tokamak launch opencode --model <catalog-id>
tokamak launch opencode -- --help

With no saved default, the first interactive tokamak launch opencode asks you to choose a model and saves it. --model-selection is a Claude-only option. Additional OpenCode arguments belong after --.

Metering and troubleshooting

Server API metering records routed inference, with X-Client-Name=opencode supplied through the provider's custom-header settings. With a resolved Tokamak identity the launcher turns on OpenCode's experimental OpenTelemetry and exports its traces (API calls and tool runs) to your Insights endpoint; that activity is supplemental and never an extra charge. Setting generic OTEL variables yourself does not add an exporter.

Use tokamak launch opencode --check for offline inspection and tokamak usage for recorded usage. If settings conflict, inspect your existing inline and native configuration; do not delete project files to regenerate a Tokamak overlay. Re-authenticate with tokamak auth if the API key was rejected.

The recorded Windows run reached Tokamak but encountered a credit reservation refusal; OpenCode returned zero despite the failed API request. Inspect the actual response and server usage. See Troubleshooting agents and Usage and spending.