Open main menu

Codex Sandbox, Explained: Modes, Limits, and the Always-On Option (2026)

The Codex sandbox is an OS-level cage around every command OpenAI's coding agent runs. Here is what each mode actually blocks, what slips through anyway, and the honest escalation path when workspace-write is not enough.

VishnuVishnu

•

Published on

•

Codex Sandbox, Explained: Modes, Limits, and the Always-On Option (2026)

Table of Contents

Do not index
The Codex sandbox is the OS-level boundary OpenAI's coding agent puts around every shell command it runs: Seatbelt on macOS, bubblewrap plus seccomp on Linux, and a native MXC sandbox on recent Windows 11 builds. By default the agent can write only inside your workspace and has no network access at all. That design is why Codex feels safe, and also why it stalls builds, blocks npm installs, and interrupts you mid-task. This guide covers the three sandbox modes, what they do not protect, the failures people actually hit, and when the honest answer is a container, a VM, or a hosted sandbox like Agent37.

What the Codex sandbox actually is

Two different things get called a Codex sandbox, and mixing them up causes most of the confusion.
The first is the local sandbox inside Codex CLI and the IDE extension. Every model-generated shell command runs under an OS-enforced policy that controls where it can write and whether it can reach the network. You pick the policy with the --sandbox flag or sandbox_mode in ~/.codex/config.toml.
The second is Codex cloud, where the sandbox is the machine itself. Each cloud task runs in its own VM: 2 vCPUs with 8 GiB of memory on Plus and Edu Plus, 4 vCPUs with 16 GiB on Pro, Business, Edu, Edu Pro, and Enterprise plans (Enterprise can request larger custom VMs). A task's saved VM state stays recoverable for up to seven days after your last turn. We broke down the full hosted product in our Codex cloud guide.
The local sandbox is the one people fight with daily, so that is where this guide spends most of its time.

The three Codex sandbox modes

The official sandboxing docs define three modes:
  • read-only. The agent can inspect files but cannot edit anything or run state-changing commands without approval. This is the default for codex exec and for folders that are not version-controlled.
  • workspace-write. The agent can read files, edit inside the workspace, and run routine commands there. Version-controlled folders get the Auto preset recommended at launch, which is workspace-write plus on-request approvals (depending on setup, Codex may start in read-only until you explicitly trust the working directory). The workspace means your current directory plus temp directories like /tmp.
  • danger-full-access. No filesystem or network boundary at all. The docs say to use it only when you want the agent acting with full access.
Approvals are the second dial, and they changed in late 2026. Two policies survive: on-request (the agent asks before crossing the boundary) and never. If your config still says approval_policy = "untrusted", current builds refuse to start; that policy was retired, and on-failure is deprecated. There is also a new middle setting, --approve-for-me (alias --not-so-yolo), which routes approval prompts through an automatic reviewer instead of you.
And yes, --yolo is real. It is the short alias for --dangerously-bypass-approvals-and-sandbox, which turns everything off. The flags documentation says to avoid it unless you are inside a dedicated sandbox VM. Hold that thought for later.
The single most searched fix, letting npm and curl work inside the sandbox, is two lines of config:
# ~/.codex/config.toml
sandbox_mode = "workspace-write"

[sandbox_workspace_write]
network_access = true

How Codex enforces it on macOS, Linux, and Windows

  • macOS uses Apple's Seatbelt framework: commands run through sandbox-exec with a profile matching the mode you selected. It works out of the box.
  • Linux uses bwrap (bubblewrap) plus seccomp, the default since version 0.115 in March 2026; the older Landlock path is now legacy. If bwrap is missing, Codex falls back to a bundled helper that needs unprivileged user namespaces, and it warns at startup when neither works.
  • Windows no longer requires WSL. On up-to-date Windows 11 builds (24H2 build 26100.9278 or 25H2 build 26200.9278 and later, where Microsoft has rolled out the MXC capabilities), Codex can use native MXC process isolation (Microsoft Execution Containers): the desktop app prefers it automatically where supported, CLI users opt in with prefer_mxc = true, and elevated and unelevated remain the legacy fallbacks. Run it inside WSL2 and you get the Linux sandbox instead; WSL1 cannot create the user namespaces bwrap needs, so since April 2026 (the 0.121 era) Codex rejects sandboxed commands on WSL1 outright.
One property worth knowing: the sandbox is designed to fail closed. Per the permissions docs, when the platform cannot enforce a selected restricted policy, Codex refuses to run the command rather than silently running it unprotected. Anthropic's equivalent tooling has been criticized for the opposite behavior, which we covered in our Claude Code sandbox guide.

What the Codex sandbox does not protect

The boundary is narrower than most people assume. As of October 2026:
  • Reads are open. workspace-write restricts where the agent can write, not what it can read. Your SSH keys, browser profiles, and dotfiles are readable by default. OpenAI's answer is the beta permission profiles system, which can deny reads outside the workspace and block patterns like **/*.env, but it is opt-in and separate from the classic sandbox_mode setting.
  • Environment variables pass through. Spawned commands inherit your environment by default, and variables with KEY, SECRET, or TOKEN in the name are kept unless you change ignore_default_excludes or add explicit filters.
  • MCP servers live outside the sandbox. They run as their own processes with their own network access. The sandbox policy does not contain them, and the new egress proxy explicitly does not filter MCP connections, web search, or cloud tasks.
  • Prompt injection is contained, not solved. The docs warn that enabling network access or web search lets injected instructions reach the agent, and the worked example in OpenAI's Codex cloud internet-access docs is a GitHub issue that tricks the agent into piping git show HEAD to an outside URL. The same mechanics apply the moment you turn on network access locally. Web search now defaults to a cached index partly for this reason, and switches back to live results when you run with full access.
  • .git is protected, your repo is not. Inside writable roots, .git, .codex, .agents, and .aws are kept read-only. Everything else in the workspace is fair game, which is both the point and the risk.
The sandbox has also been bypassed outright. CVE-2025-59532 let a model-controlled working directory become the writable root, enabling arbitrary file writes (fixed in 0.39.0). And ZDI published a sandbox-escape advisory in April 2026 (ZDI-26-305) that OpenAI assessed as outside the default product surface. That is a decent track record, not a perfect one.
One naming trap: OpenAI also ships Codex Security, a separate vulnerability-scanning CLI and SDK (cs scan). It has nothing to do with sandboxing.

When the sandbox blocks real work

The failure reports on GitHub and the OpenAI forum cluster into a few patterns, and each has a fix short of turning the sandbox off:
Symptom
What is happening
The fix
npm, curl, or builds hang or time out
Network is off by default in workspace-write
Set network_access = true under [sandbox_workspace_write]
"command failed; retry without sandbox?"
A sandboxed command failed, often because the policy denies a path it needs
Approve the escalation, or widen access with --add-dir or writable_roots
Network enabled but macOS still blocks
A long-standing Seatbelt issue (openai/codex #10390) reports network_access = true being ignored
Most reports end at a container or full access
Sandbox errors inside Docker
The container blocks the namespaces or seccomp operations bwrap needs
Let Docker be the boundary (next section)
Windows "setup refresh failed"
Native sandbox setup failures on some builds
On a supported build, opt in to MXC (prefer_mxc = true); otherwise retry the elevated setup or switch to WSL2
The old all-or-nothing network complaint is also finally ending: the experimental [features.network_proxy] config (off by default; set enabled = true) adds an allowlist-first egress proxy with per-domain rules on top of network_access = true, so you can permit registry.npmjs.org without opening the whole internet.

The honest escalation ladder: config, container, VM

When tuning stops being enough, OpenAI's own docs lay out the next steps, and they are refreshingly explicit about it.
Step 1: widen the sandbox, keep it on. Extra writable_roots, network_access = true, and proxy allowlists cover most real projects.
Step 2: make a container the boundary. When Docker blocks the operations the Linux sandbox needs, the official guidance is to configure the container to provide the isolation, then run Codex with --sandbox danger-full-access inside it so Codex does not try to create a second sandbox layer. OpenAI publishes a reference base image, ghcr.io/openai/codex-universal, and documents the same pattern for devcontainers, with a sharp warning attached: a malicious repo can still exfiltrate anything available inside the container, including your Codex credentials. Our Codex Docker guide walks through the whole setup.
Step 3: CI runners. The official openai/codex-action wraps codex exec with an API key, recommends the :workspace permission profile (no network access; leave it unset and you get the legacy workspace-write sandbox instead), and defaults to a drop-sudo safety strategy, because a read-only filesystem plus sudo can still leak your key.
Step 4: Codex cloud. Each task gets its own VM with internet access as a per-environment setting (package-manager presets or custom domain allowlists). It is the zero-setup option, with the limits we covered in the Codex cloud post.
Step 5: a VM of your own. For --yolo work, the docs' own words point at a dedicated sandbox VM: a machine where the blast radius is the whole point.

Running a Codex sandbox 24/7

Everything above assumes a laptop that is open and awake. The moment you want Codex monitoring a repo overnight, running scheduled jobs, or grinding through a long migration, you need the sandbox to outlive your terminal session.
That is the gap Agent37 fills. The agent37-codex template is Codex preinstalled on an always-on, gVisor-isolated instance with its own API, sessions, files, and URL. You connect your own OpenAI account, either by running codex login --device-auth in the instance terminal and approving with your ChatGPT plan, or by passing OPENAI_API_KEY as instance env (it also honors OPENAI_BASE_URL for any Responses-compatible endpoint). The image is lean, no browser and no desktop, and there is no managed-model option: model usage bills your OpenAI account, the sandbox bills Agent37's metered rate.
The math is the selling point. Compute is $0.80 per vCPU and $0.70 per GB of RAM, plus $0.09 per GB of disk, per 730-hour month, metered by the minute, so a standard 2 vCPU, 4 GB sandbox with 4 GB of disk is $4.76 per month running nonstop. Turn on auto-sleep and a box that is awake an hour a day costs about $0.54 per month. If you need a real kernel, for Docker-in-Docker or true --yolo isolation, VM instances run a whole Linux machine with its own kernel and KVM at 2.5x the compute rate, $11.36 per month for the same entry shape. The pricing page compares more than 30 providers at their published rates, claims 94% lower cost than most sandbox providers, and backs it with a refund-the-difference guarantee. New accounts get a $5 starter credit after adding a card, enough to run the entry sandbox for over a month.
And if you just want a Codex agent without touching an API, personal plans deploy Codex in one click, including a free tier with one sleeping agent, no card required.

FAQ

Is Codex sandboxed by default?

Yes. Interactive sessions in version-controlled folders typically start with the Auto preset (workspace-write plus on-request approvals), though Codex may start read-only until you trust the folder; non-version-controlled folders start read-only, and codex exec defaults to a read-only sandbox. Unlike some agent tools, it fails closed when the OS cannot enforce the policy.

How do I let Codex use the network inside the sandbox?

Set network_access = true under [sandbox_workspace_write] in ~/.codex/config.toml, or scope it tighter with the newer egress proxy's domain allowlist. Be aware of the macOS reports that the toggle is ignored under Seatbelt (issue #10390).

How do I turn the Codex sandbox off safely?

Only inside a boundary you trust more: --sandbox danger-full-access inside a Docker container or devcontainer that provides the isolation, an isolated CI runner, or a dedicated VM. Running --yolo on your bare laptop means one injected instruction can touch anything you can.

Does the Codex sandbox work on Windows?

Yes, natively and without WSL: MXC process isolation on up-to-date Windows 11 24H2/25H2 builds where Microsoft has rolled out the capability, the legacy elevated or unelevated sandboxes elsewhere, and the Linux bwrap sandbox under WSL2.

Has the Codex sandbox ever been bypassed?

Yes: CVE-2025-59532 (patched in 0.39.0) allowed writes outside the sandbox root, and ZDI-26-305 described an escape OpenAI judged outside the default product surface. Treat the sandbox as one strong layer, not a guarantee, and put untrusted work in a container, VM, or hosted sandbox.
Vishnu

Written by

Vishnu

Founder at Agent37, which runs managed hosting for OpenClaw and Hermes agents for 1,000+ users. Writes about what actually breaks when you leave an AI agent running.

    Related posts