# What Is the Broker Endpoint in the Codex Plugin and When Is It Used?

> Learn about the Codex plugin broker endpoint. Discover when to use this optional URL for routing requests and maintaining persistent connections for background tasks.

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

---

**The broker endpoint in the Codex plugin is an optional URL that points to a proxy process routing HTTP‑gRPC requests between the plugin and the Codex App Server, primarily used to maintain persistent connections for background tasks that outlive the Claude Code process.**

The openai/codex-plugin-cc repository enables Claude Code to interact with the Codex App Server through a sophisticated client architecture. Understanding the broker endpoint in the Codex plugin is essential for configuring network isolation, sharing brokers across workspaces, or running background review jobs. This optional configuration parameter, defined in the protocol declarations, determines whether the plugin communicates directly with the app server or routes through an intermediary broker process.

## What Is the Broker Endpoint in the Codex Plugin?

The broker endpoint is defined in [`plugins/codex/scripts/lib/app-server-protocol.d.ts`](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/scripts/lib/app-server-protocol.d.ts) as an optional string property within the `CodexAppServerClientOptions` interface.

### Definition and Purpose

**`brokerEndpoint?: string`** represents a URL pointing to a broker process that acts as a proxy between the plugin (running inside Claude Code) and the Codex App Server. Rather than communicating directly with the app server, the plugin routes its HTTP‑gRPC requests through this separate broker service. This architecture enables connection persistence and state management for long-running operations.

### Configuration Options

According to the TypeScript declarations in [`app-server-protocol.d.ts`](https://github.com/openai/codex-plugin-cc/blob/main/app-server-protocol.d.ts) (lines 50‑57), the client options include three broker-related properties:

- **`brokerEndpoint?: string`** – Explicit URL to a running broker instance
- **`disableBroker?: boolean`** – When true, bypasses the broker entirely  
- **`reuseExistingBroker?: boolean`** – Allows the plugin to connect to an already-running broker instead of starting a new one

## When Is the Broker Endpoint Used?

The broker endpoint in the Codex plugin operates in three distinct modes depending on your configuration requirements.

### Default Automatic Broker Behavior

When `disableBroker` is **false** (the default), the plugin automatically locates and starts a broker process internally. In this scenario, you normally do not need to provide a `brokerEndpoint` value, as the plugin computes the endpoint automatically and manages the broker lifecycle for you.

### Custom Broker Configuration

Provide an explicit `brokerEndpoint` value when you need to run the broker on a different host or port. This configuration is necessary for:

- **Testing environments** requiring isolated network configurations
- **Network isolation** scenarios where the broker must reside on a specific subnet  
- **Multi-workspace setups** where several Claude Code instances share a single broker process

### Disabling the Broker for Direct Communication

Setting `disableBroker: true` bypasses the broker entirely, causing the plugin to communicate directly with the app server. When disabled, the `brokerEndpoint` value is ignored, and all RPC calls travel directly from the plugin to the Codex App Server without intermediary proxying.

### Background Jobs and Persistence

The broker endpoint becomes critical for **background Codex jobs** initiated through commands like `/codex:review --background`, `/codex:rescue`, and `/codex:status`. These jobs may outlive the original Claude Code process that spawned them. The broker maintains the RPC channel, stores task state, and enables subsequent commands (`/codex:status`, `/codex:result`) to retrieve progress or final results even after the initial process exits.

## Code Examples

The following TypeScript examples demonstrate how to configure the broker endpoint in [`plugins/codex/scripts/lib/app-server-client.ts`](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/scripts/lib/app-server-client.ts) implementations.

### Example 1: Default Broker Usage

```typescript
import { CodexAppServerClient } from '@codex/plugin';

// Use the default broker (no endpoint required)
const client = new CodexAppServerClient({
  // No brokerEndpoint supplied → plugin starts its own broker.
});

```

### Example 2: Custom Broker Endpoint

```typescript
import { CodexAppServerClient } from '@codex/plugin';

// Point to a custom broker running on another machine
const client = new CodexAppServerClient({
  brokerEndpoint: 'http://broker.mycompany.com:8080',
  // Optionally keep the broker running across sessions
  reuseExistingBroker: true,
});

```

### Example 3: Disable Broker Entirely

```typescript
import { CodexAppServerClient } from '@codex/plugin';

// Disable the broker entirely (direct app‑server communication)
const client = new CodexAppServerClient({
  disableBroker: true,
});

```

## Key Implementation Files

The broker endpoint functionality spans three critical files in the openai/codex-plugin-cc repository:

- **[`plugins/codex/scripts/lib/app-server-protocol.d.ts`](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/scripts/lib/app-server-protocol.d.ts)** – Declares `CodexAppServerClientOptions` including `brokerEndpoint`, `disableBroker`, and `reuseExistingBroker` (lines 50‑57)
- **[`plugins/codex/scripts/lib/app-server-client.ts`](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/scripts/lib/app-server-client.ts)** – Constructs the client that uses the broker endpoint when provided
- **[`plugins/codex/scripts/plugin.ts`](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/scripts/plugin.ts)** – Entry point for Codex plugin commands (`/codex:review`, `/codex:rescue`, etc.) that instantiate the client

## Summary

- The **broker endpoint** is an optional URL pointing to a proxy process between the plugin and Codex App Server, defined in [`app-server-protocol.d.ts`](https://github.com/openai/codex-plugin-cc/blob/main/app-server-protocol.d.ts).
- When `disableBroker` is false (default), the plugin automatically manages the broker without requiring an explicit endpoint.
- Provide a custom `brokerEndpoint` for network isolation, testing, or multi-workspace broker sharing.
- Background jobs require the broker to maintain persistent connections and task state after the Claude Code process exits.
- Set `disableBroker: true` to bypass the broker and communicate directly with the app server.

## Frequently Asked Questions

### What happens if I don't specify a broker endpoint?

If you omit the `brokerEndpoint` property, the plugin automatically starts and manages its own broker process when `disableBroker` remains false (the default). The endpoint is computed internally, and you do not need to configure it manually for standard operation.

### Can I run the broker on a remote machine?

Yes. Set the `brokerEndpoint` property to the URL of a broker running on a different host or port, such as `http://broker.mycompany.com:8080`. Combine this with `reuseExistingBroker: true` to prevent the plugin from attempting to start a local broker instance.

### Why do background Codex jobs require a broker?

Background jobs like `/codex:review --background` and `/codex:rescue` may outlive the original Claude Code process. The broker maintains the RPC channel and stores task state, enabling subsequent commands such as `/codex:status` or `/codex:result` to retrieve progress and results after the initial process terminates.

### How do I completely disable the broker functionality?

Set `disableBroker: true` in the `CodexAppServerClientOptions`. This configuration forces the plugin to communicate directly with the Codex App Server, ignoring any `brokerEndpoint` value and eliminating the proxy intermediary.