Codex Sandbox: Modes, Approvals and Running Codex in a VM

The Codex sandbox is the boundary Codex CLI puts around the commands it runs: read-only, workspace-write or danger-full-access. Locally, workspace-write with on-request approvals covers most work. To run Codex unattended with the sandbox off, OpenAI's docs say to do it only inside a controlled environment, such as an isolated container or CI runner.

This guide explains each mode and approval policy, then sets up a remote VM where Codex can run with full access and still can't reach your keys or the open internet.

# Store the API key so that only api.openai.com can receive it
beam secret create CODEX_API_KEY "$OPENAI_API_KEY" --host api.openai.com

# Create a VM with the secret bound, then upload the repo to /workspace
beam vm new codex-box --secret CODEX_API_KEY
beam vm sync codex-box ./my-project

# Allow only the hosts this run needs, and save a restore point
beam vm network codex-box --allow api.openai.com --allow github.com
beam vm snapshot create codex-box --name codex-before-run

# Run Codex headless with its own sandbox off: the VM is the boundary
beam vm exec --cwd /workspace codex-box -- \
  codex exec --skip-git-repo-check --sandbox danger-full-access \
  "Run the test suite and fix the failing tests"

What the Codex sandbox does

The sandbox sets the technical limits on what Codex can touch, and the approval policy decides when Codex has to stop and ask before going past them. OpenAI's docs treat these as two separate settings, and you pick a value for each.

Codex CLI has three sandbox modes:

• `read-only`. Codex can inspect files, but it can't edit files or run commands without approval. This is also the default for codex exec, the non-interactive mode.
• `workspace-write`. Codex can read files, edit inside the workspace, and run routine local commands there. Network access stays off unless you turn it on. This is the low-friction default for interactive local work.
• `danger-full-access`. No filesystem or network restrictions at all. OpenAI's docs say to use it only in a controlled environment.

Two approval policies remain. on-request lets Codex work inside the sandbox and ask when it needs to step outside. never means Codex never stops for a prompt. The older untrusted policy is retired. You can also set approvals_reviewer = "auto_review" so a reviewer agent answers eligible prompts instead of you; that changes who approves, not where the sandbox boundary sits.

The interactive "Auto" preset is --sandbox workspace-write --ask-for-approval on-request. In config.toml the same choice is sandbox_mode and approval_policy, and sandbox_workspace_write.writable_roots adds directories Codex may edit.

How the sandbox works on macOS, Linux and Windows

The enforcement is different on each OS:

• macOS uses the built-in Seatbelt framework, with nothing to install.
• Linux and WSL2 need bubblewrap. Codex uses the first bwrap on your PATH and falls back to a bundled helper that needs unprivileged user namespaces.
• Windows uses a native Windows sandbox in PowerShell, and the Linux sandbox under WSL2.

To check what the sandbox allows before you trust it, run a command through codex sandbox macos, codex sandbox linux or codex sandbox windows.

What stays read-only in workspace-write

.git, .agents, .codex and .aws stay read-only even inside a writable root, and everything under them is protected too. That keeps Codex from rewriting its own config or your cloud credentials. It also means a commit from inside workspace-write needs an approval or a rule that allows it.

Is danger-full-access or --yolo safe?

It's safe only when something outside Codex is doing the isolating. --dangerously-bypass-approvals-and-sandbox, also spelled --yolo, removes both the sandbox and the approval prompts, and OpenAI labels it elevated risk and not recommended. --sandbox danger-full-access keeps approvals but drops the sandbox. Either way, Codex can then do anything the user running it can do.

Three things don't change when you turn the sandbox off:

• Prompt injection still works. OpenAI's docs warn that injected text can make the agent fetch and follow untrusted instructions. Isolation limits the damage; it doesn't stop the attempt.
• Web search goes live. With --yolo or other full-access settings, the web_search setting defaults to live results instead of the cached index, so the agent reads the open web.
• Credentials are readable. OpenAI's docs say to treat ~/.codex/auth.json like a password, and warn that a malicious project in a dev container can exfiltrate anything in it, Codex credentials included.

So the useful question isn't whether to use full access but where. On your laptop, it exposes your whole user account. In a disposable VM with an egress allowlist and no real key inside, it exposes one machine that you can throw away.

Why Codex's Linux sandbox fails in Docker

Codex's Linux sandbox needs namespaces, a setuid bwrap or seccomp operations that many containers block, so it can fail to start inside Docker. OpenAI's fix is to configure the container for the isolation you want and run Codex with --sandbox danger-full-access inside it. That swaps the inner sandbox for the outer one rather than stacking them.

The same logic applies to a VM, with a stronger outer layer. A Beam VM runs in a CPU microVM with its own kernel, so Codex running with full access inside it is separated from the host by a hypervisor rather than a shared kernel. For why that boundary is stronger, see what a microVM is.

If you also want Codex's own sandbox inside the VM as a second layer, run codex sandbox linux -- ls /workspace first. If it works, use --sandbox workspace-write instead of full access.

How to run Codex unattended in an isolated VM

An unattended Codex run needs four things: a separate machine, a credential the agent can use but not read, an egress allowlist, and a restore point. Beam VM images ship with the Codex CLI installed, so the quickstart at the top does all four with no install step. Here's what each part does.

Use the right flags for codex exec

codex exec runs one task without a terminal UI and starts in read-only mode. For edits, pass --sandbox workspace-write or, inside a VM you trust as the boundary, --sandbox danger-full-access. --full-auto is no longer supported, so older scripts that use it need to switch to --sandbox.

A few other flags matter for automation:

• --skip-git-repo-check lets Codex run outside a Git repository. Codex requires one by default as a guard against destructive changes.
• --json turns stdout into a JSONL stream of every event, which is easier to log and parse.
• -o PATH writes only the final message to a file.
• --ephemeral skips saving session rollout files.
• codex exec resume continues an earlier run, for two-stage pipelines.

Keep the API key out of the agent's reach

codex exec reads an API key from CODEX_API_KEY. OpenAI warns against setting it as a job-wide environment variable anywhere that runs repository code, because the agent can read it. A Beam brokered secret avoids that. The VM sees a placeholder that starts with beam_secret_, and Beam's worker swaps in the real key only in HTTPS request headers sent to the hosts you approved, then scrubs the literal key from responses. With --host api.openai.com, an agent that dumps its environment and posts it somewhere leaks only the placeholder.

Two limits from Beam's secrets docs: substitution happens only in headers over HTTPS on port 443, and certificate-pinned clients can't use it.

Limit where Codex can connect

beam vm network codex-box --allow HOST turns the VM's egress into an allowlist of up to 64 hostnames, wildcard domains, IPs or CIDRs. Rules persist across restarts, take effect without a reboot, and block UDP and ICMP except DNS.

Codex needs api.openai.com for model calls with an API key. Add only what the task needs beyond that: github.com to clone and push, registry.npmjs.org or pypi.org to install packages. If the agent needs nothing but the model, beam vm network codex-box --block leaves only the approved hosts of bound secrets reachable.

Save a restore point and fork attempts

beam vm snapshot create saves the VM's root disk. If a run wrecks the environment, start a fresh VM from it with beam vm fork SNAPSHOT_ID codex-box-2. You can also fork a live VM, for example beam vm fork codex-box attempt-b, to give two Codex runs the same starting point. Snapshots and forks copy the filesystem only. To keep running processes and memory, use beam vm pause and resume later.

Run long tasks in the background

A foreground beam vm exec streams output and returns Codex's exit code. For a long task, add --detach --json and follow it with beam vm logs codex-box --pid PID -f. New VMs have no idle timeout by default, and detached work doesn't keep a VM with a --ttl awake once your CLI exits, so leave the timeout off for unattended runs.

When to use beam vm prompt

beam vm prompt codex-box "…" --agent codex runs codex exec --skip-git-repo-check with your prompt and keeps a durable session log in /workspace/.beam-vm/logs/. It doesn't pass a sandbox flag, so Codex starts in its default read-only mode. That fits questions such as "explain how this project's tests run". For edits, use the beam vm exec command above.

Choosing a sandbox for Codex

Pick by where the code runs and how much you trust the repository. For your own code on your own machine, the built-in sandbox in workspace-write handles most work with no setup. Docker's sbx puts Codex in a local sandbox and keeps credentials on the host. For untrusted repositories, many parallel runs or tasks that last hours, a remote machine is the better boundary.

The local options are free and see your files directly, with no upload step. Codex cloud needs no setup if you already use ChatGPT, though OpenAI controls the image and the 12-hour cache. A Beam VM fits when you want a machine that keeps its state between runs, can be forked for parallel attempts, and bills per second only while it runs. The default VM of 4 vCPUs and 8 GiB costs $0.28 an hour on the Performance tier, which new accounts start on, $0.088 on Shared, or $0.036 on Spot, which can be interrupted. Its 50 GiB disk isn't billed yet. A paused or stopped VM has no compute charges. OpenAI API usage is billed separately by OpenAI.

If you're comparing hosted sandboxes, see the guide to Docker Sandbox alternatives, and for code your agent writes at runtime, the guide to a sandbox for AI-generated code. Teams running several agents can start from the coding agents use case and the virtual machines overview.

FAQ

What sandbox mode does Codex use by default?

Interactive Codex uses workspace-write with on-request approvals, the "Auto" preset. codex exec starts in read-only. Network access is off in workspace-write until you set network_access = true under [sandbox_workspace_write] in config.toml.

What does --full-auto do in Codex?

It used to turn on workspace-write with fewer prompts. OpenAI's docs now say --full-auto is no longer supported, and scripts should pass --sandbox workspace-write instead. Some guides and examples still show the old flag.

How do I run Codex in Docker?

Install Codex in the image and run it as you would on a Linux host. If the Linux sandbox fails because the container blocks namespaces or seccomp, OpenAI's guidance is to make the container the boundary and run Codex with --sandbox danger-full-access inside it. Docker's own sbx run codex does this for you locally.

Is --dangerously-bypass-approvals-and-sandbox the same as --yolo?

Yes. Both run Codex with no sandbox and no approval prompts, and with web search switched to live results. Use them only inside a container or VM you're willing to lose.

Can Codex leak my API key from a sandbox?

Yes, if the key is in the sandbox and the network is open. The agent can read CODEX_API_KEY or ~/.codex/auth.json like any other file. Restrict egress to the hosts the task needs, and keep the real key outside the guest with a proxy that adds it only to requests for api.openai.com.

Can I sign in with ChatGPT instead of an API key in a remote VM?

Codex stores ChatGPT sign-in tokens in ~/.codex/auth.json, and OpenAI suggests seeding that file through secure storage on machines where codex login isn't practical. Inside the VM, the agent can read that file, so a brokered API key is the safer choice for unattended runs.

Ready to give Codex a machine of its own? Create a Beam account and start a VM with beam vm new codex-box.