Codex App Server Documentation

Pages

1. OverviewWhat `codex app-server` exposes, who should integrate against it, supported transports, and the shortest path from `initialize` to a running turn.
2. InstallationHow to obtain and launch the `codex-app-server` binary, default listen URLs, session source, logging env vars, and success signals for stdio and control-socket modes.
3. QuickstartEnd-to-end first connection: `initialize` / `initialized`, `thread/start`, `turn/start`, read `item/*` and `turn/completed`, with verification and one recovery note.
4. Protocol and transportJSON-RPC 2.0 wire rules, stdio JSONL vs unix-socket vs websocket listeners, health probes, backpressure code `-32001`, and bounded queue behavior.
5. Threads, turns, and itemsCore primitives (`Thread`, `Turn`, `ThreadItem`), subscription model, thread status states, ephemeral threads, and how persisted rollouts relate to in-memory loaded threads.
6. Connection lifecyclePer-connection `initialize` handshake, `clientInfo` requirements, notification opt-out, thread subscribe/unsubscribe idle unload, and server-initiated requests vs client RPC.
7. Experimental APIRuntime opt-in via `capabilities.experimentalApi`, stable vs experimental schema generation, rejection messages, and maintainer gating patterns for fields and notifications.
8. Build a JSON-RPC clientClient responsibilities: newline-delimited framing, request ids, handling server requests mid-turn, `initialized` notification ordering, and compliance-oriented `clientInfo.name` values.
9. Transports and proxyChoosing `--listen` URLs, unix control socket at `$CODEX_HOME/app-server-control`, `codex app-server proxy` byte bridging, websocket auth args, and remote-control pairing endpoints.
10. Stream turns and eventsConsuming `turn/started`, `item/started`, deltas (`item/agentMessage/delta`, command output, reasoning), `turn/completed`, token usage, and notification opt-out for high-volume streams.
11. Approvals and server requestsInline approval flows for `commandExecution` and `fileChange`, `serverRequest/resolved` lifecycle, MCP elicitations, attestation `attestation/generate`, and `tool/requestUserInput` handling.
12. Account, auth, and configAccount login flows (`apiKey`, `chatgpt`, device code), config read/write/batch RPC, requirements.toml constraints, and hot-reload behavior after `config/batchWrite`.
13. Skills, plugins, and MCPListing and configuring skills, plugin marketplace install flows, `mcpServerStatus/list`, OAuth login, tool calls, reload after config edits, and `skills/changed` notifications.
14. In-process embeddingUsing `in_process` to run `MessageProcessor` without a socket, internal initialize handshake, `InProcessClientHandle` request/event channels, backpressure, and relationship to `codex-app-server-client`.
15. RPC methods referenceGrouped catalog of v2 `<resource>/<method>` RPCs for threads, turns, filesystem, models, processes, plugins, remote control, and utility commands with stable vs experimental markers.
16. Notifications and eventsServer notification method names, `ThreadItem` union variants, per-item delta events, turn-level events, realtime thread notifications, and `CodexErrorInfo` values on failures.
17. Config RPC reference`config/read`, `config/value/write`, `config/batchWrite`, `configRequirements/read`, `config/mcpServer/reload`, external-agent detect/import, and snake_case wire fields mirroring `config.toml`.
18. Schema generation`codex app-server generate-ts` and `generate-json-schema`, stable vs `--experimental` output, version pinning to the running binary, and when to regenerate fixtures after protocol changes.
19. CLI flags and error codes`--listen`, `--session-source`, `--strict-config`, websocket auth flags, JSON-RPC standard codes, overload `-32001`, `input_too_large`, and tracing via `RUST_LOG` / `LOG_FORMAT=json`.
20. Thread lifecycle examplesCopy-paste JSON-RPC sequences for `thread/start`, `thread/resume`, `thread/fork`, `thread/list` pagination, `turn/interrupt`, and `thread/unsubscribe` idle unload from README-backed tests.
21. TroubleshootingDiagnosing `Not initialized`, overload retries, turn failures and `codexErrorInfo`, strict config parse errors, MCP startup `failed` status, and websocket `Origin` rejections.
22. Development and testingRunning integration suites under `tests/suite`, spawning the binary via `test_app_server`, debug env hooks, notify-capture bins, and `just test -p codex-app-server` expectations.