Codex Docker: Run Codex CLI in a Container (2026)

Do not index

There is no official Codex Docker image. To run OpenAI's Codex CLI in Docker, you build a small image yourself: start from node:24-bookworm-slim, install @openai/codex pinned to a release (0.157.0 as of September 25, 2026), run it as a non-root user, and mount a volume at ~/.codex so your login survives restarts. Then let the container do the sandboxing: --dangerously-bypass-approvals-and-sandbox is the flag OpenAI ships for exactly this situation. This guide covers a tested Dockerfile and Compose file, the three ways to sign in from inside a container, why Codex's own sandbox breaks under default Docker, headless CI usage, and the honest math on when an always-on host like Agent37 beats keeping the container on your laptop.

What people mean by Codex Docker (three different things)

Search results for this topic mix up three separate things, so it is worth 60 seconds to pick the right one.

Running the Codex CLI inside a Docker container. That is this guide. You want the agent boxed in so you can grant it full autonomy without giving it your host machine. There is no official image for this; you build one from a ~15 line Dockerfile.

codex-universal. OpenAI publishes ghcr.io/openai/codex-universal, a reference implementation of the base image its cloud environments use (Ubuntu 24.04 with language runtimes selected through CODEX_ENV_* variables). It exists so you can debug your Codex cloud environment setup locally. It does not contain the Codex CLI, it is not meant to run it, and the repo has been quiet since May 2026 though the image is still published. Our Codex cloud post covers that side.

Docker Sandboxes (sbx). Docker's own agent-sandbox product ranks near the top of search results for this topic: sbx run codex ~/my-project launches Codex in a microVM, with credentials held on the host. It is now a standalone CLI: Docker's install docs say you need neither Docker Desktop nor Docker Engine, and it covers macOS (Apple silicon), Windows 11, and Ubuntu 24.04+ (Linux needs KVM); a Rocky Linux 8 rpm exists in the release artifacts, but Docker calls release-artifact distros untested and unsupported. It is the least-effort option for disposable local sessions, and Docker now documents CI use, custom images via its sandbox templates and kits, and experimental cloud sandboxes on Docker-managed pay-as-you-go compute. The plain-Docker route below is what you want for your own servers, full control of the image, and anything always-on.

What you need before you start

ㅤ	Minimum	Recommended
RAM	4 GB (OpenAI's stated floor)	8 GB
CPU	1 vCPU	2 vCPU
Disk	~1 GB for the image	a few GB for repos and caches
Auth	ChatGPT Plus or higher (CLI access starts at Plus since September 2026) or an OpenAI API key

The 4 GB minimum and 8 GB recommendation are OpenAI's own numbers from the install docs; there is no official container-specific sizing.

On the account side: Codex CLI itself is free and open source (Apache-2.0, github.com/openai/codex, latest release 0.157.0 from September 25, 2026; new versions land roughly weekly). Usage is what costs, and the plan story changed in September 2026: Codex in the CLI, IDE extension, and web is now a Plus-and-up benefit ($20/mo; Pro adds 5x limits from $100/mo, and new sign-ups for its 20x tier are currently paused). Free and Go accounts only get Codex in the ChatGPT desktop app, which does not help a container. Local messages draw from a shared five-hour window, and weekly limits may also apply. Or skip plans entirely and pay per token with an API key: since September 22 the models Codex recommends are GPT-6 Sol at $2 input / $10 output per million tokens and GPT-6 Luna at $0.10 / $0.50, half or less of the GPT-5.6 prices they replace, and OpenAI calls the cut permanent. One cost trap for API-key setups: leave the model unset and current builds resolve their default from a catalog that the flagship GPT-6 Astra ($10 / $50) now heads, so pin --model gpt-6-sol or gpt-6-luna in anything automated. Our Codex vs Claude Code comparison has the full cost breakdown.

The Dockerfile

This builds clean and runs codex-cli 0.157.0 (tested September 25, 2026, Docker 29.x):

# Codex CLI in a container: pinned version, non-root user.
FROM node:24-bookworm-slim

ARG CODEX_VERSION=0.157.0

RUN apt-get update \
    && apt-get install -y --no-install-recommends \
        git ca-certificates curl ripgrep \
    && rm -rf /var/lib/apt/lists/* \
    && npm install -g @openai/codex@${CODEX_VERSION}

# The node base image ships a non-root "node" user (uid 1000).
USER node
ENV CODEX_HOME=/home/node/.codex
RUN mkdir -p /home/node/.codex /home/node/workspace
WORKDIR /home/node/workspace

# No default args: plain `codex` opens the interactive TUI.
ENTRYPOINT ["codex"]

What the pieces do:

node:24-bookworm-slim: Codex is a Rust binary, but the npm package is the easiest pinnable install (it only asks for Node 16+). Node 24 is the active LTS line until Node 26 takes over on October 28, 2026. OpenAI now leads with a curl installer script instead of npm; that works in a RUN step too, but npm pins an exact version in one line.

ARG CODEX_VERSION: pin it. Codex ships weekly; an unpinned image that rebuilds differently every Tuesday is how CI breaks on Friday.

USER node: most community images run Codex as root, which litters your bind-mounted project with root-owned files and gives the agent more container privileges than it needs. The stock node user (uid 1000) matches the default first user on most Linux hosts, so file ownership usually just works. If your uid differs, add build args to remap it.

CODEX_HOME: Codex keeps config and credentials under ~/.codex by default; making it explicit gives you one obvious thing to mount.

git: Codex wants to work inside a git repo and will refuse otherwise unless you pass --skip-git-repo-check.

The Compose file

services:
  codex:
    build: .
    stdin_open: true   # the TUI needs an interactive terminal
    tty: true
    volumes:
      - ./:/home/node/workspace        # your project
      - codex-home:/home/node/.codex   # persists login + config
    environment:
      - OPENAI_API_KEY=${OPENAI_API_KEY:-}

volumes:
  codex-home:

Daily use is one command from your project directory: docker compose run --rm codex. The container is disposable; the named codex-home volume is not, which is exactly the split you want. Your login token and config.toml persist, everything else resets.

Signing in from inside a container

This is the part most guides skip, because codex login wants to open a browser and listen on localhost:1455, and a container has neither. You have three sanctioned options, per OpenAI's auth docs:

Device code auth (best for containers). Run docker compose run --rm codex login --device-auth. Codex prints a code, you approve it from any browser on any machine, done. It is labeled beta and has to be enabled in your ChatGPT security settings first, but it works headless, which is the whole point.

Copy your auth.json. Credentials live in a plaintext file at ~/.codex/auth.json. OpenAI's docs explicitly show copying it from a machine where you have logged in into a container. Drop it into the codex-home volume and you are signed in. Treat that file like a password.

API key. The Compose file already passes OPENAI_API_KEY into the container, so run docker compose run --rm --entrypoint sh codex -c 'printenv OPENAI_API_KEY | codex login --with-api-key'. For one-shot non-interactive runs, just set CODEX_API_KEY for codex exec. You pay per token instead of using plan credits.

Because auth state sits in the mounted volume, you log in once, not on every run.

YOLO mode without giving Codex your machine

The reason to containerize Codex at all: you want to stop approving every command. Understand the two sandbox layers first.

Codex ships its own sandbox (Seatbelt on macOS, bubblewrap on Linux, the default since March 2026). Inside a default Docker container, that Linux sandbox does not work: bubblewrap needs to create unprivileged user namespaces, and Docker's default seccomp and AppArmor profiles block exactly that. You will see errors like bwrap: setting up uid map: Permission denied.

You have two honest choices:

Let the container be the sandbox (simpler, what most people want). Run codex --dangerously-bypass-approvals-and-sandbox (alias --yolo). The flag's own help text says it is "intended solely for running in environments that are externally sandboxed", which is precisely what your container is. Codex gets free rein inside the box; the box is the boundary.

Keep Codex's inner sandbox working (defense in depth). OpenAI used to ship a secure container profile in the repo (.devcontainer/Dockerfile.secure) that installed bubblewrap setuid and relaxed Docker's seccomp/AppArmor so the inner sandbox still functioned. It deleted the entire .devcontainer on September 8, 2026, three weeks after documenting that the profile's firewall could be bypassed through DNS. The recipe still works if you maintain it yourself, but with OpenAI out, the container-as-the-sandbox route above is the sane default.

One thing neither layer gives you for free: network egress control. A default container can reach the whole internet, which matters if Codex reads untrusted code and gets prompt-injected. OpenAI's removed secure profile bundled an allowlist firewall (its own docs noted it never filtered DNS); our claude-code-docker repo shows a default-deny egress pattern for Claude Code, and the approach ports to this image directly.

Headless runs and CI

Interactive TUI is for your laptop. Everywhere else, use codex exec:

docker compose run --rm codex exec \
  --dangerously-bypass-approvals-and-sandbox \
  "run the test suite and fix any failures"

codex exec streams progress to stderr and prints only the final message to stdout, so it pipes cleanly. Useful flags: --json for JSONL events, -o file to capture the last message, --skip-git-repo-check for bare directories, --ephemeral to keep a one-shot run from persisting session files, and codex exec resume --last to continue the previous session. In CI, pass CODEX_API_KEY as a secret and set it only on the step that needs it; OpenAI now warns against job-wide keys in workflows that run repo-controlled code. Pin --model too, so a catalog change never silently upgrades you to flagship pricing. One trap from older guides: --full-auto is gone, and current releases reject it with a hard error.

Troubleshooting

Symptom	Cause	Fix
bwrap: setting up uid map: Permission denied (or a failed RTM_NEWADDR loopback error)	Codex's sandbox needs user namespaces; default Docker blocks them	Use --dangerously-bypass-approvals-and-sandbox, or self-maintain the secure profile OpenAI removed from its repo
Login hangs opening a browser	OAuth callback wants `localhost:1455`	`codex login --device-auth`, or copy `~/.codex/auth.json` in
Root-owned files in your repo	Image runs Codex as root	Use the non-root Dockerfile above; remap uid if yours is not 1000
`codex` says it needs a git repo	Bind-mounted dir has no `.git`	`git init` or `--skip-git-repo-check`
Codex can't run `docker` commands	The daemon is outside the container	Mount `/var/run/docker.sock` and install the docker CLI, knowing that this hands the agent host-level Docker control
codex exec exits 0 but did nothing	In hardened containers a failed inner-sandbox setup can swallow the run silently (issue #46246)	Run with the bypass flag inside containers; in CI, capture the --json event stream so an empty run is visible

Running it always-on instead of on your laptop

Everything above assumes the container dies when your laptop lid closes. A coding agent gets more useful when it does not: overnight refactors, scheduled dependency bumps, a box you can hand tasks from your phone.

The DIY route is a VPS with 4 GB of RAM running this exact image under docker compose with a restart policy. Price that honestly for September 2026: Hetzner's famous cheap CX line (and the Arm CAX escape hatch) is marked unavailable, so the realistic floor is EUR 19.49/mo (about $23) for a Hetzner CPX22 in EU locations or $24/mo for a 4 GB DigitalOcean droplet, and Hetzner's US locations start at $37.49. Netcup still sells a EUR 8.26/mo 4 GB box if you accept a 12-month commitment. That works, and if you enjoy patching a server, it is a fine path. The trade is that you own updates, disk, backups, and the 2 a.m. restart.

We sell the other path, so here is the honest version. Agent37 Cloud now has a prebuilt agent37-codex template: one POST /v1/instances call brings up an always-on instance with the Codex CLI preinstalled, and you connect your own OpenAI account by opening the instance's web terminal and running codex login --device-auth, or by passing OPENAI_API_KEY as instance env (OPENAI_BASE_URL works too, for pointing Codex at a compatible endpoint). The image is lean, no browser or desktop, and your credentials go from your instance to OpenAI directly; we never see them. Prefer this exact Dockerfile instead? The custom-image lane still exists: register any public image with POST /v1/templates, or build on ghcr.io/agent37-platform/codex-base. Pricing is metered per minute from a prepaid balance at $0.80 per vCPU, $0.70 per GB of RAM, and $0.09 per GB of disk per month: the 2 vCPU / 4 GB floor lands at $4.76/mo always-on, and an auto-sleeping instance pays for its disk alone (around $0.36/mo) until a request wakes it. Isolation is gVisor, on the same fleet that runs roughly 1,000 live instances. Add a card and you get a $1 starter credit (nothing is charged), about a week of the cheapest instance. Fair warning on the downside: at these prices, low-end support is Discord and community with a bookable founder call, not an SLA.

FAQ

Is there an official Codex Docker image?

No. OpenAI publishes no Docker image containing the Codex CLI; its registry holds codex-universal (the cloud base image), a tunnel client, and codex-security, OpenAI's Codex Security CLI for finding and fixing vulnerabilities (a different product in the Codex line, not an image of the coding CLI). You build your own from the Dockerfile above, or use a community image if you accept root-user tradeoffs.

Does Codex's own sandbox work inside Docker?

Not under default settings. Bubblewrap needs unprivileged user namespaces, which Docker's stock seccomp/AppArmor profiles block. Either treat the container as the sandbox with --dangerously-bypass-approvals-and-sandbox, or self-maintain the secure profile OpenAI removed from its repo in September 2026 (setuid bubblewrap plus relaxed seccomp/AppArmor).

Do I need a ChatGPT subscription or an API key?

Either works, but since September 2026 the CLI needs Plus ($20/mo) or higher; Free and Go only include Codex in the ChatGPT desktop app. Plan usage draws from shared five-hour and weekly limits. An API key meters per token instead and is the better fit for CI; pin --model gpt-6-sol or gpt-6-luna so you are not paying flagship Astra rates by default.

What is codex-universal actually for?

Reproducing OpenAI's Codex cloud environment locally so you can debug environment setup for cloud tasks. It is not a CLI runner, and while the image is still published, the repo has been quiet since May 2026. See our Codex cloud guide for how those per-task containers behave.

What about Docker Sandboxes (sbx)?

Docker's sbx run codex gives you a disposable microVM with credentials kept on the host, and it runs Codex with the bypass flag internally too. It is now a standalone CLI, no Docker Desktop or Docker Engine required, on macOS (Apple silicon), Windows 11, and Ubuntu 24.04+. Great for local one-offs, and Docker now also documents CI use (headless PAT login plus sbx exec in runners), custom images built on its sandbox templates, and an experimental cloud tier. Plain Docker still wins for your own always-on servers.

How much RAM should the container get?

OpenAI's floor is 4 GB with 8 GB recommended. Cap the container (mem_limit) below your host's total so a runaway build does not take the box down. On a VPS, 4 GB shapes are the sweet spot; our Hermes Docker guide walks the same sizing logic for a different agent.

What if I do not want to run Docker at all?

Then managed hosting is the answer to a different question, and we are biased here since we sell it. If you specifically want Codex, the agent37-codex template on Agent37 Cloud is the supported path from $4.76/mo. Try the Dockerfile locally for a week first; if you find yourself wishing it never turned off, that is the signal.

Codex Docker: Run OpenAI's Codex CLI in a Container (2026 Guide)