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

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

Example 1: Default Broker Usage

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

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

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 – Declares CodexAppServerClientOptions including brokerEndpoint, disableBroker, and reuseExistingBroker (lines 50‑57)
• plugins/codex/scripts/lib/app-server-client.ts – Constructs the client that uses the broker endpoint when provided
• 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.
• 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.

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