Codex Harness Architecture: State, Compaction, Interfaces, and Security Boundaries
OpenAI describes the harness in Codex as a platform as the open execution system behind different Codex experiences. The model proposes the next action; the harness gathers context, executes tools, preserves state, and either continues within configured boundaries or requests approval.
That adds several production responsibilities to the familiar “call tools until the task ends” loop. Work must continue across multiple model requests, long histories must shrink without losing the goal, clients need structured events, and consequential actions must pass both permission enforcement and approval policy.
Runtime State and the Execution Loop
Codex App Server represents runtime state as Thread → Turn → Item. A Thread is a continuing conversation, a Turn is one user task, and Items record messages, reasoning, commands, file changes, and tool results. Items become context for later Turns, so the harness preserves an execution trace rather than chat text alone.
The current turn implementation captures context for each Turn and can compact it before the next model sample when the context window approaches its limit. A model session is also reused across retries within the Turn to preserve connection and routing state.
Compaction Is a State Transition
The compaction implementation does not simply delete old messages. It first creates a model-generated summary, then replaces history with that summary, necessary user messages, and reinjected initial context. Whether compaction happens before a Turn or during one changes where the initial context is inserted.
This distinction affects long-task reliability. User intent, working directory, permissions, and unfinished work must survive compaction. Otherwise the history becomes shorter while the agent forgets where it is, what it may do, or which steps are complete. Compaction should therefore be tested as a state transition with invariants, not as routine token cleanup.
Three Integration Depths
| Interface | Appropriate use | What the application owns |
|---|---|---|
codex exec | CI, scripts, and bounded noninteractive tasks | preparing input and consuming the final result |
| Codex SDK | starting, resuming, or streaming an agent from code | CLI process lifecycle, Thread IDs, events, and versions |
| App Server | editors, desktop applications, and internal workbenches | persistent conversations, event streams, approval UI, and protocol compatibility |
The TypeScript SDK currently launches the codex CLI and exchanges JSONL events over stdin/stdout. App Server exposes the Thread, Turn, Item, approval, and compaction protocols, and can generate TypeScript types and JSON Schema that match the running Codex version. They reuse the same runtime ideas but are not the same client abstraction. Choose according to the lifecycle and interaction depth the product needs to own.
Sandbox and Approval Are Separate Boundaries
Codex's security documentation separates sandbox enforcement from approval policy. The sandbox determines which files and network resources a command can technically reach; the approval policy determines when Codex must stop and ask. Defaults disable network access and limit writes to the workspace, requesting approval for network use or writes outside it.
Disabling approval does not automatically remove the sandbox, while confirmation dialogs without OS-level isolation do not create a dependable boundary. danger-full-access removes filesystem and network sandbox restrictions while leaving approval policy separately configurable; --dangerously-bypass-approvals-and-sandbox bypasses both controls. Even in a container, these high-privilege configurations may let a malicious project read credentials and data available inside it.
The Codex open-source list includes components such as the CLI, SDK, and App Server, but the IDE extension and Codex Cloud are not open source. An open harness makes runtime behavior and protocols inspectable and adaptable; it does not open the model, hosted services, or the whole product stack.
Codex shows that the difficult part of a production harness is not the loop itself but state continuity, protocol compatibility, safety boundaries, and recovery around it. See AI Coding Harnesses, Agent Loop Patterns, Context Engineering, and Tool Contracts for the general design model.