Codex Docker Container Setup

Why Containerize Codex?

Containers solve the "works on my machine" problem definitively. A Dockerized Codex environment is byte-for-byte identical across every developer laptop, CI runner, and production server.

Development teams lose an extraordinary amount of time to environment discrepancies. One developer is on macOS with Homebrew-installed Codex; another is on Ubuntu with the npm version; the CI runner runs a stripped-down Linux image with pip. Version skew, missing dependencies, and platform-specific behavior produce bugs that only appear in one environment and are nearly impossible to reproduce elsewhere. Docker eliminates this entire category of problem. The Codex Docker image bundles a specific CLI version with all its dependencies — the correct Node.js runtime, the correct system libraries, the correct shell configuration. Every container created from that image runs the exact same binary in the exact same environment. When a developer reports a Codex issue, the support team reproduces it in the same Docker image and eliminates environment variables from the investigation immediately.

Containers also simplify onboarding. A new developer clones the repository, runs docker compose up, and has Codex available in their terminal and IDE with project-specific configuration applied automatically. There is no "install these five things in this order" checklist. The compose file encodes the complete development environment, and it works on macOS, Windows, and Linux without modification. For organizations that use dev containers (VS Code Dev Containers, GitHub Codespaces, JetBrains Gateway), the Codex image integrates as a dev container feature — add one line to your devcontainer.json and Codex is available inside the containerized development environment.

Available Codex Docker Images

Codex publishes four Docker images on Docker Hub, each optimized for a different use case. Choose the one that matches your workload.

All images are based on Alpine Linux 3.20 for minimal attack surface. The codex/cli image is the smallest — it contains only the CLI binary and shell completion scripts. The codex/ci image adds utilities commonly needed in CI pipelines: git for repository operations, curl and jq for API interactions, and ca-certificates for TLS verification. The codex/full image includes the TypeScript, Python, Go, and Rust SDKs pre-installed alongside their respective runtimes — useful for dev containers where developers need both the CLI and programmatic API access. The codex/server image packages the complete on-premise Codex platform and requires additional configuration documented in the Enterprise deployment guide. Images are rebuilt weekly with security patch updates and tagged with both the semantic version and latest. Digest-pinned tags (codex/cli@sha256:...) are available for environments that require immutable references.

Docker Compose Configuration

A compose file gives every developer an identical Codex environment. Commit it to your repository and onboarding becomes a single command.

Create a docker-compose.yml in your project root. The compose file defines a Codex service that mounts your source code, configuration, and a persistent volume for the index database. Environment variables for the API token and project settings are read from a .env file that is never committed. The container runs the Codex CLI in watch mode by default — it monitors your source directory for changes and updates the semantic index in real time. Developers interact with Codex through docker compose exec codex codex generate "description" or by configuring their IDE plugin to communicate with the containerized CLI. The compose file can also define a CI profile that overrides the entrypoint to run a one-shot review or generation and exit, making the same compose file usable for both local development and CI pipelines. Multi-service projects can add Codex as a sidecar container that shares a network with the application containers, enabling Codex to read service configurations and generate contextually aware code for the entire system.

Kubernetes Deployment

Codex provides official Helm charts for Kubernetes deployment. Deploy the on-premise server, run batch generation jobs, or host CI review workers on your cluster.

The Helm chart is available at https://charts.codex.gr.com. Add the repository and install with default values for a development deployment, or customize the values file for production. The chart configures a Deployment with configurable replica count, resource requests and limits, liveness and readiness probes, and a HorizontalPodAutoscaler that scales on CPU and memory utilization. Persistent storage is provided via a PersistentVolumeClaim for the index database — use your cluster's default StorageClass or specify a custom one for high-IOPS workloads. The chart also deploys a Service and, optionally, an Ingress for API access. Prometheus metrics are exposed on port 9090 and include request latency, generation counts, review scores, and error rates — the chart includes a ServiceMonitor for automatic Prometheus Operator discovery. For batch workloads like scheduled full-repository reviews, use the chart's Job template mode, which creates a Kubernetes Job that runs to completion and records the result as a ConfigMap for downstream inspection.

For teams using Kustomize instead of Helm, Codex provides Kustomize overlays in the GitHub repository under deploy/kustomize/. The overlays configure the same resources as the Helm chart but follow the Kustomize patching model. Both deployment methods produce identical Kubernetes resources — choose the one that matches your organization's GitOps workflow.

Environment Variables and Configuration

The Docker images are configured entirely through environment variables. No interactive prompts, no mounted terminal required — perfect for automated environments.

The required variable is CODEX_TOKEN. Without it, the container starts but refuses all operations. Optional variables include CODEX_PROJECT_DIR (defaults to /workspace), CODEX_CONFIG_PATH (defaults to /workspace/.codex/config.toml), CODEX_LOG_LEVEL (debug, info, warn, error; defaults to info), and CODEX_TELEMETRY (on or off; defaults to off in containers). Network configuration uses the standard proxy variables: HTTP_PROXY, HTTPS_PROXY, and NO_PROXY. The container runs as a non-root user (uid=1000, gid=1000) named codex. If you mount host directories, ensure the mounted files are readable by uid 1000 — the container startup script prints a clear error if permissions prevent access. The codex/server image accepts additional variables for database connection strings, TLS certificate paths, and SMTP configuration for email notifications; these are documented in the Enterprise deployment guide.

Volume Mounts and Data Persistence

Three mount points define the container's data lifecycle. Mount them correctly and your Codex state survives container recreation, upgrades, and host migrations.

The source code mount (/workspace) should be a bind mount to your project directory. The container reads code from here and writes generated files back — it never modifies existing source files except when explicitly asked with the --write flag. The config mount (/home/codex/.codex) should be a named volume or a bind mount to a persistent directory. This is where the semantic index database (index.db), configuration file (config.toml), generation history (history.db), and review cache live. If this volume is ephemeral, Codex re-indexes your entire codebase on every container start — functional but wasteful. The cache mount (/home/codex/.cache) stores downloaded model artifacts and language server binaries. It is safe to make ephemeral, but persistent caching avoids re-downloading model updates on every start. For Docker Compose users, the compose file should define the config and cache volumes as named volumes with the local driver. For Kubernetes, the PersistentVolumeClaim should use the cluster's default StorageClass with at least 1 Gi of capacity for typical projects and 5 Gi for monorepos.

Multi-Stage Dockerfiles for Custom Environments

Build your own Codex Docker image on top of the official base to pre-configure settings, pre-install tools, and pre-index your codebase.

A common pattern for teams that want a fully self-contained Codex environment is to create a custom Dockerfile that extends codex/full. The Dockerfile copies the project's .codex/config.toml into the image, installs additional system packages needed by the project's build toolchain, and runs codex index --build during the build phase to pre-populate the semantic index. The resulting image starts with Codex already understanding the codebase — no startup delay, no indexing wait. This pattern is especially useful for ephemeral CI runners where every second of setup time counts against the build budget. The Dockerfile can also set environment variables with defaults that individual developers can override at runtime. Multi-stage builds keep the final image small: use the first stage to build the index and install tools, then copy only the artifacts into a clean codex/cli base in the final stage. The resulting image is often under 80 MB for a typical project with pre-built index, which is competitive with the time cost of indexing at runtime.

Ingrid L. Sørensen, Senior Backend Architect at Polaris Networks, described their Docker-first approach: "Every Polaris developer gets a Docker Compose environment that includes Codex alongside our application services. The compose file pins the Codex image version, so the entire team upgrades simultaneously. Our CI pipeline uses the same image — the exact same binary that passed review on a developer's machine is the binary that runs in CI. We stopped having Codex-related environment issues the day we containerized it. The Helm chart deploys a Codex review worker as a Kubernetes CronJob that scans every service every Sunday morning; the report lands in our Slack #eng-announce channel before anyone starts their workday."