Skip to main content
The Codex App Server provides a JSON-RPC 2.0 API that powers rich interfaces like the Codex VS Code extension.

​
Protocol

The App Server uses bidirectional JSON-RPC 2.0 communication with the "jsonrpc":"2.0" header omitted on the wire for efficiency.

​
Supported Transports

stdio

Default transport using newline-delimited JSON (JSONL)
codex app-server --listen stdio://

WebSocket

Experimental transport (unsupported for production)
codex app-server --listen ws://IP:PORT
WebSocket transport is currently experimental and unsupported. Do not rely on it for production workloads.

​
Core Primitives

The API exposes three top-level primitives representing interactions between a user and Codex:
A conversation between a user and the Codex agent. Each thread contains multiple turns.Key Operations:
  • thread/start - Create a new thread
  • thread/resume - Continue an existing thread
  • thread/fork - Branch from an existing thread
  • thread/list - List stored threads
  • thread/archive - Archive a thread
One turn of the conversation, typically starting with a user message and finishing with an agent message. Each turn contains multiple items.Key Operations:
  • turn/start - Send user input and begin generation
  • turn/interrupt - Cancel an in-flight turn
  • turn/steer - Add input to an active turn
Represents user inputs and agent outputs as part of a turn, persisted and used as context for future conversations.Item Types:
  • userMessage - User text/image input
  • agentMessage - Agent response
  • reasoning - Agent reasoning traces
  • commandExecution - Shell commands
  • fileChange - File edits
  • mcpToolCall - MCP tool invocations
  • webSearch - Web search requests

​
Message Schema

You can generate TypeScript or JSON Schema definitions for the current version: 
codex app-server generate-ts --out DIR
codex app-server generate-json-schema --out DIR
For experimental API surface: 
codex app-server generate-ts --out DIR --experimental
codex app-server generate-json-schema --out DIR --experimental

​
Backpressure Behavior

The server uses bounded queues between transport ingress, request processing, and outbound writes.
When request ingress is saturated, new requests are rejected with JSON-RPC error code -32001 and message "Server overloaded; retry later."Clients should treat this as retryable and use exponential backoff with jitter.

​
Tracing & Logging

​
RUST_LOG
environment variable
Controls log filtering and verbosity
RUST_LOG=debug codex app-server
​
LOG_FORMAT
environment variable
Set to json to emit structured logs to stderr
LOG_FORMAT=json codex app-server

​
Next Steps

Initialization

Learn how to initialize a connection

Threads

Manage conversation threads

Turns

Start and control conversation turns

Items

Understand item types and notifications