Codex CLI Permissions and Sandbox Reference

Updated September 30, 2026 by Alex Sorokoletov

Independent reference, not affiliated with OpenAI. Tables are generated from the Codex CLI source at rust-v0.159.2 (v0.159.2). Official documentation: learn.chatgpt.com.

Codex CLI limits commands in two ways: a sandbox decides which files and network a command can reach, and an approval policy decides when Codex asks you first. The sandbox comes from legacy sandbox_mode or from permission profiles selected by default_permissions, with built-ins :read-only, :workspace and :danger-full-access. Administrators can lock both in requirements.toml.

What are Codex sandbox modes?#

sandbox_mode takes three values, each equivalent to a built-in permission profile. Only requirements.toml accepts a fourth value, external-sandbox.

:workspace reads everywhere and writes to the workspace roots (the working directory plus any --add-dir directories), /tmp and $TMPDIR, with network off. The legacy [sandbox_workspace_write] table tunes the same thing:

The sandbox is enforced by the operating system:

What approval policies does Codex support?#

With no approval_policy set, Codex uses on-request, except for projects marked untrusted, which get the internal untrusted policy. granular answers each kind of prompt separately: true lets that kind reach you, false rejects it automatically without asking.

approval_policy = { granular = { sandbox_approval = true, rules = true, mcp_elicitations = false } }

approvals_reviewer decides who answers an escalated request. auto_review sends it to a reviewer subagent instead of you; guardian_subagent is the legacy name for the same value.

What is the difference between sandbox mode and approval policy?#

The sandbox is the hard boundary: a command in :workspace cannot write outside the workspace roots whatever the model intends. The approval policy only governs what happens when a command needs more than the sandbox allows, or a rule asks for confirmation: on-request lets the model ask you, never returns the failure to the model without asking. never with :read-only gives an agent that can read but never change anything and never prompts.

How do Codex permission profiles work?#

A profile is a named [permissions.<name>] table, selected with default_permissions = "<name>". It can extends :read-only, :workspace or another profile of yours, then adds filesystem entries and network settings on top; child keys override the parent's. Names starting with : are reserved for built-ins, and :danger-full-access cannot be extended.

default_permissions = "dev"

[permissions.dev]
extends = ":workspace"
description = "Workspace write, one secret hidden, network on"

[permissions.dev.filesystem]
"/srv/secrets" = "deny"

[permissions.dev.network]
enabled = true

Filesystem values are read, write or deny (none is a legacy alias of deny). When two equally specific entries target the same path, deny beats write and write beats read. Besides absolute paths, entries accept these tokens; unknown :tokens are warned about and ignored, so a newer config still loads:

sandbox_mode or default_permissions: which one wins?#

Both keys still work in 0.159.2. Codex decides per session which model applies:

So with nothing configured, a trusted repository gets :workspace with on-request approvals, an untrusted one gets :workspace with untrusted approvals, and a directory with no trust decision gets :read-only.

Why are my Codex permissions locked by requirements.toml?#

requirements.toml is the administrator's file. Its allowed_* lists limit which values your config may choose, and a few keys such as default_permissions pin a value outright. It is read from the system location, enterprise cloud bundles and macOS managed preferences, never from your user or project config.

allowed_approval_policies = ["on-request"]
allowed_sandbox_modes = ["read-only", "workspace-write"]

Is there a Codex equivalent of --dangerously-skip-permissions?#

Yes: --dangerously-bypass-approvals-and-sandbox, aliased --yolo. It runs every command without a sandbox and without asking, and is meant for environments that are already sandboxed from outside, such as a disposable container. --approve-for-me keeps the workspace-write sandbox and routes approval requests to the automatic reviewer instead of you.

How do I allow network access in workspace-write?#

Network is off in :workspace and workspace-write by default. The switch depends on which permission model is active:

Frequently asked questions#

What are Codex sandbox modes?#

read-only lets commands read files but not write them or use the network; workspace-write also lets them write inside the workspace roots, /tmp and $TMPDIR; danger-full-access removes the sandbox. They correspond to the built-in permission profiles :read-only, :workspace and :danger-full-access. Set one with sandbox_mode in config.toml or -s on the command line.

What is the difference between sandbox mode and approval policy?#

The sandbox limits what a command can touch; the approval policy decides whether Codex asks you when a command needs more. on-request lets the model ask for escalation, never sends failures straight back to the model, and granular accepts or rejects each prompt type separately. They combine: workspace-write with on-request is the usual interactive setup.

How do I stop Codex from always asking for approval?#

Set approval_policy = "never" (or run with -a never) to stop prompts while keeping the sandbox; blocked commands then fail back to the model. --approve-for-me hands prompts to an automatic reviewer and keeps workspace-write. Trusting the project also helps, because untrusted projects use the stricter internal untrusted policy. Only --yolo removes both prompts and sandbox.

Is there a Codex equivalent of --dangerously-skip-permissions?#

--dangerously-bypass-approvals-and-sandbox, also accepted as --yolo, is the equivalent: it sets danger-full-access and approval never for the run. The flag conflicts with -a in the interactive CLI. Use it only inside an environment that is sandboxed externally, because Codex then runs commands with your full user permissions.

Why are Codex permissions locked by requirements.toml?#

An administrator's requirements.toml (in /etc/codex/, %ProgramData%\OpenAI\Codex\, a cloud bundle or macOS managed preferences) restricts which approval policies, sandbox modes and permission profiles are allowed. A value outside the list falls back to an allowed one with a startup warning, and profiles it excludes show "Disabled by requirements". Only the administrator can change it.

How do I allow network access in Codex workspace-write mode?#

With the legacy model, set network_access = true under [sandbox_workspace_write]. With permission profiles, add [permissions.<name>.network] with enabled = true to the profile named in default_permissions. Note that an explicit default_permissions = ":workspace" ignores the legacy table, so the network switch must then live in a custom profile that extends :workspace.

Does default_permissions replace sandbox_mode?#

Not yet: both work in 0.159.2. When both are set, the highest-precedence config layer that sets either decides, default_permissions wins inside a single layer, and -s on the command line forces the legacy key for that run. Defining [permissions] profiles without default_permissions is a startup error.

Release-by-release changes: Codex CLI version tracker. All Codex CLI pages: Codex CLI reference index.