Codex App

Before you start

Install the desktop app from the official app guide, then complete Install and connect. This launcher targets macOS and Windows. Use tokamak-stag instead of tokamak for staging. Save your Tokamak account with auth; this desktop integration requires saved credentials rather than an environment-only key. Select a model that supports Responses.

Configure and open

tokamak launch codex-app --model YOUR_MODEL_ID --check
tokamak launch codex-app --model YOUR_MODEL_ID

The first command inspects local setup offline and names the app version the launcher was reviewed against. The second configures the provider and opens the installed app; it warns if the installed app is older than the oldest supported build, and never blocks. New local tasks in a running app pick up the provider and model; telemetry settings apply after you fully quit and reopen the app. Tokamak does not stop active tasks. Existing tasks and explicit model selections may retain different settings.

Windows can display the OpenAI.Codex package as ChatGPT. For a nonstandard installation, set TOKAMAK_CODEX_APP to the absolute desktop executable path.

What changes

Tokamak selects the tokamak-app Responses provider in your real CODEX_HOME/config.toml, normally ~/.codex/config.toml. This also changes the default for plain Codex CLI and the Codex IDE extension until restored. Your sessions, MCP servers, skills, approvals and account files remain in place. For per-run CLI configuration, use Codex CLI.

The provider's credential helper reads the saved Tokamak key and verifies its endpoint, environment and key fingerprint. Rerun the launcher after rotating the key or changing accounts. Keep the installed Tokamak executable at its configured path. The native client may cache the previous credential for up to five minutes.

Desktop telemetry credentials are stored in private user configuration because an app opened by the operating system may not inherit your terminal environment. Treat configuration, backups and restore journals as credentials. Prompt text is exported only when your organization turned on Insights prompt summaries; client activity remains separate from server usage metering.

Change models or restore

tokamak launch codex-app --model
tokamak launch codex-app --restore

Choose a catalog model with the first command. The second restores the original configuration offline. Fully reopen the app after either change. Relaunch and restore preserve unrelated app preferences. Conflicts in managed model, provider or telemetry settings require reconciliation with config.toml.tokamak-backup if that happens, keeping the backup private.

Troubleshooting and limits

• Choose models with tokamak launch codex-app --model. The app's own model picker lists only Codex's built-in OpenAI models. A pick works when the catalog carries that model under a vendor namespace (gpt-6-astra is served as openai/gpt-6-astra) and answers model not found otherwise. Picking one changes the configured model, and the next launch asks to reconcile it.
• If the app keeps its old model, fully quit/reopen it and create a new local task.
• WSL agent mode cannot run the Windows Tokamak credential helper; use the Windows agent mode.
• The app's auto-review approval mode asks for Codex's own review model, which Tokamak may not serve.
• If credentials stop working after account or key changes, authenticate and rerun the launcher.
• Prefer the default Codex home. A custom CODEX_HOME may not reach bundle or Start-menu launches; direct executable launches need separate validation.
• Cloud tasks and hosted features retain the app's account requirements. A local provider does not establish support for every cloud feature.

The recorded Windows check verified configuration and app activation without restarting active tasks. It did not verify desktop inference. Use troubleshooting and server usage to verify your own session.

The launcher resolves your saved default and explicit selection against the available catalog. Use the complete model ID returned by your server. Existing tasks can retain native model aliases that your server does not expose; select the catalog ID in that task or start a new one after reopening the app.