Codex sandbox: modes, --yolo, Docker and cloud

A Codex sandbox limits where commands can write and whether they can reach the network. For local work, start with workspace-write; use --yolo only inside an external sandbox, since it turns off both Codex's sandbox and approval prompts.

We tested Codex CLI 0.162.1 on macOS and in Docker, plus a Codex task in Lizard Sandboxes. This guide covers those results, the settings that matter, and how to choose a setup.

The examples use those tested versions. Our source check on 21 October 2026 listed 0.163.0 as the newest stable release; check your installed version before applying settings from another release. See the release list.

What does the built-in Codex sandbox protect?

Codex applies operating system limits to spawned commands, including test runners, Git and package managers. Those limits control file writes and network access. MCP servers, connectors and browser tools use their own controls; the command sandbox does not contain every tool you connect. See OpenAI's sandbox scope and tool controls.

In our macOS workspace-write probes, a project write worked, a home-directory write failed, and .git/ stayed read-only. Writes to /tmp and $TMPDIR worked. Reading ~/.zshrc also worked: workspace-write does not confine reads to your project.

The docs also protect existing .codex, .agents and .aws directories within writable roots. Protection extends through their contents, and .git protection includes a linked gitdir. We probed .git; the other protected paths come from OpenAI's documentation.

Enable Codex sandbox mode

Start an interactive session in your project with:

codex --sandbox workspace-write --ask-for-approval on-request

This selects Auto: workspace edits and routine commands can run; broader access needs approval. Interactive Codex recommends Auto for version-controlled folders and read-only elsewhere. It may start read-only until you trust the folder. By contrast, codex exec runs read-only by default. To allow edits:

codex exec --sandbox workspace-write "<task>"

Replace <task> with your request. See the interactive defaults and exec permissions; our codex exec guide covers scripted tasks.

On macOS, Codex uses Seatbelt. On Linux and WSL2, it uses bubblewrap for filesystem isolation and seccomp for syscall filtering. Bubblewrap became the default in 0.115.0. On Debian or Ubuntu, install it:

sudo apt install bubblewrap

Without bwrap on PATH, Codex can use its bundled helper, which needs unprivileged user namespaces. Ubuntu 24.04 may also need the bwrap-userns-restrict AppArmor profile. Follow the prerequisites.

Native Windows supports MXC, the recommended choice on supported Windows 11 builds: 24H2 build 26100.9278 or 25H2 build 26200.9278 and later. Legacy fallbacks are elevated and unelevated; WSL2 uses Linux sandboxing. See the Windows requirements.

Set network and write access

Network access starts off in workspace-write. To enable it in your Codex config:

[sandbox_workspace_write]
network_access = true

The one-run override is -c sandbox_workspace_write.network_access=true. Our network probe changed from a DNS failure to HTTP 200 with that setting. It enables outbound access; domain rules need the separate network proxy. See network settings.

These are command-network controls. Codex's model and authentication requests use a separate path, so a blocked curl request does not mean the CLI cannot reach its model. The proxy also does not filter MCP connections or browser traffic. See traffic outside the command proxy.

For another writable folder, use --add-dir with the needed path:

codex --add-dir <DIR>

Replace <DIR> with that folder. OpenAI recommends adding a directory when that is all the task needs.

Check the boundary before a long run

From the project folder, we ran these four probes:

codex sandbox -c sandbox_mode="workspace-write" -- sh -c 'touch ./inside && echo inside-ok || echo inside-blocked'
codex sandbox -c sandbox_mode="workspace-write" -- sh -c 'touch ~/codex-probe-outside && echo outside-ok || echo outside-blocked'
codex sandbox -c sandbox_mode="workspace-write" -- sh -c 'curl -sS -m 5 -o /dev/null -w "%{http_code}\n" https://example.com || echo net-blocked'
codex sandbox -c sandbox_mode="workspace-write" -c sandbox_workspace_write.network_access=true -- sh -c 'curl -sS -m 5 -o /dev/null -w "%{http_code}\n" https://example.com || echo net-blocked'

In that order, we saw inside-ok, outside-blocked, net-blocked (after curl: (6) Could not resolve host: example.com), and 200.

Some docs print codex sandbox macos|linux. Version 0.162.1 does not accept those as OS subcommands: the host selects the backend. Use the flat form above. The release source confirms it.

Also check through the agent's shell tool. Our agent-level invocation was:

codex exec -s workspace-write -c approval_policy="never" \
  --ephemeral --json \
  "Run exactly these three shell commands, one at a time, with your shell tool, and report the exit code and output of each. Do not retry, do not use workarounds, do not ask for approval: 1) touch ./agent-inside  2) touch ~/codex-agent-probe  3) curl -sS -m 5 -o /dev/null -w '%{http_code}' https://example.com"

The prompt ran these three commands:

touch ./agent-inside
touch ~/codex-agent-probe
curl -sS -m 5 -o /dev/null -w '%{http_code}' https://example.com

In our test, the project write returned exit 0. The home write failed with Operation not permitted, and curl returned exit 6, Could not resolve host. No home file appeared. Running these commands in a separate, unsandboxed terminal would not check the agent's limits.

Sandbox modes and approval policies

Sandbox mode sets command limits. Approval policy decides when Codex may ask to go beyond them.

In 0.162.1, the interactive approval flag accepts on-request and never. The first asks when broader access is needed; the second prevents prompts while keeping the chosen sandbox limits. Config also supports a granular policy table. codex exec defaults to never and does not accept the interactive -a flag. See approval options and the exec default.

Older examples need care: untrusted retired in 0.149.0, on-failure is deprecated, and --full-auto left codex exec in 0.147.0. Our 0.162.1 run rejected --full-auto. Use --sandbox workspace-write for exec tasks that need edits.

What does Codex --yolo mode do?

--yolo aliases --dangerously-bypass-approvals-and-sandbox. It disables both controls, with the effect of danger-full-access plus approval policy never. OpenAI says to use it only in an externally sandboxed environment. See the flag warning.

We repeated the agent check with:

codex exec --yolo \
  --ephemeral --json \
  "Run exactly these two shell commands, one at a time, with your shell tool, and report the exit code and output of each. Do not retry and do not run anything else: 1) touch ~/codex-agent-probe  2) curl -sS -m 5 -o /dev/null -w '%{http_code}' https://example.com"

The two commands were the home-directory write and curl request above. This time the file appeared in our home directory and the request returned HTTP 200. We removed the probe file afterward. Codex yolo mode grants access beyond the project.

Lizard and Docker Sandboxes both start Codex with the long bypass flag inside a microVM. That matches the intended use: the VM supplies the outer boundary. It does not make files inside that VM safe from the agent. Docker Sandboxes documents its default Codex command; we observed Lizard's command during our test.

Run Codex in Docker

We tested this Dockerfile:

FROM node:22-bookworm-slim
RUN apt-get update && apt-get install -y --no-install-recommends git python3 ca-certificates curl \
 && rm -rf /var/lib/apt/lists/*
RUN npm install -g @openai/codex@0.162.1
WORKDIR /workspace

Build it as codex-sandbox-test. Our project lived in the local app folder. CODEX_DIR pointed to a separate, existing folder holding a copy of our ChatGPT login. We ran:

docker run --rm \
  -v "$PWD/app:/workspace/app" \
  -v "$CODEX_DIR:/codex-home" \
  -e CODEX_HOME=/codex-home \
  -w /workspace/app \
  codex-sandbox-test codex exec -s workspace-write --ephemeral \
  "Run python3 -m unittest. Fix the failing test with the smallest reasonable change to the code under test, not the test. Run the tests again and report what changed."

Our fixture's add(a, b) subtracted its inputs. Codex changed return a - b to return a + b; its test run and an independent host test run passed. The writable project mount let those edits reach the host.

The Linux sandbox also worked in this default Docker Desktop container without extra capabilities or an installed bubblewrap package. Codex's bundled helper allowed project writes, blocked a write to /root with Read-only file system, and blocked network access.

That result does not cover every host. OpenAI warns that Docker settings can block the namespaces, setuid bubblewrap or seccomp operations Codex needs. If the inner sandbox cannot run, configure the container as the boundary, then use:

codex --sandbox danger-full-access

Check mounts, privileges and network policy first. OpenAI's container guidance warns that a malicious project can send out anything available inside a devcontainer, including Codex credentials.

Authenticate inside the container

For automation, CODEX_API_KEY supplies a key to non-interactive Codex processes. Limit it to the run that needs it. To save an API-key login from an existing environment variable:

printenv OPENAI_API_KEY | codex login --with-api-key

For device-code login:

codex login --device-auth

Device login must be enabled in your account or workspace settings. Another option is copying auth.json from a signed-in machine, as our test did. Treat auth.json as a password: it holds access tokens. A keyring-backed login may not leave a usable file to copy. See authentication and CODEX_API_KEY.

Docker containers and Docker Sandboxes differ

Docker Sandboxes uses the separate sbx CLI:

sbx run codex ~/my-project

Each sandbox has its own Linux kernel and private Docker Engine. A host proxy keeps model credentials outside the VM and adds them to outbound requests. Network rules deny traffic unless allowed; first-run presets are Open, Balanced and Locked Down. Balanced allows common development sites; Locked Down needs an explicit model-provider rule. See isolation, credential handling and presets.

Local requirements are macOS Sonoma 14+ on Apple silicon; Windows 11 on Intel/AMD with Windows Hypervisor Platform; or Ubuntu 24.04+ on x86-64/arm64 with KVM and membership in the kvm group. Docker Desktop is not required. Running sbx local sandboxes inside a VM requires nested virtualization. Check the install guide.

We did not test Docker Sandboxes. Its default bypass flag leaves mounted project files writable, including Git hooks; review them after a run.

When a cloud sandbox helps

Remote compute helps when a task must continue after your laptop disconnects or when several agents need separate workspaces. Share only the code and credentials each task needs.

Codex Cloud's current docs describe a VM per task. An environment-level internet toggle offers package-manager and domain allowlists or unrestricted access. Environment variables go directly to programs; network secrets use placeholders that a proxy replaces for allowed HTTPS destinations on port 443. Cloud features require a supported ChatGPT plan: Plus, Pro, Business or Enterprise. API-key auth does not include them. We did not test Codex Cloud. See cloud environments, plans and our Codex Cloud guide.

Lizard Sandboxes runs tasks in Firecracker microVMs, each with its own kernel. We sell Lizard Sandboxes. We recommend them when you need remote workspaces you can create, run and pause through a CLI; start with Codex's built-in sandbox for local work.

Run Codex in Lizard Sandboxes

Install Lizard CLI, sign in and choose a project. Connect a ChatGPT subscription:

lizard agents login chatgpt

Or register an OpenAI API key:

lizard agents add openai

Check the connection:

lizard agents status

Our test used an already-connected ChatGPT subscription; we did not repeat sign-in.

Create and copy the project

Replace the project placeholder:

lizard sandbox create --project YOUR_PROJECT_ID --template codex --size small --timeout 3600000 --json

Set SB to the returned sandbox ID and BUNDLE_DIR to an existing local temporary folder. The timeout gives this workspace one hour. The default lifetime is five minutes; commands do not extend it.

From your local repository:

git bundle create "$BUNDLE_DIR/app.bundle" HEAD
lizard sandbox files put "$SB" "$BUNDLE_DIR/app.bundle" /workspace/app.bundle
lizard sandbox exec "$SB" -- git clone /workspace/app.bundle /workspace/app

The bundle carries committed history, including any committed secrets, and excludes uncommitted files. Review what you send.

Run the task

lizard sandbox prompt "$SB" --agent codex --cwd /workspace/app "Run the tests. Fix one failing test with the smallest reasonable change. Report what changed and which tests passed."

Keep --agent codex explicit. During our run, the process list showed:

codex exec --json --skip-git-repo-check --dangerously-bypass-approvals-and-sandbox -C /workspace/app "<prompt>"

Codex's own sandbox and approvals were off; the Firecracker microVM supplied isolation. Code inside can access credentials available to the process. Keep their scope narrow. The VM does not hide those credentials from the agent.

Review, download and pause

Review the diff, rerun your project's tests and save the files you need before the final pause command:

lizard sandbox exec "$SB" -- git -C /workspace/app status --short
lizard sandbox exec "$SB" -- git -C /workspace/app diff
lizard sandbox files get "$SB" /workspace/app/calc.py ./calc.py.review
lizard sandbox pause "$SB"

Our fixture used calc.py; choose your changed file when repeating the workflow. Codex fixed the subtraction bug, our separate unittest run printed OK, and the downloaded file matched. We confirmed status paused.

Save results before expiry. Successful pause stops compute billing; Persistent Volumes storage costs remain separate. Use the quickstart and sandbox CLI reference for lifecycle details.

What does the cloud workspace cost?

Lizard compute rates on 21 October 2026:

Compute bills per second while running, including idle time. Successful pause stops compute charges; Persistent Volumes storage bills separately.

Lizard Pro costs $19 a month, taxes included, with $19 of usage included. Extra usage is pay as you go. New accounts get a seven-day trial with $5 of usage; a card is required. ChatGPT or OpenAI API charges are separate. Check pricing before a run.

Common setup problems

What we tested

On 21 October 2026, we tested Codex CLI 0.162.1 from npm on macOS 26.6.2, Apple silicon (arm64), in a fresh Git repository under the home directory. We checked sandbox commands and agent shell calls with ChatGPT login, including the bypass comparison.

Docker tests used Docker Desktop, Docker Engine 28.1.1, arm64 and LinuxKit kernel 6.10. We checked sandbox limits and a Python test fix, then reran the test on the host.

Lizard tests used Lizard CLI 4.0.65. The codex template shipped Codex CLI 0.159.2, Node.js 22.23.2, Python 3.11.2 and git 2.39.5. We covered bundle upload, cloning, the task, separate tests, diff review, download and pause.

We did not test Docker Sandboxes, Codex Cloud, native Windows/WSL2, OpenAI's run_in_container.sh, or fresh account enrollment. These checks cover the recorded setups, not a security audit.

Which setup should you choose?

Use workspace-write for local work with known files and tools. Choose Docker for a repeatable runtime, and test whether Codex's inner sandbox works there. Consider Docker Sandboxes for local microVM isolation and host-held credentials, or Codex Cloud for tasks within ChatGPT.

Choose Lizard Sandboxes when you need remote workspaces through Lizard CLI. Start with one small test fix, review the diff, download the result and pause the workspace.