# What Is the App Server Broker Endpoint in the OpenAI Codex Plugin?

> Understand the OpenAI Codex plugin's app server broker endpoint a URI that mediates client and local app-server communication. Learn its crucial role in plugin functionality.

- Repository: [OpenAI/codex-plugin-cc](https://github.com/openai/codex-plugin-cc)
- Tags: api-reference
- Published: 2026-07-10

---

**The app server broker endpoint is a URI string identifying a Unix domain socket or Windows named pipe that mediates communication between the Codex client and the local app-server broker process.**

In the `openai/codex-plugin-cc` repository, the broker architecture enables multiple Codex sub-agents to share tasks, handle cancellations, and report status through a persistent intermediary. The endpoint serves as the discoverable address that connects the plugin's runtime logic to this long-lived broker process.

## Understanding the App Server Broker Endpoint

The broker endpoint acts as the **addressable link** between the Codex plugin and the app-server broker. This URI tells the client exactly where to find the broker process on the local filesystem.

### Platform-Specific URI Formats

The endpoint format varies by operating system:

- **macOS/Linux**: Returns a Unix socket URI formatted as `unix:${path}/broker.sock` (e.g., `unix:/tmp/cxc-12345/broker.sock`)
- **Windows**: Returns a named pipe URI formatted as `pipe:${path}/broker.pipe`

These platform-specific formats ensure optimal inter-process communication performance across different environments.

## Creating and Parsing Broker Endpoints

The `broker-endpoint.mjs` module handles endpoint generation and validation.

### Generating Endpoints

Use `createBrokerEndpoint(sessionDir, platform)` to generate a valid endpoint URI for a new session directory:

```javascript
import { createBrokerEndpoint } from "./plugins/codex/scripts/lib/broker-endpoint.mjs";

const sessionDir = "/tmp/cxc-12345";
const endpoint = createBrokerEndpoint(sessionDir, "linux"); 
// Returns: "unix:/tmp/cxc-12345/broker.sock"

```

On Windows, the same function returns a pipe-based endpoint suitable for the Windows named pipe API.

### Validating Endpoint Strings

The `parseBrokerEndpoint(endpoint)` function validates endpoint strings and extracts transport metadata:

```javascript
import { parseBrokerEndpoint } from "./plugins/codex/scripts/lib/broker-endpoint.mjs";

const parsed = parseBrokerEndpoint("unix:/tmp/cxc-12345/broker.sock");
// Returns: { transport: "unix", path: "/tmp/cxc-12345/broker.sock" }

```

This function throws an error if the endpoint uses an unsupported scheme, ensuring type safety before connection attempts.

## Lifecycle Management of the Broker

The `broker-lifecycle.mjs` module manages the broker process lifecycle using the endpoint as the persistent identifier.

### Starting the Broker Session

`ensureBrokerSession()` creates the broker process and persists its endpoint to a session metadata file ([`broker.json`](https://github.com/openai/codex-plugin-cc/blob/main/broker.json)):

```javascript
import { ensureBrokerSession } from "./plugins/codex/scripts/lib/broker-lifecycle.mjs";

const session = await ensureBrokerSession(sessionDir);
// Stores endpoint in sessionDir/broker.json for later retrieval

```

### Loading and Reusing Sessions

`loadBrokerSession()` reads the stored [`broker.json`](https://github.com/openai/codex-plugin-cc/blob/main/broker.json) to retrieve the existing endpoint, allowing clients to reconnect to running brokers across separate process invocations.

### Graceful Shutdown

Send a JSON-RPC shutdown message to the broker endpoint to terminate the process cleanly:

```javascript
import { sendBrokerShutdown } from "./plugins/codex/scripts/lib/broker-lifecycle.mjs";

await sendBrokerShutdown("unix:/tmp/cxc-12345/broker.sock");

```

This invokes the `"broker/shutdown"` method implemented in `app-server-broker.mjs`, ensuring all pending operations complete before termination.

## Connecting the App Server Client

The `CodexAppServerClient` class in `app-server.mjs` consumes the broker endpoint to establish transport.

Clients receive the endpoint via the `brokerEndpoint` constructor option or the `CODX_BROKER_ENDPOINT` environment variable. When present, the client automatically sets its transport to `"broker"` and connects to the specified socket:

```javascript
import { CodexAppServerClient } from "./plugins/codex/scripts/lib/app-server.mjs";

const client = new CodexAppServerClient(process.cwd(), {
  brokerEndpoint: "unix:/tmp/cxc-12345/broker.sock",
  // additional options...
});

await client.start(); // Connects via the broker socket

```

This architecture decouples the client from the broker's physical location, enabling dynamic session management and multi-agent coordination.

## Summary

- The **app server broker endpoint** is a platform-specific URI (`unix:` or `pipe:` scheme) that identifies the broker's communication socket.
- **Creation** occurs via `createBrokerEndpoint()` in `broker-endpoint.mjs`, which generates appropriate Unix socket or Windows named pipe paths.
- **Lifecycle management** functions in `broker-lifecycle.mjs` persist the endpoint to [`broker.json`](https://github.com/openai/codex-plugin-cc/blob/main/broker.json) and support graceful shutdown via JSON-RPC.
- The **CodexAppServerClient** uses the endpoint (via `brokerEndpoint` option or `CODX_BROKER_ENDPOINT` env var) to establish broker transport in `app-server.mjs`.
- The endpoint enables **task sharing, cancellation, and status reporting** across multiple Codex sub-agents through a persistent broker process.

## Frequently Asked Questions

### What file formats does the broker endpoint use on different platforms?

On macOS and Linux, the broker endpoint uses Unix domain sockets with the `unix:` URI scheme (e.g., `unix:/tmp/cxc-12345/broker.sock`). On Windows, it uses named pipes with the `pipe:` scheme (e.g., `pipe:/tmp/cxc-12345/broker.pipe`). The `createBrokerEndpoint()` function in `broker-endpoint.mjs` automatically selects the appropriate transport based on the platform parameter.

### How does the Codex plugin store and retrieve the broker endpoint between sessions?

The plugin stores the endpoint in a [`broker.json`](https://github.com/openai/codex-plugin-cc/blob/main/broker.json) file within the session directory. The `ensureBrokerSession()` function writes this file when starting the broker, and `loadBrokerSession()` reads it to retrieve the endpoint for reconnecting to an existing broker process. This persistence mechanism allows separate client processes to discover and connect to long-running brokers.

### What happens if I provide an invalid broker endpoint URI?

The `parseBrokerEndpoint()` function validates the endpoint string and throws an error if it encounters an unsupported scheme or malformed URI. This validation occurs before any connection attempts, preventing runtime transport errors. Valid transports are strictly limited to `unix` (Unix sockets) and `pipe` (Windows named pipes) as defined in `broker-endpoint.mjs`.

### Can I specify the broker endpoint using environment variables?

Yes. The `CodexAppServerClient` checks for the `CODX_BROKER_ENDPOINT` environment variable when the `brokerEndpoint` option is not explicitly provided in the constructor. This allows deployment configurations to specify the broker location without modifying source code, facilitating containerized and distributed setups.