deep-dive

Where Are the Application Server Protocol Definitions in OpenAI Codex?

March 6, 2026 openai/codex ↗

The application server protocol definitions for OpenAI Codex are located in the codex-rs/app-server-protocol crate, specifically within the src/protocol directory where v2.rs, common.rs, and supporting modules define the JSON-RPC wire format.

The Codex repository organizes its machine-readable API contracts in a dedicated Rust crate that serves as the single source of truth for client-server communication. This crate, app-server-protocol, contains all request parameters, response structs, and serialization logic used by both the core client and the app server binary.

Core Location of the Protocol Crate

The application server protocol definitions reside entirely within the codex-rs/app-server-protocol directory. According to the source code, this crate is isolated to ensure that changes to the wire format are centralized and versioned independently of the business logic that consumes them.

The entry point for the crate is [src/lib.rs](https://github.com/openai/codex/blob/main/codex-rs/app-server-protocol/src/lib.rs), which publicly re-exports the protocol module for downstream consumers such as codex-core and codex-app-server.

Protocol Module Structure

Inside the crate, the src/protocol/ directory contains the substantive definitions:

Anatomy of the Protocol Definitions

The protocol follows strict conventions documented in the crate’s internal standards: camelCase wire naming, #[serde(rename_all = "camelCase")] attributes, and #[ts(...)] macros for TypeScript generation.

Common Types and Utilities

Before examining specific API versions, it is essential to understand the shared foundations in [src/protocol/common.rs](https://github.com/openai/codex/blob/main/codex-rs/app-server-protocol/src/protocol/common.rs). This file defines identifiers like ThreadId, standard pagination cursors, and error payloads that prevent duplication across method definitions. The [serde_helpers.rs](https://github.com/openai/codex/blob/main/codex-rs/app-server-protocol/src/protocol/serde_helpers.rs) companion file handles edge cases in JSON-RPC formatting, ensuring consistent DateTime serialization and optional field handling.

Version 2 API Surface

The actively developed API lives in [src/protocol/v2.rs](https://github.com/openai/codex/blob/main/codex-rs/app-server-protocol/src/protocol/v2.rs). This is where new RPC methods are added, including structs like ThreadReadParams, ThreadCreateParams, and their corresponding ThreadReadResponse and ThreadCreateResponse types. When the Codex client initiates a conversation with the app server, it instantiates these structs, which are then serialized into the JSON-RPC payload.

Legacy Version 1 Support

Backward compatibility is maintained through [src/protocol/v1.rs](https://github.com/openai/codex/blob/main/codex-rs/app-server-protocol/src/protocol/v1.rs). While new features are implemented exclusively in the v2 module, the v1 definitions remain available to support older clients, ensuring that breaking changes never disrupt existing integrations.

Practical Usage Examples

The protocol types are designed for direct use in Rust code. Below are practical snippets demonstrating how to construct requests and handle responses using the v2 definitions.

Constructing JSON-RPC Requests

To initiate a thread read operation, import the relevant types from the protocol module and populate the parameters struct:

use codex_app_server_protocol::protocol::v2::{ThreadReadParams, ThreadReadResponse};
use serde_json::json;

// Build a request to read a thread
let params = ThreadReadParams {
    thread_id: "thread-123".into(),
    cursor: None,
    limit: Some(20),
};

// Serialize to JSON ready for the JSON-RPC transport
let json_payload = json!({
    "jsonrpc": "2.0",
    "method": "thread/read",
    "params": params,
    "id": 1,
});
println!("{}", serde_json::to_string_pretty(&json_payload).unwrap());

Deserializing Server Responses

After receiving a server response, deserialize it into the strongly-typed protocol struct:

use codex_app_server_protocol::protocol::v2::{
    ThreadCreateParams, ThreadCreateResponse,
};

// Example of creating a new thread
let create_params = ThreadCreateParams {
    name: Some("My New Thread".into()),
    ..Default::default()
};

// In a real client you would send `create_params` via the JSON-RPC client;
let response: ThreadCreateResponse = /* await server response */;
println!("Created thread with ID: {}", response.thread_id);

Schema Generation and TypeScript Export

The protocol crate includes binary targets for generating cross-language bindings. The [src/bin/write_schema_fixtures.rs](https://github.com/openai/codex/blob/main/codex-rs/app-server-protocol/src/bin/write_schema_fixtures.rs) file implements a CLI tool that introspects the Rust types in v2.rs and common.rs to produce JSON-Schema files and TypeScript definitions. Running this tool ensures that frontend clients and documentation remain synchronized with the Rust backend definitions.

Summary

  • The application server protocol definitions are centralized in the codex-rs/app-server-protocol crate.
  • Core type definitions live under src/protocol/, with v2.rs serving as the current API surface and common.rs providing shared primitives.
  • The protocol uses JSON-RPC conventions with camelCase wire format enforced via Serde attributes.
  • write_schema_fixtures.rs generates TypeScript and JSON-Schema artifacts from the Rust source files.
  • Both the Codex core client and the app-server binary consume these types directly for type-safe communication.

Frequently Asked Questions

What crate contains the application server protocol definitions in Codex?

The definitions are contained in the app-server-protocol crate located at codex-rs/app-server-protocol. This crate is a dedicated library within the larger codex-rs workspace that exports all wire-format types used for JSON-RPC communication between the client and server.

How does Codex handle backward compatibility for API changes?

Codex maintains backward compatibility by preserving legacy protocol definitions in [src/protocol/v1.rs](https://github.com/openai/codex/blob/main/codex-rs/app-server-protocol/src/protocol/v1.rs) while actively developing new features in [src/protocol/v2.rs](https://github.com/openai/codex/blob/main/codex-rs/app-server-protocol/src/protocol/v2.rs). The server can deserialize requests targeting either version, ensuring older clients continue to function while newer clients leverage the v2 surface.

Can I generate TypeScript definitions from the Rust protocol files?

Yes. The crate includes a binary target [write_schema_fixtures.rs](https://github.com/openai/codex/blob/main/codex-rs/app-server-protocol/src/bin/write_schema_fixtures.rs) that generates TypeScript definitions and JSON-Schema files directly from the Rust structs. This build-time artifact ensures that frontend applications type-check against the exact same contract enforced by the Rust backend.

Where are the JSON-RPC method names defined in the protocol?

While the method strings (e.g., "thread/read") are typically referenced in the client and server routing logic, the associated parameter and response types that define each method's contract are located in [src/protocol/v2.rs](https://github.com/openai/codex/blob/main/codex-rs/app-server-protocol/src/protocol/v2.rs) for the current API version. The struct names (like ThreadReadParams) map to these method names through the JSON-RPC method field in the serialized payload.

Have a question about this repo?

These articles cover the highlights, but your codebase questions are specific. Give your agent direct access to the source. Share this with your agent to get started:

Share the following with your agent to get started:
curl -s "https://instagit.com/install.md"
Works with
Claude Codex Cursor VS Code OpenClaw Any MCP Client

Maintain an open-source project? Get it listed too →