codex-exec

Drive headless Codex worker and validator agents with codex exec on the ChatGPT Pro subscription (OAuth) — the Codex side of the flywheel. The one inviolable rule: subscription billing, never per-token API billing.

⚠️ Critical Constraints

• Never API-bill a worker. Do NOT set OPENAI_API_KEY in a worker's env, and do NOT use codex login --with-api-key. Why: that flips Codex from flat-rate sub billing to per-token API billing — the Codex twin of the banned claude -p. A factory cycle on API keys silently burns real money. (Mirror of the "never claude -p for workers" rule.)
  • WRONG: OPENAI_API_KEY=sk-... codex exec -C "$REPO" "<task>"
  • CORRECT: codex login status # Logged in using ChatGPT then codex exec -C "$REPO" -s workspace-write "<task>"
• Confirm the sub before dispatch. Run codex login status and require Logged in using ChatGPT. Why: a worker that "runs fine" on a leaked API token bills per token; the check is the only thing standing between a green run and a surprise invoice.
• Pipe the prompt (or close stdin) in any non-TTY lane — else codex HANGS. A positional-arg codex exec "<prompt>" run with non-TTY stdin (background, &, ATM/NTM pane, cron, piped, inherited-pipe) still reads stdin — it prints Reading additional input from stdin... and blocks forever when that stdin never reaches EOF (the classic idle open pipe). Why: codex appends piped stdin as a <stdin> block even when a positional prompt is present, so an open idle stdin is an unterminated read. For unattended/background/factory lanes the safe DEFAULT is to pipe the prompt — printf '%s' "$P" | codex exec … - (or cat prompt.txt | codex exec … -) — or close stdin — codex exec "<prompt>" </dev/null. The bare positional form is fine only for an interactive TTY.
• Pick the sandbox deliberately. -s read-only for offline validators, -s workspace-write for workers that must edit, -s danger-full-access only inside an already-sandboxed host. Why: codex exec runs model-generated shell commands; the sandbox is the blast radius.
• Network-touching validators are the exception — use -s danger-full-access. A validator that must git fetch, clone a repo, or hit any network endpoint will FALSE-FAIL under -s read-only, because the sandbox blocks connect syscalls — the failure is an infrastructure artifact, not a real verdict. On an already-sandboxed host, give network validators -s danger-full-access. Offline validators stay -s read-only.
• --dangerously-bypass-approvals-and-sandbox is for externally-sandboxed hosts only. Why: it removes every guardrail in one flag; use it only when the OS/container is the sandbox.
• Don't strand work in --ephemeral. It skips session persistence, so there is nothing to resume. Why: a crashed ephemeral run cannot be recovered or continued.
• Multi-account lanes go through caam, not env-var juggling. Why: caam exec codex <profile> -- keeps each Pro lane isolated; hand-setting CODEX_HOME invites cross-account token bleed.

Why This Exists