# Broker Endpoint for Codex Communication: Platform-Specific Transport Mechanisms

> Discover the broker endpoint for Codex communication. Learn how platform-specific transport mechanisms like Unix domain sockets and Windows named pipes enable seamless data exchange.

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

---

**The broker endpoint for Codex communication is a platform-specific transport generated by `createBrokerEndpoint` that resolves to Unix-domain sockets (`unix:<session-dir>/broker.sock`) on Linux and macOS, or Windows named pipes (`pipe:\\.\pipe\<sanitized-name>-codex-app-server`) on Windows systems.**

The broker endpoint for Codex communication serves as the critical transport layer between the Codex plugin and the internal app-server in the `openai/codex-plugin-cc` repository. This endpoint is dynamically constructed based on the session directory and host operating system, ensuring secure local inter-process communication across different platforms.

## How the Broker Endpoint Is Generated

The endpoint generation logic resides in `plugins/codex/scripts/lib/broker-endpoint.mjs`, which exports the `createBrokerEndpoint` helper. This function accepts a session directory path and returns a formatted broker endpoint string specific to the platform.

### POSIX Systems (Linux and macOS)

On POSIX systems, the function constructs a Unix-domain socket path by appending `broker.sock` to the session directory. The resulting endpoint follows the format `unix:<session-dir>/broker.sock`. For example, a session directory of `/tmp/session-abc` produces `unix:/tmp/session-abc/broker.sock`.

### Windows Named Pipes

On Windows, the implementation sanitizes the session directory name to remove illegal filesystem characters, then constructs a named pipe path. The format is `pipe:\\.\pipe\<sanitized-session-name>-codex-app-server`. This creates a unique named pipe for each Codex session while ensuring compatibility with Windows naming conventions.

## Implementation in the Codex Plugin

The generated endpoint is consumed by `plugins/codex/scripts/app-server-broker.mjs` to initialize the broker process. This file uses the endpoint string to establish the communication channel between the plugin and the app-server. Additionally, `parseBrokerEndpoint` (also exported from `broker-endpoint.mjs`) handles reverse parsing of endpoint strings when connecting to existing broker processes. Unit tests validating these formats are located in `tests/broker-endpoint.test.mjs`.

## Code Examples

Here are practical examples of generating broker endpoints for different platforms using the `createBrokerEndpoint` function.

**POSIX systems (Linux/macOS):**

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

const sessionDir = "/tmp/codex-session-123";
const endpoint = createBrokerEndpoint(sessionDir);
// Returns: "unix:/tmp/codex-session-123/broker.sock"
console.log(endpoint);

```

**Windows systems:**

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

const sessionDir = "C:\\Users\\Dev\\Sessions\\codex-session-123";
const endpoint = createBrokerEndpoint(sessionDir, "win32");
// Returns: "pipe:\\\\.\\pipe\\codex-session-123-codex-app-server"
console.log(endpoint);

```

## Summary

- The broker endpoint for Codex communication is generated by `createBrokerEndpoint` in `plugins/codex/scripts/lib/broker-endpoint.mjs`.
- **Linux/macOS**: Uses Unix-domain sockets with the format `unix:<session-dir>/broker.sock`.
- **Windows**: Uses named pipes with the format `pipe:\\.\pipe\<sanitized-name>-codex-app-server`.
- The `app-server-broker.mjs` module consumes this endpoint to establish the broker process.
- Unit tests in `tests/broker-endpoint.test.mjs` validate the platform-specific formatting.

## Frequently Asked Questions

### What file generates the broker endpoint for Codex communication?

The broker endpoint is generated by the `createBrokerEndpoint` function exported from `plugins/codex/scripts/lib/broker-endpoint.mjs` in the `openai/codex-plugin-cc` repository. This utility handles both Unix socket and Windows named pipe creation based on the platform.

### Why does Windows use a named pipe instead of a Unix socket?

Windows does not support Unix-domain sockets in the same way POSIX systems do. Instead, the Codex plugin uses Windows named pipes (`pipe:\\.\pipe\...`) which provide equivalent local inter-process communication capabilities. The implementation sanitizes the session name to ensure valid pipe naming conventions.

### How is the session directory sanitized on Windows?

The `createBrokerEndpoint` function removes illegal filesystem characters from the session directory name before constructing the pipe path. This ensures the resulting named pipe conforms to Windows naming requirements while maintaining uniqueness for the Codex session.

### Can I parse an existing broker endpoint string back into components?

Yes. The `broker-endpoint.mjs` module exports `parseBrokerEndpoint`, which reverses the formatting operation to extract the session directory and platform type from an existing endpoint string. This is used internally when connecting to existing broker processes.