Codex CLI API Wrapper

FastAPI service that wraps the Codex CLI and exposes OpenAI-compatible endpoints (/v1/completions, /v1/chat/completions) plus a simple /run. Supports bearer auth, configurable concurrency, and a small load test helper.

Quick Start

conda create -n codex2api python=3.13 # or any Python 3.11+ venv
conda activate codex2api  # or any Python 3.11+ venv
pip install -r requirements.txt

Configure .env (example):

CODEX_BIN=C:\Users\xxxxx\AppData\Roaming\npm\codex.cmd  # (output of `where codex` / Get-Command codex.cmd)
API_AUTH_TOKEN=local-token
MAX_CONCURRENT_RUNS=2
MAX_QUEUE_SIZE=4
API_HOST=127.0.0.1
API_PORT=8000

Run the server:

python run.py
# logs show: Starting server at http://<API_HOST>:<API_PORT>
curl http://127.0.0.1:8000/health

Endpoints

• /run (POST, no auth): {"prompt":"Hello","model":"gpt-5.1","args":[],"timeout":null,"clean":true}
• /v1/completions (POST, bearer auth): {"model":"gpt-5.1","prompt":"Hello"}
• /v1/chat/completions (POST, bearer auth): {"model":"gpt-5.1","messages":[{"role":"user","content":"Hello"}]}

Curl examples (Windows cmd):

set API_AUTH_TOKEN=local-token
curl -X POST http://127.0.0.1:8000/v1/completions ^
  -H "Authorization: Bearer %API_AUTH_TOKEN%" ^
  -H "Content-Type: application/json" ^
  -d "{\"model\":\"gpt-5.1\",\"prompt\":\"Hello\"}"

curl -X POST http://127.0.0.1:8000/v1/chat/completions ^
  -H "Authorization: Bearer %API_AUTH_TOKEN%" ^
  -H "Content-Type: application/json" ^
  -d "{\"model\":\"gpt-5.1\",\"messages\":[{\"role\":\"user\",\"content\":\"Hello\"}]}"

Concurrency & Queueing

• MAX_CONCURRENT_RUNS: how many Codex processes run in parallel (default 2).
• MAX_QUEUE_SIZE: how many requests may wait; beyond this returns HTTP 429 (default max(4, 2*MAX_CONCURRENT_RUNS)).
• Set per-request timeout in body if you need to bound Codex runtime; client-side you can also use --timeout in the test helper.

Test Helper

Fire concurrent requests to measure throughput/queueing:

python test_concurrency.py --count 8 --endpoint v1/chat/completions ^
  --base-url http://127.0.0.1:8000 --token %API_AUTH_TOKEN%

Notes and Safety

• This service shells out to codex exec; ensure CODEX_BIN points to a valid CLI and that you comply with its license and any upstream (OpenAI) terms. Do not expose this service publicly without proper auth and rate controls.
• Logs include command metadata (not prompts); avoid logging sensitive data. For production, add TLS, request logging/rotation, and stricter timeouts.