Sandbox, permissions and approvals

What is a sandbox

Codex's sandbox is a running environment that allows agents to act autonomously while still maintaining boundaries. When Codex executes local commands in apps, IDE extensions, and CLI, these commands will not get full permissions on the entire machine by default, but will run in a restricted environment.

The sandbox boundary determines what Codex can do on its own, such as which files it can modify, whether commands can access the network, and whether it can only work within the current workspace. When the task stays within this boundary, Codex can be executed continuously; when it needs to cross the boundary, it will enter the approval process.

Sandboxing and approvals are two different but complementary sets of controls. The sandbox defines the technical boundaries, and the approval policy determines when Codex must stop and ask. It's important to understand that allowing more approvals doesn't mean expanding the sandbox, and expanding the sandbox doesn't mean eliminating approvals at all.

• The sandbox restricts the commands for model generation and startup, not just the built-in file editing of Codex.
• Child processes such as git, package managers, test frameworks, build scripts, etc. all inherit the same set of sandbox boundaries.
• The underlying implementation differs between macOS, Linux, WSL2, and Windows, but the goal is to have agents work within well-defined scopes.

Why you need a sandbox

Sandboxing reduces approval fatigue from low-risk operations. You don't need separate confirmations for each time you read a file, change a workspace file, or run a local test, but you can still tell when the Codex is trying to cross a boundary.

It also makes it easier for teams to build a trust model: instead of simply trusting the agent to "do something good," you make it work within the constraints enforced by the operating system or runtime. In this way, when dealing with a real repository, you can give it enough space to complete the task without letting it touch the host, network or sensitive directories by default.

Platform premise

Codex automatically uses available platform sandboxing capabilities. macOS uses the system's built-in mechanism; Windows can use the native Windows sandbox or WSL2's Linux sandbox; Linux and WSL2 recommend installing bubblewrap.

On some Linux distributions, bubblewrap also relies on unprivileged user namespace or AppArmor configuration. When Codex is started, if it detects that bwrap is missing or cannot create the required namespace, a warning will be displayed; at this time, priority should be given to repairing the system's sandboxing capabilities rather than switching directly to full access.

sudo apt install bubblewrap
# or
sudo dnf install bubblewrap

How to control the sandbox

Most users start with permission control within the product. Codex App and IDE can select permission mode near the input box; in CLI session, you can use /permissions to switch.

/permissions

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

sandbox_mode = "workspace-write"
approval_policy = "on-request"
approvals_reviewer = "user"

Common sandbox modes

Codex's common sandbox modes can be understood as three levels: read-only, workspace writable, and full access. Each level should be viewed together with the approval strategy.

Approval strategy

Approval policies control when Codex is paused. Common official policies include untrusted, on-request, and never; when approval is interactive, there is also the option to review by user or auto_review.

auto_review only reviews requests that inherently require approval, such as sandbox out of bounds, blocked network requests, request_permissions prompts, or app/MCP tool calls with side effects. Behaviors already allowed within the sandbox will not pass through it.

approval_policy = "on-request"
approvals_reviewer = "auto_review"

network access

workspace-write turns off command network access by default. When you need to connect to the Internet to install dependencies, call APIs, or access internal services, you should explicitly open the network and try to use domain name rules to limit exports.

network_proxy does not grant network permissions individually, it simply imposes policies on enabled command network access. That is, network_access still determines whether the command has a network, and network_proxy determines where this network traffic can go.

The domain name policy is allowlist-first: the exact host only matches itself, *.example.com matches subdomains, **.example.com matches both root domains and subdomains, and deny always takes precedence. The global *allow represents very wide network permissions and should be avoided as much as possible.

[sandbox_workspace_write]
network_access = true

[features.network_proxy]
enabled = true
domains = { "api.openai.com" = "allow", "example.com" = "deny" }

protected path

In the default workspace-write, some directories remain read-only. The official specifically mentioned that .git, .agents, .codex and their recursive contents will be protected to prevent tasks from accidentally destroying the repository state or Codex's own configuration.

If .git is a gitdir pointer file, the parsed Git directory is also read-only. When encountering requirements such as git commit, git reset, and modification of Codex configuration, Codex may require approval or explicit authorization.

• Don't switch directly to danger-full-access just to let a command pass.
• First determine whether the task really needs to write a protected path, and whether it can use ordinary files, temporary directories, or smaller approval exceptions instead.
• Check the diff when finished to confirm that no version control, configuration, or automation files were accidentally modified.

Run silently

If you want to cancel the approval prompt, you can use --ask-for-approval never or -a never, but it will still be subject to the sandbox mode.

This means never does not equal full permissions. A safer non-interactive approach is workspace-write + never, which allows the Codex to execute automatically within the workspace; only consider danger-full-access + never when the external environment is isolated and there is no host risk.

If you really need to read files, write files, run commands and connect to the Internet without any prompts, the official also provides danger-full-access or dangerously bypass related entrances, but these should only be used in a controlled environment.

codex --sandbox workspace-write --ask-for-approval never "Run tests and fix failures"

# High risk, isolated environment only
codex --sandbox danger-full-access --ask-for-approval never

Study Checklist

Put the content on this page into real tasks and use the five dimensions of entry, context, permissions, verification and team rules to check whether you have truly mastered it.

Codex practical notes

Fill in the most overlooked execution details of Codex usage around local environments, privilege escalation, remote entry, automation failures, and rollbacks.