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

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:

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:

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):

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

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:

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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}