# What Is the Codex Plugin Broker Endpoint and How It Communicates with the App Server

> Understand the Codex plugin broker endpoint, a platform-specific transport for lightweight IPC. Learn how it uses sockets and JSON-RPC to enable multiple processes to share a single server instance.

- Repository: [OpenAI/codex-plugin-cc](https://github.com/openai/codex-plugin-cc)
- Tags: internals
- Published: 2026-08-01

---

**The broker endpoint is a platform-specific transport string—either a Windows named pipe or Unix domain socket—that enables lightweight IPC between the Codex app-server and client components, allowing multiple processes to share a single server instance via JSON-RPC messages sent over a socket connection.**

The openai/codex-plugin-cc repository implements a **broker endpoint** mechanism to facilitate inter-process communication between the long-running app-server and various client components. This architecture eliminates the overhead of repeatedly spawning new server processes by providing a persistent connection point that clients can reference and reuse across multiple operations.

## What Is the Broker Endpoint?

The **broker endpoint** is a string that encodes the transport mechanism and address for reaching a running app-server process. Rather than spawning a new server for every command, the Codex Plugin uses this endpoint to establish a reusable communication channel.

### Endpoint Generation and Platform Abstraction

The endpoint is generated by `createBrokerEndpoint(sessionDir, platform)` in [`plugins/codex/scripts/lib/broker-endpoint.mjs`](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/scripts/lib/broker-endpoint.mjs). The function abstracts operating system differences by selecting either Windows named pipes or Unix domain sockets based on the platform:

```javascript
// On Windows → pipe:\\.\pipe\<sanitized-session-name>-codex-app-server
// On POSIX → unix:<sessionDir>/broker.sock
export function createBrokerEndpoint(sessionDir, platform = process.platform) {
  if (platform === "win32") {
    const pipeName = sanitizePipeName(`${path.win32.basename(sessionDir)}-codex-app-server`);
    return `pipe:\\\\.\\pipe\\${pipeName}`;
  }
  return `unix:${path.join(sessionDir, "broker.sock")}`;
}

```

On Windows, the function returns a string prefixed with `pipe:` followed by the named pipe path. On POSIX systems, it returns a `unix:` prefix followed by the absolute path to a socket file within the session directory.

### Environment Variable Configuration

Once generated, the endpoint string is exposed to clients through the **`CODEX_COMPANION_APP_SERVER_ENDPOINT`** environment variable. This constant is defined as `BROKER_ENDPOINT_ENV` in [`plugins/codex/scripts/lib/app-server.mjs`](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/scripts/lib/app-server.mjs) and exported when the app-server starts in broker mode. Clients can discover the active endpoint by reading this environment variable or by loading a broker session file from the filesystem.

## How the Broker Endpoint Communicates with the App Server

Communication proceeds through a three-phase process: parsing the endpoint string, establishing the socket connection, and exchanging JSON-RPC messages.

### Parsing the Transport String

When a client obtains the endpoint string, it calls `parseBrokerEndpoint(endpoint)` from [`broker-endpoint.mjs`](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/scripts/lib/broker-endpoint.mjs) to extract the transport type and concrete path:

```javascript
export function parseBrokerEndpoint(endpoint) {
  if (endpoint.startsWith("pipe:")) {
    return { kind: "pipe", path: endpoint.slice("pipe:".length) };
  }
  if (endpoint.startsWith("unix:")) {
    return { kind: "unix", path: endpoint.slice("unix:".length) };
  }
  throw new Error(`Unsupported broker endpoint: ${endpoint}`);
}

```

This function returns an object with `kind` (either `"pipe"` or `"unix"`) and the `path` necessary for Node.js's `net` module to establish a connection.

### Establishing the Socket Connection

Using the parsed result, the client creates a `net.Socket` connection via `net.connect()`. In [`plugins/codex/scripts/lib/app-server.mjs`](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/scripts/lib/app-server.mjs), the `BrokeredCodexAppServerClient` class handles this connection:

```javascript
import net from "node:net";
import { parseBrokerEndpoint } from "./broker-endpoint.mjs";

const endpoint = process.env.CODEX_COMPANION_APP_SERVER_ENDPOINT;
const { kind, path } = parseBrokerEndpoint(endpoint);

const socket = net.connect({ path }, () => {
  console.log(`Connected to app-server via ${kind}`);
});

```

The socket provides a bidirectional byte stream that serves as the foundation for all subsequent communication.

### JSON-RPC Message Exchange

Once connected, the client and app-server communicate using the protocol defined in [[`app-server-protocol.d.ts`](https://github.com/openai/codex-plugin-cc/blob/main/app-server-protocol.d.ts)](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/scripts/lib/app-server-protocol.d.ts). The client sends JSON-RPC requests and notifications over the socket using the `sendMessage` method implemented in `BrokeredCodexAppServerClient`:

```javascript
// Send a JSON-RPC request example
socket.write(JSON.stringify({ 
  jsonrpc: "2.0", 
  id: 1, 
  method: "initialize", 
  params: {} 
}) + "\n");

```

The app-server processes these messages and returns responses through the same socket, enabling multiple clients to multiplex operations through a single server instance.

## Broker Mode vs. Direct Process Spawning

The Codex Plugin supports two client implementations defined in [`app-server.mjs`](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/scripts/lib/app-server.mjs):

- **`SpawnedCodexAppServerClient`** – Spawns a new `codex app-server` process directly and communicates via stdio. Used when no broker endpoint is available.
- **`BrokeredCodexAppServerClient`** – Connects to an existing server via the broker endpoint socket. Used when `CODEX_COMPANION_APP_SERVER_ENDPOINT` is set or when `loadBrokerSession(cwd)` returns a valid endpoint (as implemented in [`plugins/codex/scripts/lib/codex.mjs`](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/scripts/lib/codex.mjs) at line 907).

```javascript
import { loadBrokerSession } from "./broker-lifecycle.mjs";

async function getClient(cwd) {
  const envEndpoint = process.env.CODEX_COMPANION_APP_SERVER_ENDPOINT;
  const session = await loadBrokerSession(cwd);
  const endpoint = envEndpoint ?? session?.endpoint ?? null;

  if (endpoint) {
    // Broker mode – connect to existing socket
    const client = new BrokeredCodexAppServerClient(cwd, { brokerEndpoint: endpoint });
    await client.initialize();
    return client;
  } else {
    // Direct mode – spawn a new app-server process
    const client = new SpawnedCodexAppServerClient(cwd);
    await client.initialize();
    return client;
  }
}

```

## Summary

- **The broker endpoint** is a transport string (`pipe:` on Windows, `unix:` on POSIX) generated by `createBrokerEndpoint()` that specifies how to reach a running app-server.
- **Environment discovery** happens via `CODEX_COMPANION_APP_SERVER_ENDPOINT` or session files loaded by `loadBrokerSession()`.
- **Connection flow** involves parsing the endpoint with `parseBrokerEndpoint()`, then establishing a `net.Socket` to the specified path.
- **Protocol** uses JSON-RPC over the socket, enabling multiple clients to share one app-server instance.
- **Fallback behavior** automatically spawns a new server via `SpawnedCodexAppServerClient` if the broker endpoint is unavailable or the connection fails.

## Frequently Asked Questions

### What transport protocols does the broker endpoint support?

The broker endpoint supports **Windows named pipes** (format: `pipe:\\.\pipe\<name>`) and **Unix domain sockets** (format: `unix:<path>`). The `parseBrokerEndpoint()` function in `broker-endpoint.mjs` handles both formats and throws an error for unsupported schemes.

### How does the client decide whether to use broker mode or spawn a new server?

The client checks for the `CODEX_COMPANION_APP_SERVER_ENDPOINT` environment variable first, then falls back to `loadBrokerSession(cwd)?.endpoint` as implemented in `codex.mjs`. If an endpoint exists, it instantiates `BrokeredCodexAppServerClient`; otherwise, it uses `SpawnedCodexAppServerClient` to launch a fresh process.

### Where is the broker endpoint string stored between sessions?

The endpoint is stored in the **`CODEX_COMPANION_APP_SERVER_ENDPOINT`** environment variable (defined as `BROKER_ENDPOINT_ENV` in `app-server.mjs`) and optionally persisted to a session file on disk that `loadBrokerSession()` can retrieve later.

### What happens if the broker socket connection is lost?

The `BrokeredCodexAppServerClient` detects disconnections through the socket's `error` and `close` events. According to the `handleExit` implementation in `app-server.mjs`, the client can then trigger a cleanup sequence, optionally restart the server, or fall back to spawning a new direct-connection client to maintain availability.