PROVIDER GUIDE
OpenAI Codex CLI
Run OpenAI Codex CLI as a fully sandboxed agent on your machine. Each agent gets its own isolated CODEX_HOME, preventing cross-agent state pollution.
OpenAI API key Per-agent isolation CODEX_BIN_PATH if not in PATH
Requirements
- ✓ Codex CLI installed:
npm i -g @openai/codex - ✓ An OpenAI API key with access to the Codex model
- ✓ CTRL NODE Bridge installed on your machine (GitHub)
Quick start
Codex in PATH
$ PAIRING_TOKEN=your-pairing-token \
CODEX_API_KEY=sk-… \
./ctrlnode
CODEX_API_KEY=sk-… \
./ctrlnode
Codex NOT in PATH — set CODEX_BIN_PATH
$ PAIRING_TOKEN=your-pairing-token \
CODEX_API_KEY=sk-… \
CODEX_BIN_PATH=/home/user/.npm-global/bin/codex \
./ctrlnode
CODEX_API_KEY=sk-… \
CODEX_BIN_PATH=/home/user/.npm-global/bin/codex \
./ctrlnode
Without
CODEX_BIN_PATH, the Bridge tries to find codex in your PATH. If it fails you'll see: "Unable to locate Codex CLI binaries".
.env file
PAIRING_TOKEN=your-pairing-token
CODEX_API_KEY=sk-…
# Optional
CODEX_BIN_PATH=/path/to/codex
CODEX_DEFAULT_MODEL=codex-mini-latest
Environment variables
| Variable | Required | Description |
|---|---|---|
| CODEX_API_KEY | Yes | OpenAI API key used by the Codex CLI. |
| CODEX_BIN_PATH | No | Full path to the codex binary. Required if not in PATH. |
| CODEX_DEFAULT_MODEL | No | Model to use. Defaults to codex-mini-latest. |
Per-agent isolation
Each agent gets its own CODEX_HOME directory inside the Bridge workspace. This prevents agents sharing conversation history, models or cached state across tasks.
When multiple Codex agents run in parallel, each maintains a fully isolated environment — no cross-agent pollution, even when they work on the same repository.