OpenAI Codex CLI

Use OpenAI's Codex command-line tool as a Cerevisor provider, ChatGPT subscription auth, sandbox modes, and the limits to know about.

The Codex CLI provider runs each agent by spawning codex exec --json as a subprocess. OpenAI's Codex runs the work in its own engine — with its own sandboxing and sign-in — while Cerevisor supervises: wave orchestration, dependency tracking, and inter-agent handoff stay with Cerevisor.

The main reason to use it: you have a ChatGPT Plus or Pro subscription and don't want to pay per-token for the same model when you're already paying monthly.

Prerequisites

  • Node.js (any recent LTS).
  • Codex CLI installed: npm install -g @openai/codex.
  • A ChatGPT Plus / Pro subscription (or an OpenAI API key; both auth modes are supported, but the subscription path is the typical case).

Setup wizard

  1. Settings → Providers → + Add provider → Codex CLI.

The wizard runs six steps:

1. Detect

Cerevisor runs codex --version to confirm Codex is installed and reachable. On Windows, it auto-resolves the .cmd shim that npm install -g creates.

2. Auth status

Runs codex login status to check whether you're already signed in. If you are, skip ahead. If not:

3. Sign in

Click Sign in. Cerevisor launches codex login, which opens your browser to sign in with your ChatGPT account. If the browser flow fails (headless machine, browser didn't open), choose use a code instead: Cerevisor runs codex login --device-auth and shows the URL + code to enter manually. Either way, the wizard polls codex login status every 2 seconds and advances when sign-in completes.

4. Keyring config (optional)

On supported platforms, the wizard offers to write Codex's auth into your OS keyring instead of the plain text file. Recommended.

5. Smoke test

Cerevisor runs codex exec --json with a trivial prompt to confirm everything works end-to-end. The smoke test result is shown.

6. Save

The provider becomes available.

What Codex CLI runs

When an agent uses the Codex CLI provider, Cerevisor invokes:

codex exec --json \
  --skip-git-repo-check \
  --cd <project-folder> \
  -c sandbox_mode=<read-only|workspace-write> \
  -c approval_policy=<untrusted|on-failure|never> \
  --output-last-message <temp-file> \
  -

The prompt is piped via stdin (the - positional). Workflow runs let Codex save its session (under ~/.codex/sessions/, outside Cerevisor) so you can chat with the agent afterward; Cerevisor's own background calls to Codex add --ephemeral instead and leave nothing behind.

Sandbox modes

Cerevisor translates your workflow's permissions to Codex's sandbox_mode:

Cerevisor permissions Codex sandbox_mode
File writes allowed (with or without shell / web) workspace-write — writes stay inside the project folder; if web access is also allowed, network access is enabled inside the sandbox
Everything read-only read-only

Cerevisor never selects Codex's danger-full-access mode; writes are always scoped to the workspace.

Approval policies

Cerevisor derives approval_policy from the same WorkflowPermissions (file write + bash execution + web access), not from a single trust-profile selector. The common patterns:

Cerevisor permissions Codex approval_policy
File write + bash both Allow (web optional) never
File write Allow, bash blocked on-failure
Read-only across the board untrusted

When in doubt, set the workflow permissions you actually want and let Cerevisor compute the matching Codex flags.

Known v1 limitations

These are the trade-offs of using Codex as your runner, known limitations, not bugs:

  • No per-tool permission prompts. Cerevisor can't intercept individual tool calls inside Codex's subprocess. Sandbox + approval policy are set up-front.
  • No mid-run conversation continuation. Codex's exec mode is one-shot per prompt: when Cerevisor's output check finds a problem, the retry runs as a fresh Codex attempt (with the prior output handed over as context) rather than continuing the same conversation. You can chat with a finished Codex agent, though — Cerevisor resumes the saved session (codex exec resume) so the follow-up has the run's full context.
  • Background features run as one-shot Codex tasks. Run retrospectives, memory crystallization, and the other background features work on a Codex default: each call becomes one small Codex task on your subscription. If a call fails (not signed in, quota exhausted), Cerevisor automatically retries it on another chat-capable credential in your library and records any fallback spend in Analytics → Models. The chat builder works the same way when Settings → Chat Builder → "Build with a subscription provider" is on; otherwise it asks you to point it at a chat-capable provider (the smoothest experience).
  • MCP tools added in Cerevisor don't reach Codex. Codex has its own tool catalog; Cerevisor doesn't inject MCP tools into the subprocess.
  • Cost is reported as $0.00. Subscription billing: Cerevisor has no way to compute per-call cost. The analytics view classifies these sessions as "subscription" so they're distinguishable from per-token runs.

Switching ChatGPT plans

The Codex CLI is tied to your ChatGPT account. If you upgrade or downgrade your plan, Codex picks up the change automatically, no Cerevisor action needed.

Windows note

npm install -g @openai/codex installs as codex.cmd on Windows. Cerevisor auto-resolves the .cmd path so child_process.spawn('codex', ...) works. If the wizard reports "Codex not found" but codex --version works in your terminal, restart Cerevisor, PATH is read at launch.

macOS note

If you launched Cerevisor from Finder (not Terminal), macOS strips PATH to the system defaults, so even though which codex works in your terminal, the launched app might not see it. Cerevisor uses fix-path at startup on macOS to repair PATH for the lifetime of the process, so this should be transparent.

Back to docs