Docker Codex

Install your own instance with npm install -g docker-codex, then run sudo docker-codex setup, sudo docker-codex login and sudo docker-codex smoke. Linux x64/systemd/Docker Engine is required. New installations default to Astra/medium. Run docker-codex help for all commands and headless flags. The package includes setup, integration, updates, and Claude Code/Codex documentation; docker-codex docs reads these without Git access. Each instance serves password-protected Swagger at its own /docs URL. Existing installations preserve their configured defaults, clients and Codex login during package updates.

A private API gateway for running Codex CLI in disposable Docker workers. Applications can use OpenAI or Gemini request formats, keep their own prompts and tool handlers, and select a Codex model and reasoning effort per request. New npm instances use gpt-6-astra with medium effort; the existing production instance retains its configured max default.

Production target: https://gpt.gowalk.com. Swagger: /docs, protected by a separate password.

How it works

The gateway authenticates a signed request, translates its conversation into native Codex history, and starts an isolated worker. A function call returns to the application that owns the tool; that application executes it and submits the result in the next request. Gateway workers never receive the support application's database, refund credentials, repository, or Docker socket.

Each worker runs without root or Linux capabilities, with a read-only image, memory/CPU/PID limits, a private job directory, and internet egress. A dedicated network blocks the host and private networks. The gateway is trusted infrastructure: its Docker control socket must never be exposed to a model worker. Jobs select from a dedicated Codex account pool and use a bounded worker pool (ten concurrent turns in production). Setup and updates install claude-multiacc automatically for quota-based selection and earned limit resets. Repeat docker-codex login to add accounts; docker-codex accounts shows their quota and status. A trusted login broker serializes persistent authentication access; model workers receive ephemeral tokens in protected app-server memory. Signed status exposes active, queued, and maximum worker counts. The shared worker slice limits the whole pool to 24 GiB and 20 CPU cores, with memory pressure control starting at 20 GiB. Individual workers retain their 4 GiB/2 CPU limits. The trusted login broker has its own 512 MiB/1 CPU cap. Workers cannot use swap or consume the rest of the host's resources.

API compatibility

| API | Endpoints | | --- | --- | | OpenAI text/tools | /v1/chat/completions, /v1/responses, response retrieval/deletion | | Gemini text/tools/images | /v1beta/models/{model}:generateContent, :streamGenerateContent | | Files | OpenAI multipart files; Gemini resumable upload, list, metadata, deletion | | Audio | /v1/audio/transcriptions with json, text, or verbose_json output | | Images | /v1/images/generations with base64 image output | | Models | /v1/models, /v1beta/models, and individual model retrieval, including alias targets | | Operations | Signed /api/v1/status with readiness, error code, model, effort, and build identity |

Core generation and media routes also have /api/v1 aliases. Protocol-compatible does not mean every OpenAI/Gemini service is implemented: batches, fine-tuning, embeddings, audio synthesis, background responses, and hosted provider-specific tools are outside this gateway's scope. Sampling controls and output-token settings are not native Codex app-server controls; selected Codex model limits apply. Unknown models and unavailable efforts fail explicitly. OpenAI json_object and Gemini JSON MIME mode enforce JSON-only final answers and validate the returned JSON. Full JSON schemas use native structured output; JSON mode allows dynamic keys.

Images retain their bytes; documents and other files are made available to sandbox tools. Audio is transcribed by a separate offline Whisper large-v3 container and supplied as quoted attachment content to Codex. The original audio remains available in the job. Image generation uses Codex's built-in image tool and returns its actual image result. Account capabilities require verification after login. Gemini accepts image model aliases and generationConfig.responseModalities: ["IMAGE"]; these requests require the images:generate scope and return actual base64 inlineData image parts. SSE includes keepalives during reasoning and final provider-format output events.

Models and efforts

All seven Codex models are supported. The authenticated account catalog is checked on every request. OpenAI and Gemini model names are accepted through explicit aliases, including dated/preview variants. gpt-6 resolves to gpt-6-astra; max selects its maximum standard reasoning effort. Responses identify the actual Codex model. See the model and alias reference.

| Codex model | Supported efforts | | --- | --- | | gpt-6-astra, gpt-5.6-sol, gpt-5.6-terra | low, medium, high, xhigh, max, ultra | | gpt-5.6-luna | low, medium, high, xhigh, max | | gpt-5.5, gpt-5.4-mini, gpt-5.3-codex-spark | low, medium, high, xhigh |

Extra high, extra-high, and extra_high normalize to xhigh; names are case-insensitive. Omitting model and effort uses the instance configuration. When only a model is selected, its default is the highest supported effort up to the configured level. An explicitly unsupported effort returns 400. Spark accepts text only; the other six models also accept images.

Request authentication

HTTPS encrypts traffic. HMAC-SHA256 authenticates requests; nonce tracking prevents replay. A public salt or plain MD5 hash is not a replacement for a secret signing key.

Send these headers on every API request, including GET, DELETE, and every upload chunk:

• X-Client-Id: your client identifier.
• X-Request-Timestamp: Unix seconds; five-minute clock tolerance.
• X-Request-Nonce: fresh 16–32 random bytes encoded as lowercase hex.
• X-Content-SHA256: SHA-256 of the exact request body, including multipart boundaries.
• X-Request-Signature: lowercase hex HMAC-SHA256 of the canonical bytes below.

Canonical string, UTF-8, newline separators, no final newline:

codex-hmac-v1
HTTP_METHOD
/exact/path?exact=query
exact Content-Type header, or empty
timestamp
nonce
body_sha256_hex

Use a fresh nonce for retries. Client secrets stay out of request URLs and bodies. If any X-Goog-Upload-* headers are present, append one more canonical line: SHA-256 of those headers sorted by lowercase name, as newline-separated lowercase-name:exact-value pairs. This binds resumable offsets, commands, declared length and MIME type as well as the chunk bytes. The server validates the signed headers before receiving large content and then hashes the incoming stream before any application handler can consume it. Client IDs have independent least-privilege scopes.

Files and cleanup

The configurable file ceiling is 8 GiB. Large uploads stream through temporary storage; model input and context ceilings remain independent. A 5 GiB free-space reserve protects other server services. Increase GATEWAY_MAX_FILE_BYTES only alongside available storage; configure nginx to permit the size. Direct TLS at the origin avoids an intermediary's smaller upload or response-time limits.

Unused files and stored responses expire after 30 minutes; references renew file inactivity time, with a maximum lifetime of 48 hours. Incomplete uploads expire after 15 minutes. Cleanup checks run every minute and preserve active file leases. Completed/failed jobs remove their scratch immediately. Codex authentication, gateway credentials, and pinned transcription weights are persistent and are never part of file cleanup. Transcription containers and temporary audio files are removed after each job.

Development

python3.12 -m venv /path/to/task-scratch/venv
/path/to/task-scratch/venv/bin/pip install -e '.[test]'
/path/to/task-scratch/venv/bin/python -m pytest tests/test_auth.py

See CLAUDE.md for architecture boundaries and focused verification commands. Read deployment, login and monitoring, OpenRouter fallback, SDK integration examples, OpenAPI, and the operation/scope registry.

Upstream references

• Codex app-server
• Codex authentication
• OpenAI upload parts
• Gemini file input methods