Codex App Server: 5 Ways to Build Custom Agent Clients

The Codex app server is OpenAI's open-source JSON-RPC protocol for building custom agent clients on the Codex harness, tools and SDK included.

What is the Codex app server?

The Codex app server is an open-source JSON-RPC protocol that wraps the Codex agent harness, the engine behind OpenAI's Codex coding agent. Speaking at the AI Engineer World's Fair 2026 in San Francisco, Dominik Kundel of OpenAI's Codex developer experience team explained that the same protocol powers the Codex desktop app, the VS Code extension, and third-party clients in Xcode and JetBrains IDEs.

Both the harness and the app server are open source under the Apache 2 license, so you can fork and modify them. Kundel also noted that the harness can connect to other model providers as long as they expose a Responses-API-compatible endpoint, with convenience settings for Ollama and LM Studio. Because the protocol changes between CLI versions, OpenAI recommends bundling a known version of the harness binary with your application rather than relying on whatever the user has installed.

How does the app server compare to the Agent Client Protocol?

The app server is conceptually similar to the Agent Client Protocol, a generic protocol for connecting coding agents to editors, but it gives you finer control over the specific parts of the Codex harness. A client sends JSON-RPC messages to the server to start threads, run turns, and receive streamed events such as configuration reads, file-search activity, and token deltas.

Kundel demonstrated this with a custom inspector that intercepts the real traffic between the Codex app and the app server, showing live thread-start events, streamed deltas, and file-search calls. The trade-off: ACP is agent-agnostic, while the app server is specific to Codex but exposes capabilities like per-thread model and sandbox settings that a generic protocol does not.

What can clients control through the protocol?

According to the talk, the protocol currently exposes more than 120 client message types, and OpenAI keeps adding more. They cover initialization, thread management, turns, goal setting, plugin listing, file search, and file-system modification.

Two client-facing features stand out:

• Sign in with ChatGPT. Users of your client can authenticate with their own ChatGPT subscription, and their usage draws down their existing Codex limits rather than yours.

• Full harness access. Because every capability the first-party apps use flows through the same protocol, a third-party client can offer essentially the same feature set as the official Codex app.

Customizing the agent: developer instructions and dynamic tools

The two main customization points are developer instructions and dynamic tools. Developer instructions are appended on top of Codex's system prompt rather than replacing it. Kundel recommended this because OpenAI continuously tunes the base prompt to keep it in-distribution for each model, and replacing it forfeits that work. The Codex app itself uses developer instructions to add app-specific behavior.

Dynamic tools let you expose new functions to the agent without going through MCP. Marking tools as deferred is the key detail: deferred tools are not injected into the system prompt. Instead, Codex discovers them through a tool-search tool, which keeps your context window clean when you have many functions. Per-thread configuration goes further, letting you switch model provider, choose a model, and set fine-grained sandbox rules for network access and file modification on a thread-by-thread basis.

How do you ship and integrate it?

The app server ships inside the Codex CLI binary, so an existing CLI install can start it immediately. The Codex desktop app bundles its own copy and updates it with every release; on Windows the bundle carries both a Linux build for WSL mode and a native Windows build. You can drive the server over standard input/output or WebSockets, and you can ask Codex to generate TypeScript bindings or a JSON schema matching the exact protocol version you bundle.

For integration, Kundel described two practical paths:

1. Use the Python SDK, which OpenAI recently released. It handles lifecycle management and simplifies sign in with ChatGPT behind a familiar interface.

2. Ask Codex to implement the protocol for you, pointing it at the documentation. Kundel reported using this approach to generate a native Windows client in Visual Basic largely in one shot.

When you only need to kick off scripted tasks, codex exec is the simpler choice: it provides a non-interactive interface well suited to CI/CD jobs such as auto-fixing a pull request. The app server wins when you need a rich client UI or many concurrent Codex threads, such as running an eval harness, because thread management and parallelism are built into the protocol.

The Doom demo: Codex inside a video game

To show the protocol is not limited to chat interfaces, Kundel demoed Codex running inside Doom. The demo was an Electron app wrapping Cloudflare's Doom WASM port running the FreeDoom game data, with the game files modified so a Codex interface renders natively inside the game. The Electron app forwards input to the app server over IPC.

Using dynamic tools, the in-game Codex could grant armor, health, and weapons by calling exposed game functions. Because the harness was still running locally on his machine, it could also run shell commands such as reporting the current working directory, meaning you could technically write code from inside Doom. Kundel's point: once the harness is a protocol, the interface can be anything, from game engines to background jobs to unusual hardware.

Three tips for building on the Codex app server

Kundel closed with three recommendations from OpenAI's own experience building first-party clients on this protocol.

1. Ship your own harness binary. Relying on the user's installed CLI exposes you to breaking changes and version drift. Bundling the version you built against removes both problems.

2. Expose new functions as deferred tools. The Codex app does this for self-control features such as spinning up automations. Deferral keeps the extra functions available without polluting the context window.

3. Extend with developer instructions before rewriting the system prompt. OpenAI tunes the base prompt continuously to keep it in-distribution for each model, and a custom system prompt throws away that tuning.

FAQ

• Is the Codex app server open source? Yes. Kundel stated at AI Engineer World's Fair 2026 that both the Codex harness and the app server are available under the Apache 2 license in the Codex repository, so you can fork and modify them.

• When should I use codex exec instead of the app server? Use codex exec for non-interactive scripting such as CI/CD tasks like auto-fixing a pull request. Use the app server when you need a rich client interface, streaming events, or many concurrent Codex threads.

• Do users need their own API keys? With sign in with ChatGPT, users of your client can authenticate with their own ChatGPT subscription, and usage counts against their existing Codex limits. You can also configure other Responses-API-compatible model providers, including local ones like Ollama.

• What transport does the protocol use? You can start the app server over standard input/output or over WebSockets, depending on your application's architecture. The protocol itself is JSON-RPC style.

• Why bundle your own harness binary? The protocol changes between CLI versions, so depending on the user's installed CLI risks breaking changes and missing features. Bundling a known version gives you a stable capability set.

From talks like this to written articles

Dominik Kundel packed a protocol walkthrough, a live inspector, and a Doom demo into eighteen minutes, and most of that knowledge lives only in the recording. If you have talks, interviews, or tutorials of your own sitting on YouTube, that same situation applies to your content.

Skala Blog turns a YouTube URL into a written article: paste the link, the video is transcribed, and the transcript becomes a structured, publishable draft you can review and edit. The details you explained on camera get a second life as text people can search and skim.

Source video