OpenAI Codex on Linux

Install Codex

Helios uses the official Codex CLI’s persistent App Server. Install a current CLI using the official Codex guide. A user-local npm installation is one supported route:

npm install -g --prefix ~/.local @openai/codex
~/.local/bin/codex --version
~/.local/bin/codex login

The npm route needs Node.js and npm. Helios looks for HELIOS_CODEX_BINARY, codex on PATH, and ~/.local/bin/codex.

Choose account or API-key sign-in

Use codex login for the native account flow. Check it with:

codex login status

For API-key sign-in, use Settings → Providers → OpenAI · Codex and its key action. Helios passes the key to codex login --with-api-key through standard input and keeps no copy. Close active GPT sessions before replacing that login.

Exporting OPENAI_API_KEY alone does not authenticate Helios’s App Server. An environment CODEX_API_KEY does not substitute for its native credential store either.

Verify models in Helios

Check Settings → Accounts, then refresh Codex under Providers. Models become selectable after App Server reports them. The account and CLI determine available models, reasoning levels and Plan capabilities.

If a model was hidden in Helios, use Model picker · Shown models to restore it. A discovery failure and a deliberately hidden model need different fixes.

Use the native workflow

Start a chat in a project folder and select Codex/GPT. Ask for a short explanation first. Read the native approvals and inspect the sandbox setting in Execution before allowing edits or network access.

Supported Codex actions include native plans, compaction, Review and a fork from the current conversation head. The fork does not choose an earlier message cut point. Image input and Helios browser tools are available through their supported paths.

Understand usage and errors

Verified ChatGPT subscription sessions omit Helios’s API token cap. API-key sessions use the Codex token breaker described under budgets. Neither is an account-wide spending cap across other applications.

If sign-in is correct but startup fails, verify the CLI directly, refresh discovery and read Diagnostics. Leave HELIOS_CODEX_TRANSPORT unset; the retired exec path is disabled.