Codex CLI approval policy: untrusted, on-request, never and the granular policy

🔍 What the approval policy is and why it is not the sandbox

Codex has two separate, complementary controls. The sandbox (sandbox_mode: read-only, workspace-write, danger-full-access) is the technical boundary enforced by the operating system: where commands can write, whether they can reach the network. The approval policy (approval_policy) is the interruption protocol: in which cases Codex must stop and ask me before executing — for instance to leave the boundary, use the network, or run a command outside the trusted set.

The distinction matters because the two dials fail in different ways: a tight sandbox limits damage even with few approvals, while frequent confirmation prompts do not make an unbounded environment safe. I always configure them together, never just one of the two.

Mid-session I check them without touching any file: /status shows the active policy and sandbox, /permissions lets me switch permission levels on the fly — it is the command that early versions called /approvals. From the command line, the policy is passed with --ask-for-approval (or -a), the sandbox with --sandbox (or -s).

# ~/.codex/config.toml
approval_policy = "on-request"   # untrusted | on-request | never
sandbox_mode    = "workspace-write"

# same thing, for a single run
codex --sandbox workspace-write --ask-for-approval on-request

# mid-session: /status to inspect, /permissions to switch

🧭 The three values: untrusted, on-request, never

untrusted is the most conservative and the most misunderstood: Codex autonomously runs only the read operations known to be safe, and asks for confirmation on anything that can mutate state or trigger external execution paths — including destructive Git operations or flags that override configuration. I use it on repositories I do not know, where I want to see every move.

on-request is the interactive standard, the one behind the Auto preset: the agent works freely inside the sandbox and only pings me when it wants to go further — editing files outside the workspace, accessing the network, running certain commands. It is the right trade-off for daily work on trusted projects.

never disables approval prompts, but it is not the free-for-all it sounds like: the sandbox stays fully active and Codex does its best within the constraints I set. -a never with -s read-only is a read-only CI run that never stalls; with -s workspace-write it is automation confined to the repo. A note for readers of older guides: the on-failure value is deprecated — do not copy it from old examples.

There is one case where approval fires regardless of the policy I picked: calls to MCP or app tools that declare themselves destructive. If the tool advertises the destructive annotation, Codex asks for confirmation even if the same tool also claims to be read-only.

⚙️ Granular policy and Auto-review: the options guides skip

When "ask for everything" and "ask for nothing" are both too blunt, there is the granular policy: instead of a string, approval_policy accepts an object that governs each request category separately — sandbox escalations, execpolicy rule prompts, MCP server requests, request_permissions and skill scripts. I can keep sandbox escalations interactive and auto-reject skill scripts, for example.

The other newcomer is Auto-review: with approvals_reviewer = "auto_review", eligible approval requests no longer reach me but an automatic reviewer, which evaluates them for data exfiltration, credential access and destructive operations — denying critical-risk actions and holding high-risk ones. It only applies when approvals are interactive (on-request or a granular policy): with never there is nothing to review.

Two warnings from someone who has tried it: the reviewer evaluates only the actions that already require approval — whatever stays inside the sandbox never reaches it — and each evaluation is an extra model call, so it adds to usage. I treat it as defense in depth, not as a substitute for a tight sandbox.

✅ Where the settings live and the checklist I follow

Settings are layered, and knowing the precedence saves half-hour debugging sessions: CLI flags and -c overrides win, then project .codex/config.toml files (closest first), then the selected profile, then the user configuration in ~/.codex/config.toml, finally the defaults. A security detail I appreciate: project configuration is ignored until the project is trusted, so a freshly cloned repo cannot silently load its own rules and hooks.

For different contexts I use profiles: a cautious one with untrusted + read-only for exploration, a standard one with on-request + workspace-write for daily work, a never one for automation. I invoke them with --profile, and when something looks off my first command is /status, the second codex doctor.

• Unknown repo: untrusted + read-only — I see every move, the agent writes nothing.
• Daily work: the Auto preset (on-request + workspace-write), no flags to remember.
• Automation and CI: never with the tightest sandbox the task allows.
• Long unattended tasks: on-request + approvals_reviewer = "auto_review" as a middle ground.
• Always verify: /status for the active configuration, /permissions to change it mid-session.

More articles from the blog