# Where Are the Application Server Protocol Definitions in OpenAI Codex?

> Find application server protocol definitions in OpenAI Codex within the codex-rsapp-server-protocol crate at srcprotocolv2rs and commonrs. Explore the JSON-RPC wire format.

- Repository: [OpenAI/codex](https://github.com/openai/codex)
- Tags: deep-dive
- Published: 2026-03-06

---

**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`](https://github.com/openai/codex/blob/main/v2.rs), [`common.rs`](https://github.com/openai/codex/blob/main/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/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/`](https://github.com/openai/codex/blob/main/codex-rs/app-server-protocol/src/protocol) directory contains the substantive definitions:

- **[[`src/protocol/mod.rs`](https://github.com/openai/codex/blob/main/src/protocol/mod.rs)](https://github.com/openai/codex/blob/main/codex-rs/app-server-protocol/src/protocol/mod.rs)** – Re-exports all public types from submodules, acting as the canonical import target.
- **[[`src/protocol/common.rs`](https://github.com/openai/codex/blob/main/src/protocol/common.rs)](https://github.com/openai/codex/blob/main/codex-rs/app-server-protocol/src/protocol/common.rs)** – Defines shared primitives like `ThreadId`, pagination helpers, and base error types used across API versions.
- **[[`src/protocol/v2.rs`](https://github.com/openai/codex/blob/main/src/protocol/v2.rs)](https://github.com/openai/codex/blob/main/codex-rs/app-server-protocol/src/protocol/v2.rs)** – Houses the current Version 2 API surface, including all active request and response structs.
- **[[`src/protocol/v1.rs`](https://github.com/openai/codex/blob/main/src/protocol/v1.rs)](https://github.com/openai/codex/blob/main/codex-rs/app-server-protocol/src/protocol/v1.rs)** – Maintains legacy Version 1 definitions for backward compatibility.
- **[[`src/protocol/thread_history.rs`](https://github.com/openai/codex/blob/main/src/protocol/thread_history.rs)](https://github.com/openai/codex/blob/main/codex-rs/app-server-protocol/src/protocol/thread_history.rs)** – Provides streaming and pagination utilities specific to thread-history endpoints.
- **[[`src/protocol/serde_helpers.rs`](https://github.com/openai/codex/blob/main/src/protocol/serde_helpers.rs)](https://github.com/openai/codex/blob/main/codex-rs/app-server-protocol/src/protocol/serde_helpers.rs)** – Contains custom serialization and deserialization logic.
- **[[`src/protocol/mappers.rs`](https://github.com/openai/codex/blob/main/src/protocol/mappers.rs)](https://github.com/openai/codex/blob/main/codex-rs/app-server-protocol/src/protocol/mappers.rs)** – Implements conversions between internal domain models and protocol types.

## 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/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/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/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/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:

```rust
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:

```rust
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/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`](https://github.com/openai/codex/blob/main/v2.rs) and [`common.rs`](https://github.com/openai/codex/blob/main/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`](https://github.com/openai/codex/blob/main/v2.rs)** serving as the current API surface and **[`common.rs`](https://github.com/openai/codex/blob/main/common.rs)** providing shared primitives.
- The protocol uses **JSON-RPC** conventions with camelCase wire format enforced via Serde attributes.
- **[`write_schema_fixtures.rs`](https://github.com/openai/codex/blob/main/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/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/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/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/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.