Codex CLI API Demo

Minimal local API service that exposes:

• GET /health
• POST /chat
• POST /codex

POST /codex wraps your local Codex CLI with an HTTP endpoint. It runs codex exec on the machine where this server is running.

Run

npm install
$env:CODEX_API_TOKEN="change_this_local_wrapper_token"
$env:OPENAI_API_KEY="your_openai_api_key_here"
npm start

Open the local conversation manager:

http://localhost:3100/

Enter the same CODEX_API_TOKEN in the page to create, view, send, and delete Codex conversations. Conversation history is stored in data/conversations.json.

Calls made directly to POST /codex by other programs are automatically recorded in half-hour API Calls YYYY-MM-DD HH:mm conversations so they appear in the web console without making one long review-unfriendly thread. Each assistant response stores its parsed Codex CLI tokens used count, and conversation summaries show the accumulated token total.

Test

npm test

Example Request

Full API usage guide: API_USAGE.md.

Direct OpenAI call:

curl -X POST http://localhost:3000/chat `
  -H "Content-Type: application/json" `
  -d "{\"message\":\"你好\"}"

Codex CLI wrapper call:

curl -X POST http://localhost:3000/codex `
  -H "Content-Type: application/json" `
  -H "Authorization: Bearer change_this_local_wrapper_token" `
  -d "{\"user\":\"alice\",\"prompt\":\"list files in this project\",\"sandbox\":\"read-only\"}"

Optional POST /codex JSON fields:

• prompt: required Codex instruction.
• user: optional caller/user keyword used to group records in the web console; defaults to default when omitted. Older records without a user are shown as default.
• model: optional model passed to codex exec --model; see API_USAGE.md for model options and selection guidance.
• sandbox: optional, either read-only or workspace-write; defaults to read-only.
• cwd: optional working directory passed to codex exec --cd.
• timeoutMs: optional timeout in milliseconds.

Keep this service private or behind your own authentication. A Codex wrapper can read files and, with workspace-write, modify files inside the target workspace.