Codex runs on a ChatGPT plan login (ES-F120–F129)
The codex engine authenticates from OPENAI_API_KEY in the environment
the worker inherits. Someone with only a ChatGPT plan has no key, and the
sandbox masks the Codex CLI's own login file (~/.codex/auth.json, W33).
This note records how a codex run may use the plan login instead, and why
it is built the way it is.
Invariants touched: I5 (no new permission system: the opt-in is a
project-policy key resolved like every other), I8 (the card, the run
record and skep doctor say which login a run used, never a value),
I9 (every refusal names the way forward), I12 (the network pin
gains exactly the host this mode needs). I1–I4 are untouched: the engine
stays forced into the sandbox, still needs a pinned verify_command, and
the patch still lands only through a human approval.
How the Codex CLI uses and refreshes auth.json
Read from the Codex CLI source at tag rust-v0.167.2 (the version
installed when this was built), codex-rs/login/src/:
auth/storage.rs(AuthDotJson): the file holdsauth_mode,OPENAI_API_KEY,tokens(id_token,access_token,refresh_token,account_id, ...) andlast_refresh.auth/manager.rs:3528(proactive_refresh_reason): a ChatGPT login (auth_mode: "chatgpt") is refreshed when the access token expires within 5 minutes (:222), or whenlast_refreshis older than 8 days (:221). A 401 also triggers a refresh (UnauthorizedRecovery).auth/manager.rs:3612(refresh_and_persist_chatgpt_token): the refresh calls the token endpoint first (:3630) and only then writes the new tokens back toauth.json(persist_tokens,:1726).auth/storage.rs:281+auth/storage_file.rs:34: a read-onlyauth.jsonmakes the write fail ("credential file is read-only"), but by then the refresh token has already been spent at the server.auth/manager.rs:225: refresh tokens are single-use. A reused one fails with "your refresh token was already used. Please log out and sign in again."auth/manager.rs:469,:1933,:3446: a file whoseauth_modeischatgptAuthTokens(tokens supplied by an external host) loads asCodexAuth::ChatgptAuthTokens, uses in-memory storage (it is never written back), and its refresh is a no-op: Codex never contacts the token endpoint for it.from_external_chatgpt_tokens(:899) is Codex's own constructor for this mode: access token plus account id, empty refresh token.model-provider-info/src/lib.rs:86: ChatGPT-mode requests go tochatgpt.com(/backend-api/codex), notapi.openai.com.
The access token in a fresh login lives about ten days.
The danger
Handing a run a copy of the whole file means the run holds the operator's refresh token. If Codex refreshes inside the sandbox, the server rotates the token: the run's copy gets the new one, the operator's own file keeps the spent one, and the operator's next Codex refresh fails with "already used". The operator is logged out. Making the copy read-only does not help, because the token is spent before the write is attempted. Copying a refreshed file back at the end of the run (the first sketch of W37) narrows the window but still breaks on a crash, a kill or two runs at once.
The design
The refresh token never leaves the host.
- The supervisor reads the operator's
$CODEX_HOME/auth.json(default~/.codex). It never writes it. - For a codex run that opted in and has no
OPENAI_API_KEY, it writes a new file in Codex'schatgptAuthTokensmode: the access token, the account id, an empty refresh token, mode 0400. Codex never refreshes this mode, so nothing a run does can rotate or revoke the operator's login. The file lives in the run's audit dir (<home>/supervisor/audit/<task>/codex-login.json), which every worker's sandbox masks; the run's redirectedCODEX_HOME(<workspace>/.toolchain/codex, 0700, v106-F1) holds only anauth.jsonlink to it, and that one run's sandbox binds the file back read-only after the masks. A copy inside the worktree would be readable by every other sandboxed run on the machine, whatever its engine or project: worktrees are not masked. - The access token must outlive the run's wall-clock budget plus 5
minutes, or the dispatch refuses before any run record exists and
says how to refresh on the host (use
codexonce, orcodex login; the Codex CLI refreshes its own file, under its own rules). - The run's network pin gets
chatgpt.com:443instead ofapi.openai.com:443: the one host this mode talks to. - The file is deleted when the run ends (the
finallyofrun_task), including runs whose worktree is kept for a retry..toolchain/(and so the link) is excluded from every patch. - The real login file stays masked from every worker (W33), wherever it
is:
~/.codex/auth.json, or$CODEX_HOME/auth.jsonwhen the operator setCODEX_HOME(the file skep reads is the file it masks). The builtin worker,claude_code,aider,piand every other codex run never get the run file: it is written only for an opted-incodexrun and only that run's sandbox can read it. The copy is on the secret floor too (codex-login.json, and the link to it by its realpath): the Queen'sread_file,search_filesand host shell refuse it, and no card lifts that.
Codex's own sandbox is off
skep runs codex exec --sandbox danger-full-access (ES-F220). Codex's
default, read-only, refuses every edit (ES-F128), and any Codex sandbox
starts its own bubblewrap for each shell call, which the kernel refuses
inside skep's Landlock domain: the first live run's shell calls all failed
with bwrap: Failed to make / slave: Operation not permitted and it made
no patch. On macOS, Codex's Seatbelt could not nest inside skep's either.
skep's sandbox (bubblewrap with the Landlock step on Linux, Seatbelt on
macOS) is the wall: a codex run is always dispatched in sandbox mode
(v94-F4), and the codex worker refuses to start when the spawner did not
mark its launch as sandboxed. See sandboxing.md, Landlock.
Opting in
Off by default. A project-policy key, codex_chatgpt_login (bool):
- CLI:
skep project setup <repo> --strategy <strategy> --phase <phase> --codex-chatgpt-login(--no-codex-chatgpt-loginturns it off again). A repeated setup keeps every stored key but needs the strategy again, and--phasedefaults tobuild, so name an existing project's own strategy and phase (skep project show <id>); the NO AUTH ENV refusal prints the exact line for the repo it refused. - chat:
setup_project ... codex_chatgpt_login=true(a HIGH confirmation card: it holds once and is never confirmable from a messenger channel);codex_chatgpt_login=falseturns it off copy_project_policynever copies it: each project opts in with its own HIGH card.
OPENAI_API_KEY, when set, still wins: the plan login is used only when
no key is present.
What says so
- The dispatch card and manifest: "uses your ChatGPT plan login (Codex)".
- The run record (the
dispatchedtransition) and the run'sworker.log:codex_auth=chatgpt_login. Never a value. Not the policy decision log (<audit>/policy/decisions.jsonl): that is the ledger ofdecide()verdicts, its replay counts every row as one, and a login choice is not a policy verdict. skep doctor: whether a ChatGPT login is saved, its plan and expiry when the token names them, which projects opted in, and what a codex run would use.- The NO AUTH ENV refusal names the option when a ChatGPT login exists.
Failure modes
- The token expires or is revoked mid-run (signed out elsewhere, password change): Codex gets a 401, cannot refresh, and the run fails. The operator's login is unaffected beyond whatever revoked it.
- The token is too close to expiry at dispatch: refused up front, with the refresh hint.
- The supervisor dies mid-run: the
finallydoes not run and the 0400 file stays in the run's audit dir, which no worker can read, until the operator removes it. It holds an access token only (at most ~10 days of life), never the refresh token. - The run reads its own token: the codex process and the commands it
runs can read the file, exactly as they can read
OPENAI_API_KEYin the key mode. The network pin limits where it can be sent tochatgpt.com. - Codex changes the format:
chatgptAuthTokensis a documented mode of Codex's app-server protocol. If a later Codex stops loading it from disk, the run fails with Codex's own "not logged in" error, the operator's login is untouched, and the API-key mode still works.
The Queen on the same login (v118, ADR 0063)
The Queen can run on the plan too, through the provider registry: skep provider add openai-codex --preset openai-codex --activate (or the chat
add_provider card, a HIGH card). It talks the Responses protocol to
https://chatgpt.com/backend-api/codex with the access token from the same
auth.json, read in place and never refreshed or written: nothing here
changes the rules above.
- The key for any profile on
chatgpt.comis this login or nothing — never the profile's key file,llm-secretor an env var.skep provider set-keyandprovider loginrefuse such a profile. - It is the Queen's alone. Activating it leaves
profile.json(the workers' provider) as it was, so builtin workers and the key relay keep their own provider; with none configured they refuse and say how to set one. No run is routed to it, pinned to its host or unmasked a key for it. - A missing login, an API-key login, a token within 5 minutes of expiry,
or a 401 from chatgpt.com ends the Queen's turn with the reason and the
fix: use
codexonce on this machine, orcodex login. - The provider list,
/api/llm/config, Settings andskep doctorreport the login's presence, plan and expiry, never a value.