skip to content

In Codex, what does sandbox_mode control versus approval_policy, and what does the default workspace-write plus on-request pairing allow without asking?

level: middleimportance: should knowfreq 10%

answer

  1. two layers, two questions
  2. can it, versus must it ask
  3. three sandbox modes
  4. network off in workspace-write
  5. .git and .codex stay read-only

basics

~20 s

sandbox_mode sets what model-run commands can technically touch; approval_policy sets when Codex stops to ask. With workspace-write and on-request, Codex reads, edits and runs commands in the workspace freely, but asks before writing outside it or using the network.

solid answer

~40 s

Codex separates two questions. **`sandbox_mode`** is the OS-enforced boundary for commands the model runs: `read-only`, `workspace-write` (writes inside the workspace, network off unless `[sandbox_workspace_write] network_access = true`), or `danger-full-access` (no sandbox). **`approval_policy`** decides when Codex pauses for you: `on-request`, the default, lets the model ask when it needs to leave the sandbox; `never` never asks, so blocked actions fail back to the model; a `granular` table chooses per prompt category. The documented **Auto** pairing, `workspace-write` with `on-request`, lets Codex read, edit and run commands in the workspace without prompting, and asks before editing outside it or using the network. Even then `.git`, `.codex` and `.agents` stay read-only. You switch in the session with `/permissions`, or start with `--sandbox` and `--ask-for-approval`.

go deeper

for a junior

Recall the two settings, the three sandbox modes, and that the default workspace-write keeps network access off.

for a middle

Explain the split: the sandbox is OS-enforced capability, the approval policy is when Codex asks, and describe on-request, never and granular with their effects.

for a senior

Choose a pairing for a real workflow and name its leftovers: protected paths, network off, and why never with a narrow sandbox is safer than a wide sandbox.

for a principal

Decide which pairings a team may use, where they are pinned, and when a container rather than Codex's own sandbox should be the boundary.

## Two layers, two questions Codex, OpenAI's coding agent, controls what it may do on your machine with two independent settings. The documentation describes them as layers that work together: - **`sandbox_mode`** answers *what can a command technically do?* It is enforced by the operating system — Seatbelt policies through `sandbox-exec` on macOS, `bwrap` plus `seccomp` on Linux and WSL2, a native sandbox on Windows — and it applies to the commands the model generates. - **`approval_policy`** answers *when must Codex stop and ask?* It decides whether an action that needs more than the sandbox allows is put to a person, handled automatically, or refused. Confusing the two is the classic mistake: turning approvals off does not remove the walls, and widening the walls does not by itself add prompts. ## The three sandbox modes | `sandbox_mode` | Files | Network for commands | |---|---|---| | `read-only` | read only | off | | `workspace-write` | write in the workspace (current directory plus temporary directories such as `/tmp`) | off unless `sandbox_workspace_write.network_access = true` | | `danger-full-access` | no sandbox | unrestricted | Inside `workspace-write`, some paths stay protected: `<root>/.git` (including the Git directory a `gitdir:` pointer file resolves to), and the `.agents` and `.codex` directories when they exist are read-only, recursively. Extra writable directories go in `sandbox_workspace_write.writable_roots`, and `exclude_tmpdir_env_var` and `exclude_slash_tmp` remove the temporary directories. ## The approval policies At Codex 0.159.3, `approval_policy` accepts: 1. **`on-request`** — the default. Commands the sandbox allows run without asking; the model requests approval when it needs to go beyond the sandbox. `on-failure` is still accepted as a deprecated alias for it. 2. **`never`** — Codex never asks. A blocked action fails and the error goes back to the model, which works within the limits. It combines with any sandbox mode. 3. **`granular`** — a table of booleans, `sandbox_approval`, `rules`, `mcp_elicitations`, `request_permissions` and `skill_approval`. `true` lets that category's prompt reach you; `false` rejects those requests automatically without showing them. The old `untrusted` value is retired: 0.159.3 refuses to start with it in config. ## What the Auto pairing does The documentation calls `workspace-write` with `on-request` the **Auto** preset and recommends it for version-controlled folders. With it, Codex: - reads files and makes edits in the workspace without asking; - runs commands in the workspace without asking; - asks before editing files outside the workspace; - asks before running commands that need network access. For a folder that is not under version control Codex recommends `read-only`, and depending on your setup it may start read-only until you trust the working directory. ## Changing the settings - **In a session:** `/permissions` chooses what Codex is allowed to do, for example switching to read-only to plan without changes; `/status` shows which directories are in the workspace. - **At launch:** `codex --sandbox workspace-write --ask-for-approval on-request`, or the short forms `-s` and `-a`. - **In `config.toml`:** set `sandbox_mode` and `approval_policy` at top level, and network access under `[sandbox_workspace_write]`. - **Fully open:** `--dangerously-bypass-approvals-and-sandbox`, alias `--yolo`, removes both layers; the documentation recommends it only inside an environment that is already isolated. ## Common misreadings - **"`never` is the dangerous setting."** On its own it only removes prompts. Paired with `read-only` it is the documented setup for a non-interactive CI run that must not change anything. - **"`danger-full-access` is `workspace-write` plus network."** It removes the sandbox altogether: every file the user can reach and the whole network. - **"Network off means no web search."** The web search tool is configured separately with `web_search` (`cached` by default); `sandbox_workspace_write.network_access` governs commands only. - **"Allowing a domain turns the network on."** Domain rules under the `network_proxy` feature only constrain traffic once command network access is already enabled. - **"Approvals protect `.git`."** In `workspace-write` the sandbox itself keeps `.git`, `.codex` and `.agents` read-only, whatever the approval policy says. ## An everyday picture Think of the sandbox as the walls of a workshop and the approval policy as the rule for when you must knock on the supervisor's door. `never` means nobody knocks — but the walls are still there, so anything outside them simply cannot be reached. Only `danger-full-access` takes the walls down.

  • What does `approval_policy = "never"` change when combined with `read-only`?
    Codex never prompts. Commands run inside the read-only sandbox; anything that would need a write or network access fails, and the error goes back to the model, which has to work within those limits. The documentation lists this pairing as the read-only non-interactive setup for CI.
  • Which paths stay read-only even in Codex's `workspace-write` mode?
    In each writable root, `.git` is protected whether it is a directory or a `gitdir:` pointer file (and then the resolved Git directory too), and `.agents` and `.codex` are protected when they exist as directories. Protection is recursive, so hooks and config inside them cannot be rewritten by a sandboxed command.

The sandbox is the workshop's walls; the approval policy is when you must knock on the supervisor's door. Setting never stops the knocking, but the walls still stand, so anything outside them stays out of reach.

  • approval_policy = never means Codex can do anything, including writing outside the workspace
  • workspace-write lets commands reach the network by default
  • danger-full-access only removes approval prompts and keeps the sandbox
  • sandbox_mode and approval_policy are one setting with three levels
  • In workspace-write, Codex can rewrite the repository's .git hooks

Assumes Codex 0.159.3: on-request is the default, on-failure an alias of it, and approval_policy = "untrusted" is refused at startup.