Approvals & Sandboxing

Almost everyone new to Codex collapses safety into a single dial — "how locked down is it?" That instinct will trip you up. Codex separates safety into two independent controls, and you set each one on its own:

• Sandbox = WHERE. This is an OS-enforced boundary on what Codex's commands can read, write, and whether they can reach the network. The operating system itself stops a command from escaping it — it isn't the model politely declining.
• Approval = WHEN. This is the policy for when Codex must stop and ask you before it runs something. It governs the conversation, not the kernel.

Think of it like a new contractor working in your house. The sandbox is which rooms they're physically allowed into and whether they get a key to the front gate (the building enforces that — locked doors). Approvals are the rule for when they have to knock and ask you first before doing a thing. You can have a contractor confined to one room who still asks before every action, or one with a full set of keys who never asks. The where and the when are genuinely separate.

Why does this matter? Because the two combine into very different safety postures, and the dangerous mistakes come from changing the wrong knob. Loosening approvals so Codex stops nagging you is fine if the sandbox still confines it. Dropping the sandbox to silence the same prompts is how people accidentally hand an agent the keys to the whole machine. Keep the two ideas separate in your head and the rest of this lesson clicks into place.

The sandbox is set with --sandbox / -s on the command line, or sandbox_mode in ~/.codex/config.toml. There are exactly three modes:

In config form:

sandbox_mode = "workspace-write"   # or "read-only" / "danger-full-access"

The mental progression is consultant → editor → root. read-only is a consultant who can look but not touch. workspace-write is an editor who can change things in your project but can't wander off into the rest of the machine or phone home. danger-full-access removes the walls entirely.

The key boundary in workspace-write is the workspace root — Codex can freely edit files inside it but is blocked from writing elsewhere. That's what makes it the everyday default: enough freedom to actually do the work, with a hard wall around the blast radius.

The approval policy is set with --ask-for-approval / -a on the command line, or approval_policy in config. The accepted values on the current CLI are untrusted, on-request, and never:

In config form:

approval_policy = "on-request"

Notice how on-request leans on the sandbox: Codex doesn't pester you for every edit because the sandbox already confines it; it only surfaces a prompt when it wants to step outside that confinement. That's the whole reason the two controls are designed to work together.

There's also a granular object form (approval_policy = { granular = { ... } }) for fine-tuned control over which categories of action prompt — but the three string values above cover almost every situation; reach for the granular form only when you have a specific need and verify its exact shape against the live config reference.

In an interactive session you usually don't set the two knobs by hand — you pick a preset from the picker. Each preset is simply a sandbox mode + approval policy combined, so once you understand the two controls, the presets are obvious:

Auto is the launch default and where you'll live most of the time. The explicit flag form of Auto is just the two knobs spelled out:

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

So a preset isn't a fourth concept to memorize — it's a named shortcut for a (where, when) pair. Knowing that lets you read any preset's safety properties off its two components, and it's why you can always fall back to the explicit flags when you want a combination the presets don't offer.

Here is the single most surprising thing about workspace-write, and the one that catches everyone: network access is DISABLED by default. Codex can edit your files all day, but npm install, pip install, curl, or any command that reaches the internet will be blocked until you explicitly opt in. This is deliberate — the network is the main escape route for a prompt-injection or a runaway command, so it's off unless you say otherwise.

The legacy sandbox_mode schema opts in with a single boolean plus optional extra writable roots:

[sandbox_workspace_write]
network_access = true            # default is false
writable_roots = ["/Users/you/.pyenv/shims"]   # extra writable dirs
exclude_tmpdir_env_var = false   # is $TMPDIR writable?
exclude_slash_tmp = false        # is /tmp writable?

The newer permission-profile schema expresses network as a per-domain allowlist instead of one on/off switch, so you can permit api.openai.com while denying a tracking host:

[permissions.profile-name.network]
enabled = true

[permissions.profile-name.network.domains]
"api.openai.com"       = "allow"
"*.example.com"        = "allow"
"tracking.example.com" = "deny"   # deny overrides allow

Two rules worth burning in: deny always wins over allow on a conflict, and even when you enable the network, Codex blocks literal local targets like localhost and 127.0.0.1 by default as a DNS-rebinding defense — you have to explicitly allowlist them. Enabling network access changes how it's enforced; it does not, by itself, hand Codex the open internet.

The sandbox is only meaningful because the operating system enforces it — not the model's good intentions. Codex uses the platform-native mechanism for each OS, and crucially it refuses to run a command unsandboxed if the platform can't enforce the requested policy. It does not silently fall back to no sandbox — a vital property to trust.

The Windows native sandbox is comparatively new — older material says Windows is WSL-only, so don't carry that assumption in. The two Windows modes trade isolation for privilege:

[windows]
sandbox = "elevated"   # preferred; or "unelevated"

• Elevated uses dedicated lower-privilege sandbox users, filesystem permission boundaries, and firewall rules — the strongest isolation.
• Unelevated is a fallback using a restricted token derived from your user and ACL-based boundaries; network isolation is weaker and it can't enforce every read/write carve-out.

The practical upshot: if you see a Linux/WSL2 error like "couldn't set up sandbox," it's almost always missing bubblewrap or restricted user namespaces — and Codex stopping is the correct behavior, because it would rather refuse than run your commands without the boundary you asked for.