OpenAI's Codex App Server is a bidirectional JSON-RPC API that enables different surfaces (web, CLI, IDE extensions, macOS app) to embed the same Codex agent harness. The architecture includes thread lifecycle management, authentication, tool execution, and a protocol built around three primitives: items (atomic I/O units), turns (agent work units), and threads (persistent conversations). The App Server evolved from an internal VS Code integration into a stable platform that supports streaming progress, tool approvals, and diffs. Integration patterns include local apps bundling the binary, web runtime using containers, and the TUI being refactored to use the protocol. The open-source implementation provides JSON Schema generation for building clients in multiple languages.
Table of contents
Origin of the App ServerInside the Codex harnessThe conversation primitivesIntegrating with clientsChoosing the right protocolTaking this forwardSort: