OpenAI Codex App Server Architecture
The problem it solves
Codex runs in many places — CLI, VS Code, Web, Xcode — and building each integration separately is the “N-to-1” problem: N clients each reimplementing the same agent logic. The Codex App Server collapses that into one stable API. The agent’s core logic lives behind the protocol; every client surface talks to it the same way.
It has to carry more than request/response, because a single user request doesn’t produce a single reply — it unfolds into a stream of actions, artifacts, and incremental progress. The protocol is built to model that faithfully.
Conversation primitives
Three primitives model agentic work:
| Primitive | What it is | Lifecycle |
|---|---|---|
| Item | The atomic unit of input or output — a user message, agent message, tool execution, or diff. | started → delta (streaming) → completed |
| Turn | A grouped sequence of Items from one unit of agent work. | Initiated by user input, concluded by the agent |
| Thread | The durable session container; supports creation, resumption, forking, and archival. | Persisted event history for reconnection |
Protocol mechanics
The transport is JSON-RPC streamed as JSONL (JSON Lines) over stdio.
The differentiator is server-initiated requests. When the agent needs permission — say, to run a destructive command — the server sends a request to the client, the Turn pauses, the client replies allow or deny, and the Turn resumes. A purely client-driven protocol can’t express this cleanly; the App Server treats it as a first-class flow.
Why not MCP
OpenAI explicitly evaluated and rejected the Model Context Protocol (MCP) for this role. MCP’s tool-oriented model couldn’t map the rich session semantics an IDE needs — it struggled with streaming diffs, complex approval flows, and thread persistence in a way that felt native to VS Code. OpenAI still supports MCP for simpler, tool-based workflows, but recommends the App Server for full-fidelity agent integration.
Deployment patterns
Clients embed the App Server three ways:
- Local child process (VS Code, desktop) — the client bundles a platform binary and talks to it over bidirectional
stdio. - Decoupled binary (Xcode) — the client points to a separately updated binary, so agent logic can ship without a client release.
- Remote container (Web) — a worker provisions a container running the App Server; the browser talks to it over HTTP/SSE, keeping the UI thin while the server holds state.
Where it sits in the ecosystem
The App Server exists alongside the Agent Client Protocol (ACP), supported by Zed and JetBrains. The distinction is scope: the App Server is specific to the Codex harness and OpenAI’s ecosystem, while ACP aims to be a universal standard — the “LSP for agents” — connecting any agent to any editor.
