# How to Configure Different Codex API Base URLs with the OpenAI Codex Plugin

> Easily configure different Codex API base URLs for the OpenAI Codex plugin using environment variables or session files. Use self-hosted or regional endpoints without code changes.

- Repository: [OpenAI/codex-plugin-cc](https://github.com/openai/codex-plugin-cc)
- Tags: how-to-guide
- Published: 2026-07-15

---

**Yes, the OpenAI Codex plugin supports configurable API base URLs through environment variables or persisted session files, allowing seamless switching between self-hosted instances, staging environments, and regional endpoints without modifying source code.**

The `openai/codex-plugin-cc` repository implements a dynamic endpoint resolution system that decouples the plugin from hardcoded API addresses. By leveraging the **Codex App Server** client architecture, the plugin can route all requests to alternative Codex instances by reading configuration from environment variables or local session persistence files.

## Understanding the Endpoint Resolution Architecture

The plugin determines which Codex API to target through a hierarchical resolution process implemented in `plugins/codex/scripts/lib/state.mjs`. The `getSessionRuntimeStatus` function (lines 6‑15) first checks for the `BROKER_ENDPOINT_ENV` environment variable (exposed as `CODX_ENDPOINT` to users), then falls back to endpoint data stored in the broker session file via `loadBrokerSession`.

All network communication flows through the **CodexAppServerClient** class, which receives endpoint configuration during initialization. When `CodexAppServerClient.connect` is invoked, it accepts an optional `env` object containing a custom `CODX_ENDPOINT` value, which it then uses for all subsequent `client.request` calls.

## Configuring Endpoints via Environment Variables

The simplest method to redirect the plugin involves setting the `CODX_ENDPOINT` environment variable before launching Claude Code. This approach overrides any persisted session configuration and immediately directs traffic to your specified URL.

```bash

# Point to a self-hosted Codex instance

export CODX_ENDPOINT="https://my-self-hosted-codex.example.com"

# Reload plugins to pick up the new environment variable

/reload-plugins

# Verify connectivity to the custom endpoint

/codex:setup

```

The plugin reads this value through the `BROKER_ENDPOINT_ENV` constant defined in the source code. If the variable is present, `getSessionRuntimeStatus` extracts it from `process.env[BROKER_ENDPOINT_ENV]` and passes it to the client initialization logic.

## Using Persisted Broker Session Files

For persistent configuration across sessions, the plugin stores endpoint metadata in a JSON file located at `<repository-root>/.codex/broker-session.json`. The `plugins/codex/scripts/lib/broker-endpoint.mjs` module handles reading and writing these persisted endpoints, enabling shared runtime states between different Claude Code windows.

To manually configure a different API base URL, modify the `endpoint` field in the broker session file:

```json
{
  "endpoint": "https://internal-codex.mycompany.com",
  "pid": 12345,
  "startedAt": "2024-11-01T12:34:56Z"
}

```

When `CODX_ENDPOINT` is undefined, the plugin automatically loads this file and uses the stored URL for reconnection attempts.

## Programmatic Endpoint Configuration

Developers building custom Claude Code extensions can programmatically specify endpoints by passing configuration objects directly to the client constructor. The `CodexAppServerClient.connect` method accepts an `env` parameter that bypasses both environment variables and session files.

```javascript
// Programmatic use inside a Claude Code extension
import { CodexAppServerClient } from "plugins/codex/scripts/lib/app-server.mjs";

const client = await CodexAppServerClient.connect(process.cwd(), {
  env: { CODX_ENDPOINT: "https://staging.codex.openai.com" },
  reuseExistingBroker: false,
});

await client.request("review/start", { /* request payload */ });
await client.close();

```

This approach is particularly useful for testing environments where you need to temporarily override the default endpoint without affecting global environment variables.

## CLI Verification and Runtime Status

The `/codex:setup` command (implemented in `plugins/codex/scripts/codex-companion.mjs`) validates endpoint connectivity during initialization. When executed, this command reports the currently detected endpoint and attempts to start a new shared runtime at that URL if none is running, providing immediate feedback on whether your custom configuration is reachable.

## Summary

- The Codex plugin uses `CodexAppServerClient` to manage API connections dynamically rather than hardcoding endpoints.
- Set the `CODX_ENDPOINT` environment variable to override the default URL for the current session.
- Persisted configuration stores the endpoint in `<repo>/.codex/broker-session.json` via the `broker-endpoint.mjs` helper.
- Programmatic users can pass custom environments directly to `CodexAppServerClient.connect` in `plugins/codex/scripts/lib/codex.mjs`.
- Use `/codex:setup` to verify connectivity against your configured base URL before executing Codex operations.

## Frequently Asked Questions

### Can the Codex plugin connect to self-hosted Codex instances?

Yes. By exporting `CODX_ENDPOINT="https://your-instance.example.com"` before launching Claude Code, or by editing the broker session file, you can direct the plugin to communicate with any Codex-compatible API server, including self-hosted deployments or enterprise internal instances.

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

If `CODX_ENDPOINT` is undefined and no broker session file exists, the plugin falls back to its default endpoint resolution logic. The `getSessionRuntimeStatus` function in `plugins/codex/scripts/lib/state.mjs` handles this gracefully by checking both sources sequentially before establishing connections.

### How do I verify which API endpoint the plugin is currently using?

Execute the `/codex:setup` command in Claude Code. This CLI tool (located in `plugins/codex/scripts/codex-companion.mjs`) displays the resolved endpoint URL and attempts to validate connectivity, showing whether the plugin will communicate with the default OpenAI servers or your custom-configured base URL.

### Can I change the endpoint without restarting Claude Code?

Yes. After modifying the `CODX_ENDPOINT` environment variable, run `/reload-plugins` to force the plugin to reinitialize and pick up the new configuration. Alternatively, updating the broker session file will affect the next connection attempt without requiring a full application restart.