# Codex App Server Documentation

> Reference for the `codex app-server` JSON-RPC 2.0 process: transports, connection lifecycle, thread/turn APIs, config and auth RPC, notifications, schema generation, and client integration patterns for IDE and embedded hosts.

This is a Grok-Wiki source-grounded repository documentation set. Use the complete Markdown link when an agent needs the full repo context.

## Context Links

- [Complete Markdown docs](https://grok-wiki.com/public/docs/openai-codex-c82680b15ec1/llms-full.txt)
- [Complete Markdown alias](https://grok-wiki.com/public/docs/openai-codex-c82680b15ec1.md)
- [Human interactive docs](https://grok-wiki.com/public/docs/openai-codex-c82680b15ec1)
- [GitHub repository](https://github.com/openai/codex)

## Repository

- Repository: openai/codex
- Branch: main
- Generated: 2026-06-02T06:42:53.759Z
- Updated: 2026-06-02T06:53:57.380Z
- Runtime: Grok CLI
- Format: Documentation
- Pages: 22

## Pages

- [Overview](https://grok-wiki.com/public/docs/openai-codex-c82680b15ec1/pages/01-overview.md): What `codex app-server` exposes, who should integrate against it, supported transports, and the shortest path from `initialize` to a running turn.
- [Installation](https://grok-wiki.com/public/docs/openai-codex-c82680b15ec1/pages/02-installation.md): How 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.
- [Quickstart](https://grok-wiki.com/public/docs/openai-codex-c82680b15ec1/pages/03-quickstart.md): End-to-end first connection: `initialize` / `initialized`, `thread/start`, `turn/start`, read `item/*` and `turn/completed`, with verification and one recovery note.
- [Protocol and transport](https://grok-wiki.com/public/docs/openai-codex-c82680b15ec1/pages/04-protocol-and-transport.md): JSON-RPC 2.0 wire rules, stdio JSONL vs unix-socket vs websocket listeners, health probes, backpressure code `-32001`, and bounded queue behavior.
- [Threads, turns, and items](https://grok-wiki.com/public/docs/openai-codex-c82680b15ec1/pages/05-threads-turns-and-items.md): Core primitives (`Thread`, `Turn`, `ThreadItem`), subscription model, thread status states, ephemeral threads, and how persisted rollouts relate to in-memory loaded threads.
- [Connection lifecycle](https://grok-wiki.com/public/docs/openai-codex-c82680b15ec1/pages/06-connection-lifecycle.md): Per-connection `initialize` handshake, `clientInfo` requirements, notification opt-out, thread subscribe/unsubscribe idle unload, and server-initiated requests vs client RPC.
- [Experimental API](https://grok-wiki.com/public/docs/openai-codex-c82680b15ec1/pages/07-experimental-api.md): Runtime opt-in via `capabilities.experimentalApi`, stable vs experimental schema generation, rejection messages, and maintainer gating patterns for fields and notifications.
- [Build a JSON-RPC client](https://grok-wiki.com/public/docs/openai-codex-c82680b15ec1/pages/08-build-a-json-rpc-client.md): Client responsibilities: newline-delimited framing, request ids, handling server requests mid-turn, `initialized` notification ordering, and compliance-oriented `clientInfo.name` values.
- [Transports and proxy](https://grok-wiki.com/public/docs/openai-codex-c82680b15ec1/pages/09-transports-and-proxy.md): Choosing `--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.
- [Stream turns and events](https://grok-wiki.com/public/docs/openai-codex-c82680b15ec1/pages/10-stream-turns-and-events.md): Consuming `turn/started`, `item/started`, deltas (`item/agentMessage/delta`, command output, reasoning), `turn/completed`, token usage, and notification opt-out for high-volume streams.
- [Approvals and server requests](https://grok-wiki.com/public/docs/openai-codex-c82680b15ec1/pages/11-approvals-and-server-requests.md): Inline approval flows for `commandExecution` and `fileChange`, `serverRequest/resolved` lifecycle, MCP elicitations, attestation `attestation/generate`, and `tool/requestUserInput` handling.
- [Account, auth, and config](https://grok-wiki.com/public/docs/openai-codex-c82680b15ec1/pages/12-account-auth-and-config.md): Account login flows (`apiKey`, `chatgpt`, device code), config read/write/batch RPC, requirements.toml constraints, and hot-reload behavior after `config/batchWrite`.
- [Skills, plugins, and MCP](https://grok-wiki.com/public/docs/openai-codex-c82680b15ec1/pages/13-skills-plugins-and-mcp.md): Listing and configuring skills, plugin marketplace install flows, `mcpServerStatus/list`, OAuth login, tool calls, reload after config edits, and `skills/changed` notifications.
- [In-process embedding](https://grok-wiki.com/public/docs/openai-codex-c82680b15ec1/pages/14-in-process-embedding.md): Using `in_process` to run `MessageProcessor` without a socket, internal initialize handshake, `InProcessClientHandle` request/event channels, backpressure, and relationship to `codex-app-server-client`.
- [RPC methods reference](https://grok-wiki.com/public/docs/openai-codex-c82680b15ec1/pages/15-rpc-methods-reference.md): Grouped catalog of v2 `<resource>/<method>` RPCs for threads, turns, filesystem, models, processes, plugins, remote control, and utility commands with stable vs experimental markers.
- [Notifications and events](https://grok-wiki.com/public/docs/openai-codex-c82680b15ec1/pages/16-notifications-and-events.md): Server notification method names, `ThreadItem` union variants, per-item delta events, turn-level events, realtime thread notifications, and `CodexErrorInfo` values on failures.
- [Config RPC reference](https://grok-wiki.com/public/docs/openai-codex-c82680b15ec1/pages/17-config-rpc-reference.md): `config/read`, `config/value/write`, `config/batchWrite`, `configRequirements/read`, `config/mcpServer/reload`, external-agent detect/import, and snake_case wire fields mirroring `config.toml`.
- [Schema generation](https://grok-wiki.com/public/docs/openai-codex-c82680b15ec1/pages/18-schema-generation.md): `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.
- [CLI flags and error codes](https://grok-wiki.com/public/docs/openai-codex-c82680b15ec1/pages/19-cli-flags-and-error-codes.md): `--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`.
- [Thread lifecycle examples](https://grok-wiki.com/public/docs/openai-codex-c82680b15ec1/pages/20-thread-lifecycle-examples.md): Copy-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.
- [Troubleshooting](https://grok-wiki.com/public/docs/openai-codex-c82680b15ec1/pages/21-troubleshooting.md): Diagnosing `Not initialized`, overload retries, turn failures and `codexErrorInfo`, strict config parse errors, MCP startup `failed` status, and websocket `Origin` rejections.
- [Development and testing](https://grok-wiki.com/public/docs/openai-codex-c82680b15ec1/pages/22-development-and-testing.md): Running 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.

## Source Files

- `BUILD.bazel`
- `Cargo.toml`
- `README.md`
- `src/app_server_tracing.rs`
- `src/attestation.rs`
- `src/bespoke_event_handling.rs`
- `src/bin/notify_capture.rs`
- `src/config_manager_service.rs`
- `src/config_manager.rs`
- `src/config/mod.rs`
- `src/connection_rpc_gate.rs`
- `src/error_code.rs`
- `src/filters.rs`
- `src/fs_watch.rs`
- `src/fuzzy_file_search.rs`
- `src/in_process.rs`
- `src/lib.rs`
- `src/main.rs`
- `src/mcp_refresh.rs`
- `src/message_processor.rs`
- `src/models.rs`
- `src/outgoing_message.rs`
- `src/request_processors.rs`
- `src/request_processors/account_processor.rs`
- `src/request_processors/command_exec_processor.rs`
- `src/request_processors/config_errors.rs`
- `src/request_processors/config_processor.rs`
- `src/request_processors/external_agent_config_processor.rs`
- `src/request_processors/feedback_processor.rs`
- `src/request_processors/fs_processor.rs`
- `src/request_processors/initialize_processor.rs`
- `src/request_processors/marketplace_processor.rs`
- `src/request_processors/mcp_processor.rs`
- `src/request_processors/plugins.rs`
- `src/request_processors/process_exec_processor.rs`
- `src/request_processors/remote_control_processor.rs`
- `src/request_processors/request_errors.rs`
- `src/request_processors/thread_lifecycle.rs`
- `src/request_processors/thread_processor.rs`
- `src/request_processors/turn_processor.rs`
- `src/request_serialization.rs`
- `src/server_request_error.rs`
- `src/skills_watcher.rs`
- `src/thread_state.rs`
- `src/thread_status.rs`
- `src/transport.rs`
- `tests/all.rs`
- `tests/common/lib.rs`
- `tests/common/responses.rs`
- `tests/common/test_app_server.rs`
- `tests/suite/auth.rs`
- `tests/suite/mod.rs`
- `tests/suite/strict_config.rs`
- `tests/suite/v2/client_metadata.rs`
- `tests/suite/v2/compaction.rs`
- `tests/suite/v2/config_rpc.rs`
- `tests/suite/v2/mcp_server_status.rs`
- `tests/suite/v2/thread_inject_items.rs`
- `tests/suite/v2/thread_list.rs`
- `tests/suite/v2/thread_name_websocket.rs`
- `tests/suite/v2/thread_rollback.rs`
- `tests/suite/v2/thread_status.rs`