Codex app-server Protocol Guide

If you want your own Codex client, app-server is the integration surface. It gives you thread lifecycle, turn execution, streaming events, approvals, and model discovery over JSON-RPC.

Handshake first

Every connection must start with initialize followed by initialized. Skip that and requests fail.

{
  "method": "initialize",
  "id": 1,
  "params": { "clientInfo": { "name": "my_client", "version": "0.1.0" } }
}
{
  "method": "initialized",
  "params": {}
}

Core mental model

• Thread = conversation container
• Turn = one user input + model execution
• Items/events = incremental streamed progress

Minimum useful method set

• thread/list, thread/start, thread/resume, thread/read
• turn/start (with threadId + input)
• model/list

Approvals are a product feature, not a side case

Your client must handle approval requests explicitly and render them clearly. In mobile contexts this is the difference between “it works in demo” and “it works in life.”