Special Topic
Inside OpenAI Codex
Study how a coding agent makes context, approvals, tool execution, MCP, and sandboxing governable through its architecture. The practical takeaway is a checklist for putting security into the system itself.
Special Topic32notes
THE QUESTION THIS PAGE ANSWERS
ANSWER FIRSTWhat will the “Inside OpenAI Codex” AI learning path help you do?
Study how a coding agent makes context, approvals, tool execution, MCP, and sandboxing governable through its architecture. The practical takeaway is a checklist for putting security into the system itself. The path contains 32 free notes, each centered on one question you can understand and test.
DECISION RULE
Core themes include Governance and Loops, Context, Tools, Sandbox.
TRY NEXT
Begin with “Read a coding agent as a system of boundaries,” then choose the next note by the task in front of you.
WATCH FOR
Do not optimize for finishing the list. Explaining one trade-off with your own example matters more than opening more titles.
What this route helps you practice
Open the first note
Each chapter follows a class of real decisions. Follow the sequence, or enter at the problem you are solving today.
01Read a coding agent as a system of boundariesBegin a source-led exploration of context, turns, tools, approvals, and sandboxing. The goal is to see how a coding agent earns trust through explicit boundaries rather than through a friendly interface.↗02Three-layer Turn Loop: who gets to say continueCodex splits one conversation into a task shell, a turn, and sampling: each layer answers only its own question, and control sits in one layer at a time.↗03The stream is still going. Tools already started.The model is still streaming words, and a tool call is already recognized. Codex writes history on OutputItemDone, then pins exec — every stream exit drains first.↗04Mid-turn interrupt: this turn, next turn, or refusedThe Agent is editing a file when you add a constraint. Codex uses one entry, three modes, and a two-stage mailbox to decide start, steer, or refuse on the spot.↗05After You Hit Cancel, How Each Layer Stands DownTool failures go back to the model; only Esc stops the turn. A cancel token travels from the task to sampling to tools, finished results stay in history, and a hard abort after 100 ms cannot be undone↗06Before You Stuff Context, Give It a TypeBefore Codex stuffs anything into model context, it first mints a type for each injection: the type knows its own role, marker, and body; assembly sorts by fields; later the same marker pair claims it back↗07Write Context Governance into Code ReviewA type system cannot police length, frequency, or prefix stability. Codex writes six bans into AGENTS.md, copies them into the code review skill, and lets review hold the cost after the type has already passed↗08After the Window Fills, What Gets Cut and What StaysCodex splits compaction into three timings times three implementations. Remote results hit a filter first; a mid-turn summary must sit as the last history item; flip the empty-window switch and memory does not come along↗09JSONL Is the Truth, SQLite Is the MirrorThe session writes as it runs. JSONL is the original. SQLite is a rebuildable cover. After a mid-run power cut, resume reads the file; the list can degrade↗10The tool list the model sees is computed for one sampleCodex plans the tool list per sample: identity trims sources, exposure decides visible vs searchable, then the result freezes into StepContext↗11Tell the model it can go parallel — a lock keeps the floorThe model is allowed to emit several tool calls at once. A request flag, a per-tool boolean, and one read-write lock work separately; history still books in emit order↗12One door: a command forks by featuresAfter a command enters the unified exec door, it forks by tty, remote env, and a 150ms window: PTY, pipe, exec-server — and only an early death can retry by policy↗13Sandbox manager: compile a permission profile into one commandWhat shell the same command gets on three platforms. Wanting a sandbox and having a backend are two different questions↗14macOS: stitch a security policy into one stringOn macOS, Seatbelt’s policy is stitched from text fragments. Paths go in a param table; a carve-out must block the node, its descendants, and a move↗15Linux: build the view, then seccomp, then execOn Linux, Codex first swaps the filesystem view with bubblewrap, then applies seccomp in the same helper, and only then execs the user command. Send one access request through and see which layer stops it↗16Windows: restricted token, firewall filter, and two dedicated system usersWindows has no seatbelt and no bubblewrap. Codex stacks a restricted token, a firewall filter, and two dedicated system users into a sandbox — and why AppContainer does not fit this permission model↗17execpolicy: Let the Policy File Carry Its Own TestsCodex writes positive and negative examples into the rule itself: how a command is split, prefix-matched, and judged at the strictest level, and how load-time tests pin down false hits↗18Approval Policy: Same Command, Two Knobs Decide Whether to AskPair the same command with different approval policies and the ending swings from a straight allow to a human nod. Whether it asks by default depends on whether the filesystem is Restricted. The session cache keys on an exact command.↗19Guardian: Let One Model Approve AnotherCodex Guardian replaces the approval popup with a locked review session: four steps, fail-closed, split accounting for timeouts versus denials, and a circuit breaker counted by turn↗20Network and Credential Proxy: The Key the Model Never SeesCodex funnels outbound traffic: the domain is judged first, the real token is swapped only inside the proxy, and the sandbox only allows the proxy port↗21apply-patch: A Diff Designed for ModelsCodex gives the model a line-number-free patch language: locate by context anchors, apply with four-level matching, and skip the disk write if a single file doesn’t match↗22exec and wait: How an Unfinished Program EndsCodex lets the model write JavaScript to orchestrate tools: a V8 isolate with capabilities subtracted, and a long-task protocol that yields the cell when time runs out, then continues with wait↗23Host Split: Who Holds the ProgramIn the default topology, V8 already lives in a separate host process. The same JS on four hosts: isolation boundary, lifetime, and failure fallout each change↗24A Multi-agent Graph Must Be PersistedCodex turns sub-agents into graph nodes: edges are Open or Closed, messages enqueue before they wake, and closing an edge leaves history intact↗25What a hook can change is set by the event contractCodex’s hook protocol names eleven events and four handler types, but the runtime table only loads commands and MCP. In one turn: what each hook gets, what it can change, and when it’s already too late↗26MCP comes in: the model sees translated namesWhen Codex takes an external MCP, tools pass a translation layer before the model sees them: prefix, sanitize, hash on collision. The skill catalog stays up; the body arrives only when named↗27Migration only keeps fields that mapCodex migrates from Claude Code and Cursor: detect lists the assets, import only keeps fields that map, plugins install from the user level only↗28SQ in, EQ out: two faces of the same thingCommands walk the Submission Queue; events walk the Event Queue. Rust calls it TurnStarted; JSON still writes task_started. Where an unknown type lands on each of the three paths↗29The external protocol is a projectionCodex’s external protocol is a projection: a turn/start first returns a response, then pushes the event stream. Approval is a reverse request. The two official SDKs do not walk the same protocol face↗30How streaming output finalizes between two terminal regionsCodex splits streaming output into a stable region and a live tail: finalized lines go to the terminal scrollback; an unclosed table stays in the mutable region so column widths do not keep reshuffling↗31Write architecture decisions as lintIn the same spec, rules with a red light rot at a different speed from rules without one. Call-site comments have a rustc plugin and three-platform CI; stale paths have nobody checking they still exist↗32Two security lenses: one command, two verdictsOn the same dangerous command, replayable asks whether the scene can be rebuilt; refusable asks whether a door could say no before anything happened. The two lenses can agree — and they can also contradict↗