Unlocking the Codex harness: how we built the App Server

OpenAI’s account of turning an internal convenience into a public protocol. The App Server began as a way to reuse the Codex harness in the VS Code extension without reimplementing the agent loop, so it was never designed as a stable API. Demand from internal teams and partners changed that: JetBrains and Xcode wanted an IDE-grade agent, and the desktop app needed to run many agents in parallel.

The design problem is that agent work is not request/response. One user input unfolds into a sequence of actions the client has to render faithfully, so the protocol settles on three primitives. An item is the atomic unit of input or output, typed and with an explicit started / delta / completed lifecycle so clients can paint as content streams. A turn is one unit of agent work started by a user input. A thread is the durable container of turns, and can be created, resumed, forked and archived.

Transport is JSON-RPC over stdio, bidirectional, so the server can also initiate requests, pausing a turn on an approval prompt until the client answers allow or deny. Clients exist in Go, Python, TypeScript, Swift and Kotlin. The two details worth keeping: the protocol is deliberately backward compatible, which lets a partner like Xcode keep a stable client and point it at a newer server binary to pick up fixes without shipping a release; and the TUI, historically a special case that talked directly to Rust types in-process, is being refactored to become just another client, which would let it drive a Codex server on a remote machine while the laptop sleeps.