Codex Docker Environment Template

A hardened Docker/devcontainer setup for running OpenAI’s Codex CLI with predictable tooling, locked-down permissions, and resource quotas. Drop it into any repository to spin up an isolated workspace that still has everything you need (git, zsh, gh, fzf, delta, etc.) to collaborate with Codex comfortably.

Why this exists

• Keep Codex sessions contained: only the project folder is mounted and Linux capabilities are dropped.
• Provide a consistent toolbox: Node.js 20 base image plus common CLI utilities and Zsh defaults.
• Make auth easy but safe: a loopback-only socat sidecar forwards the Codex port so the CLI can talk to OpenAI without exposing extra surfaces.
• Encourage reproducibility: ship the exact Dockerfile/compose combo you can bring to any project.

What’s included

File	Purpose
Dockerfile.codex	Builds the dev image from node:20, installs CLI tools, configures Zsh, sets up persistent history, and installs @openai/codex.
docker-compose.codex.yaml	Defines the dev workspace container and a proxy service (Alpine socat) that forwards TCP/1455 back to Codex.
api.http	Scratchpad for Codex HTTP requests (handy when testing API calls).

Prerequisites

• Docker Engine 20.10+ and the Docker Compose v2 plugin.
• Access to the OpenAI Codex CLI (login happens from inside the container).
• Optionally, GNU Make or task runners if you want to wrap the compose commands.

Quick start

Clone or copy this template

git clone https://github.com/mkloubert/codex-docker-env codex-env
cd codex-env

Build and start the workspace

docker compose -f docker-compose.codex.yaml up --build -d dev

Attach to the container shell

docker compose -f docker-compose.codex.yaml exec dev zsh

Authenticate Codex

codex login

The CLI will open a device-code flow. Once authenticated you can run codex chat, codex task, etc. inside /workspace. 1.

Stop the stack when finished

docker compose -f docker-compose.codex.yaml down

Using this in your own project

1. Copy Dockerfile.codex and docker-compose.codex.yaml into the root of your repo.
2. Adjust paths under volumes if your project lives somewhere other than ./.
3. (Optional) Create a .env file with TZ, CODEX_CODE_VERSION, or other args you want to pin.
4. Run the same compose commands from within your repo—your source tree will be mounted into /workspace.

Because the compose file only exposes port 1455 internally (via the proxy service) you can safely run multiple projects by giving each stack a distinct project name:

COMPOSE_PROJECT_NAME=myapp-codex docker compose -f docker-compose.codex.yaml up -d dev

Customization hints

• Resource limits: tweak deploy.resources to raise/lower CPU and memory for Codex sessions.
• Network isolation: set network_mode: none in the dev service to go fully offline (Codex CLI features that hit the network will stop working).
• User mapping: uncomment the user: line and pass UID/GID build args so container file ownership matches the host.
• Tooling: extend the apt-get install list or add extra global npm packages after the RUN npm install -g @openai/codex@... line.

Security posture

• cap_drop: [ALL] and security_opt: ["no-new-privileges:true"] prevent accidental privilege escalation.
• Only ./ is mounted, so Codex cannot see files outside your project.
• The proxy binds to 127.0.0.1, keeping the Codex port off your LAN.
• Shell history is stored under /commandhistory inside the container; remove the volume if you prefer stateless sessions.

Troubleshooting

• Landlock/Sandbox errors: If you see error running landlock when running commands outside Docker (for example, in Codex sandbox environments), rerun with elevated permissions or execute from within the container where the filesystem is writable.
• Auth loops: Run codex logout then codex login inside the container to refresh tokens.
• Port conflicts: If 1455 is in use on your host, change the socat TCP-LISTEN port and the codex CLI --host flag accordingly.

License

MIT — see LICENSE for details.