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:22-bookworm-slim, install @openai/codex pinned to a release, 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 copy 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, and it is not meant to run it. Our Codex cloud post covers that side.

Docker Sandboxes (sbx). Docker's own agent-sandbox product now sits at the top of this SERP: sbx run codex ~/my-project launches Codex in a microVM, with credentials held on the host. It is the least-effort option if you run Docker Desktop and want disposable sessions. The plain-Docker route below is what you want for servers, CI, custom toolchains, and anything long-running.

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 Free/Go/Plus/Pro account 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.149.0 from August 20, 2026). Usage is what costs. Every ChatGPT plan includes some Codex usage, from Free ($0) through Go ($8/mo), Plus ($20/mo), and Pro ($100/mo for 5x, $200/mo for 20x); 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: the GPT-5.6 models Codex recommends run from $0.20 input / $1.20 output per million tokens (Luna) up to $4 / $20 (Sol) as of late August 2026. Our Codex vs Claude Code comparison has the full cost breakdown.

The Dockerfile

This builds clean and runs codex-cli 0.149.0 (tested August 23, 2026, Docker 29.x):

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

ARG CODEX_VERSION=0.149.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:22-bookworm-slim: Codex is a Rust binary, but the npm package is the easiest pinnable install, and Node 22 matches the base OpenAI uses in its own container profile for Codex.

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 but 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: operation not permitted.

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's repo ships a customer-oriented container profile (.devcontainer/Dockerfile.secure) that installs bubblewrap setuid and relaxes Docker's seccomp/AppArmor for the container so the inner sandbox still functions. More moving parts, two layers of isolation.

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 secure profile bundles an allowlist firewall, and our claude-code-docker repo shows the same default-deny egress pattern for Claude Code; 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, and codex exec resume --last to continue the previous session. In CI, pass CODEX_API_KEY as a secret instead of baking credentials into the image. One trap from older guides: --full-auto is gone, and 0.149.0 rejects it with a hard error; the bypass flag or --sandbox settings are the current way.

Troubleshooting

Symptom	Cause	Fix
`bwrap: ... operation not permitted`	Codex's sandbox needs user namespaces; default Docker blocks them	Use `--dangerously-bypass-approvals-and-sandbox`, or relax seccomp/AppArmor like OpenAI's secure profile
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

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: roughly $7/mo on Hetzner (CX23) to $18/mo on DigitalOcean at today's prices. That works, and if you enjoy patching a server, it is the cheapest 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 has no prebuilt Codex template, and we will not pretend otherwise. What it has is a custom-image lane that is fully supported today: push this Dockerfile's image to a public registry (give it a keep-alive command like sleep infinity), register it with POST /v1/templates, and provision an always-on instance with POST /v1/instances. Pricing is metered per minute from a prepaid balance: from $1.99/mo shared or $4.94/mo dedicated for a 2 vCPU / 4 GB instance, extra disk at $0.09/GB/mo, gVisor isolation, on the same fleet that runs roughly 1,000 live instances. Your OpenAI credentials live on your instance and go from there to OpenAI directly; we never need them. New workspaces get a $1 starter credit, about a week of the cheapest instance, no card required. Fair warning on the downside: at these prices support is an AI bot and community, not a human on call.

FAQ

Is there an official Codex Docker image?

No. OpenAI publishes no Docker image containing the Codex CLI. codex-universal is the cloud-environment base image and does not include the 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 replicate OpenAI's secure devcontainer profile to run bubblewrap inside.

Do I need a ChatGPT subscription or an API key?

Either works. Plans from Free to Pro include Codex usage under shared five-hour and weekly limits; Go at $8/mo is the cheapest paid tier. An API key meters per token instead and is the better fit for CI.

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. 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. Great for local one-offs on Docker Desktop; not the tool for servers, CI pipelines, or custom images.

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 custom-image route on Agent37 Cloud is the supported path from $1.99/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)