Codex sandbox and approval modes

Who this is for and what you will be able to do

This guide is for people who run Codex CLI or the IDE extension on their own machine and want to limit what the agent can change. After reading it you should know what the sandbox and approval policy each control, how to pick a combination for a given situation, what Linux and WSL2 need installed first, and how to use codex sandbox to see what a command does under the sandbox.^[1][2]

The sandbox and approvals are separate controls

The sandbox defines technical boundaries, such as which files the agent can modify and whether commands can use the network. The approval policy decides when the agent must stop and ask before it crosses those boundaries. The two work together.^[1]

The sandbox applies to commands the agent starts, not only to built-in file operations. Tools such as git, package managers and test runners inherit the same boundaries.^[1]

Locally, Codex turns network access off by default. An OS-enforced sandbox limits what the agent can touch, typically to the current workspace.^[2]

The three sandbox modes

• read-only: the agent can inspect files, but it cannot edit files or run commands without approval.^[1]
• workspace-write: the agent can read files, edit within the workspace, and run routine local commands inside that boundary. The docs call it the default low-friction mode for local work.^[1]
• danger-full-access: the agent runs without sandbox restrictions, so the filesystem and network boundaries are gone. The docs say to use it only when you want the agent to have full access.^[1]

Full access means sandbox_mode set to danger-full-access together with approval_policy set to never. The lower-risk local automation preset is workspace-write with on-request.^[1]

The two approval policies

• on-request: the agent works inside the sandbox by default and asks when it needs to go beyond that boundary.^[1]
• never: the agent does not stop for approval prompts.^[1]

The untrusted value is no longer a selectable approval policy, so a configuration that still uses it needs to be migrated.^[1]

The approvals_reviewer setting decides who reviews approval prompts. The default, user, shows them to you. With auto_review, eligible requests go to a reviewer agent first.^[1]

Choosing a combination

• Auto preset: --sandbox workspace-write --ask-for-approval on-request, or no flags at all. Codex can read files, make edits and run commands in the working directory without asking, and it asks for approval before editing outside the workspace or using the network.^[2]
• Interactive read-only use: the docs' migration example pairs sandbox_mode = "read-only" with approval_policy = "on-request".^[2]
• Non-interactive CI: the docs list --sandbox read-only --ask-for-approval never, which is read-only and never asks. For codex exec, use --sandbox workspace-write.^[2]
• Full access: --dangerously-bypass-approvals-and-sandbox, also written --yolo, runs with no sandbox and no approvals. The docs say this is not recommended.^[2]

Linux and WSL2: install bubblewrap first

On Linux and WSL2, Codex's sandbox relies on bwrap, from the bubblewrap package. Install it with your package manager: sudo apt install bubblewrap on Ubuntu or Debian, or sudo dnf install bubblewrap on Fedora.^[1]

Codex uses the first bwrap it finds on PATH. If none is available, it falls back to a bundled helper, which needs unprivileged user namespace creation to be allowed. Installing the distribution package keeps the setup reliable.^[1]

If bwrap is missing, or the helper cannot create the needed user namespace, Codex shows a warning at startup.^[1]

On Ubuntu 24.04 the warning can persist after bubblewrap is installed. The docs say to copy /usr/share/apparmor/extra-profiles/bwrap-userns-restrict to /etc/apparmor.d/bwrap-userns-restrict, then load it with sudo apparmor_parser -r /etc/apparmor.d/bwrap-userns-restrict. The profile takes effect without a reboot.^[1]

macOS and Windows

On macOS, sandboxing works out of the box using the built-in Seatbelt framework.^[1]

On Windows, Codex uses the native Windows sandbox when you run in PowerShell, and the Linux sandbox implementation when you run in WSL2.^[1]

Test a command under the sandbox

The codex sandbox command shows what happens to a command under the sandbox. The docs give one form per platform, where the bracketed parts are optional:^[2]

# macOS
codex sandbox macos [--permissions-profile <name>] [--log-denials] [COMMAND]...
# Linux
codex sandbox linux [--permissions-profile <name>] [COMMAND]...
# Windows
codex sandbox windows [--permissions-profile <name>] [COMMAND]...

Turning on network access

In workspace-write mode, network access is off by default. To turn it on, set this in your configuration:^[2]

[sandbox_workspace_write]
network_access = true

After that you can enable the network_proxy feature to limit outbound traffic to the domain rules you configure. The feature is off by default. It constrains commands whose network access is already on, and by itself it does not grant access.^[2]

Domain rules are allowlist-first. An exact host matches only itself, *.example.com matches subdomains such as api.example.com but not example.com, and deny always wins over allow.^[2]

Protected paths inside writable roots

Even in workspace-write mode, .git, .agents, .codex and .aws inside a writable root are read-only when they exist, and the protection is recursive. A .git entry is protected whether it is a directory or a file that points to a Git directory.^[2]

Web search settings

web_search defaults to cached, which serves results from an index of web results maintained by OpenAI. live fetches live data, the same as --search. indexed lets external access happen only when the search index allows it, and disabled turns the web search tool off.^[2]

Treat web results as untrusted. With --yolo or another full-access sandbox setting, web search defaults to live results. Prompt injection can lead the agent to fetch and follow untrusted instructions, so be careful when you enable network access or web search.^[2]

Common problems

The bubblewrap warning stays. Make sure bwrap is on PATH. On Ubuntu 24.04, load the bwrap-userns-restrict profile as described above.^[1]

The sandbox does not work in a container. The sandbox can fail if the host or container configuration blocks the namespace, setuid bwrap or seccomp operations that Codex needs. The docs suggest configuring the container for isolation, then running codex --sandbox danger-full-access inside it.^[2]

Limits

• danger-full-access and --yolo both run without sandbox protection. The docs say to use danger-full-access only when you really want full access, and they do not recommend --yolo.^[1][2]
• A Dev Container can serve as the outer isolation layer. If you run danger-full-access inside it, a malicious project can exfiltrate anything inside the container, including Codex credentials, so the docs say to use it only with trusted repositories.^[2]

Next steps

For the exact configuration keys, continue with the configuration documentation. The sandbox page and the approvals and security page are the official full references for this material.^[1][2]