Connect Codex

Codex uses OpenAI's Responses API. Run Codex through its local Responses proxy, point that proxy at https://api.preview.arena.ai/v1/responses, and pass your Arena key as the upstream OpenAI-compatible API key. The gateway also supports /v1/responses/compact for Codex remote compaction.

1. Create a gateway key

  1. Open the Keys page and create a new key.
  2. Set the gateway URL, key, and an isolated Codex home for this workspace.
export ARENA_GATEWAY_URL=https://api.preview.arena.ai
export ARENA_API_KEY=<your-arena-key>
export CODEX_HOME="$PWD/.codex-arena"

2. Start the Responses proxy

Keep this command running in one terminal. The proxy listens locally and forwards HTTP Responses API requests to Arena Gateway.

mkdir -p "$CODEX_HOME"

printf '%s' "$ARENA_API_KEY" | \
  codex responses-api-proxy \
    --port 9322 \
    --upstream-url "$ARENA_GATEWAY_URL/v1/responses" \
    --http-shutdown

3. Launch Codex

In a second terminal, start Codex with the proxy as its OpenAI base URL. The isolated CODEX_HOME keeps this API key setup separate from your normal Codex login.

OPENAI_API_KEY="$ARENA_API_KEY" \
CODEX_API_KEY="$ARENA_API_KEY" \
CODEX_HOME="$CODEX_HOME" \
  codex -m gpt-4.1-mini \
    -c 'openai_base_url="http://localhost:9322/v1"' \
    -c 'forced_login_method="api"'

4. Verify the gateway connection

First confirm the key works directly against Arena's Responses endpoint.

curl "$ARENA_GATEWAY_URL/v1/responses" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ARENA_API_KEY" \
  -d '{
    "model": "gpt-4.1-mini",
    "input": "Say hello in exactly five words"
  }'

You can also verify the compact endpoint directly. A successful response contains opaque compaction output items for later Responses calls.

curl "$ARENA_GATEWAY_URL/v1/responses/compact" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ARENA_API_KEY" \
  -d '{
    "model": "gpt-4.1-mini",
    "input": "Remember: gateway compact works."
  }'

Then run a Codex one-shot through the local proxy.

OPENAI_API_KEY="$ARENA_API_KEY" \
CODEX_API_KEY="$ARENA_API_KEY" \
CODEX_HOME="$CODEX_HOME" \
  codex exec --ephemeral -C . \
    -m gpt-4.1-mini \
    -c 'openai_base_url="http://localhost:9322/v1"' \
    -c 'forced_login_method="api"' \
    "Reply with exactly: gateway-ok"

5. Stop the proxy

Shut the proxy down when the Codex session is done.

curl -fsS http://localhost:9322/shutdown

Tips

  • Use the gateway root URL for ARENA_GATEWAY_URL; the proxy command appends /v1/responses.
  • Use an OpenAI-backed model such as gpt-4.1-mini. Responses requests do not route to Anthropic models.
  • Routing aliases such as auto are allowed, but the gateway constrains Responses routing to OpenAI-backed models for both normal Responses and compact requests.
Arena API — Dashboard