OpenAI Codex sandbox

Pin checked 2026-09-28 CST against Sandbox, Agent approvals & security, Permissions (beta profiles), Config reference, Advanced Config, and Config sample.

Not this note: a broad “auto approve / --yolo survey.” That older digest was deleted on purpose — do not recreate it. Auto-review UI/config lives in 2026-09-28 OpenAI Codex Approve for me.

Two layers (plus reviewer)

Control	Question it answers	Key knobs
Sandbox / permission profile	What can commands do technically without leaving the boundary?	`sandbox_mode` + `[sandbox_workspace_write].`, or `default_permissions` + `[permissions.]` (beta; do not mix)
Approval policy	When must Codex stop and create an approval request?	`approval_policy` = `on-request` \| `never` \| `{ granular = { ... } }`
Approvals reviewer	Who answers eligible interactive prompts?	`approvals_reviewer` = `user` (default) \| `auto_review`

Inside the sandbox, routine work runs without prompts. Crossing the boundary (write outside roots, network when blocked, escalated exec, etc.) creates an approval — unless approval_policy = "never". Changing the reviewer does not widen the sandbox.

sandbox / permission profile  →  technical allow boundary
approval_policy               →  whether / which categories prompt
approvals_reviewer            →  user | auto_review (Approve for me)

Legacy sandbox modes (`sandbox_mode`)

Mode	Filesystem	Network (default)	Typical use
`read-only`	Inspect; edits / write-y commands need approval (or fail closed under `never`)	No outbound for sandboxed commands unless separately enabled via other policy paths	Explore, plan, CI read-only
`workspace-write`	Read (where OS allows); write in workspace + temp dirs (`$TMPDIR`, `/tmp` unless excluded); extra dirs via `writable_roots` / `--add-dir`	Off unless `[sandbox_workspace_write] network_access = true`	Default local “Auto” preset
`danger-full-access`	No FS/network sandbox restrictions	Unrestricted (sandbox boundary removed)	Only when host/container already isolates; pairs with `approval_policy = "never"` / `--yolo` for “Full access”

Official low-risk local automation preset:

sandbox_mode = "workspace-write"
approval_policy = "on-request"
# approvals_reviewer = "user"          # default
# approvals_reviewer = "auto_review"   # Approve for me — same sandbox

CLI equivalents:

codex --sandbox workspace-write --ask-for-approval on-request
codex --sandbox read-only --ask-for-approval on-request
# Full access (elevated risk):
# codex --dangerously-bypass-approvals-and-sandbox   # alias: --yolo

Launch heuristics (approvals page): version-controlled folders → recommend Auto (workspace-write + on-request); non-VC folders → recommend read-only. Workspace includes cwd and temp dirs; /status shows roots.

`[sandbox_workspace_write]` keys

Only apply when sandbox_mode = "workspace-write" (legacy path). Documented in config reference / sample:

Key	Type	Role
`writable_roots`	`array` of paths	Extra writable directories beyond workspace cwd
`network_access`	`bool` (default `false`)	Allow outbound network inside workspace-write sandbox
`exclude_tmpdir_env_var`	`bool` (default `false`)	Drop `$TMPDIR` from writable roots
`exclude_slash_tmp`	`bool` (default `false`)	Drop `/tmp` from writable roots

[sandbox_workspace_write]
writable_roots = ["/Users/YOU/.pyenv/shims"]
network_access = false
exclude_tmpdir_env_var = false
exclude_slash_tmp = false

One-off: codex -c sandbox_workspace_write.network_access=true. Session CLI: --add-dir <path> (repeatable) grants extra writable roots alongside the workspace; official CLI reference says prefer --add-dir over --sandbox danger-full-access. Persist the same idea with writable_roots in config.toml.

Protected paths (still read-only under writable roots)

In default workspace-write, these stay read-only under each writable root (recursive):

<writable_root>/.git (dir or pointer file; resolved gitdir: target also protected)
<writable_root>/.agents (if directory)
<writable_root>/.codex (if directory)

Consequence: git commit and similar often still need approval to run outside the sandbox. Prefer rules for allow/prompt/forbid of specific command prefixes rather than broadly expanding access.

Network: grant vs filter

Two separate concerns:

Grant command network: legacy sandbox_workspace_write.network_access = true, or permission-profile permissions.<name>.network.enabled = true.
Filter destinations: features.network_proxy (experimental; off by default) + domain allow/deny. Proxy does not grant access by itself.

Network grant	Proxy	Effect
Off	On or off	Commands stay offline; proxy idle
On	Off	Direct outbound; domain rules not enforced
On	On	Outbound constrained by allowlist-first domain policy

Domain patterns (proxy active): exact host; *.example.com (subdomains only); **.example.com (apex + subdomains); * allow-only global; deny wins. Local/private destinations blocked by default (allow_local_binding = false); allow exact localhost / IP literals when needed.

Proxy does not filter: web search, apps/connectors, MCP transports, browser / Computer Use, Codex model/auth traffic, Codex cloud internet settings — configure those surfaces separately (web_search, mcp_servers, etc.).

Beta permission profiles (alternative system)

Built-ins: :read-only, :workspace, :danger-full-access. Select with default_permissions; define customs under [permissions.<name>] (filesystem + network + optional extends).

Do not combine with sandbox_mode / [sandbox_workspace_write]. If any loaded config sets sandbox_mode, you pass --sandbox, or the selected profile sets sandbox_mode, Codex uses the legacy sandbox path instead of default_permissions (managed allowed_permission_profiles is the exception that forces profiles — strip legacy keys first; needs Codex ≥ 0.138.0).

Rough map:

Legacy `sandbox_mode`	Built-in profile
`read-only`	`:read-only`
`workspace-write`	`:workspace`
`danger-full-access`	`:danger-full-access`

Caveat (OSS issue / migration notes): with a named default_permissions active, legacy [sandbox_workspace_write] network_access may be silently ignored — put network under the active [permissions.<name>.network] instead. Prefer one system consistently.

OS enforcement

Applies to spawned commands (shell, git, package managers, test runners), not only built-in file ops. Platform-native:

Platform	Mechanism	Notes
macOS	Seatbelt via `sandbox-exec` + profile for selected mode	Works out of the box; curated platform policy for tool compatibility
Linux / WSL2	`bwrap` + `seccomp` (Landlock on some fallback paths)	Install distro `bubblewrap`; first `bwrap` on `PATH`; else bundled helper needing unprivileged user namespaces. Ubuntu 24.04 may need `bwrap-userns-restrict` AppArmor profile. WSL1 unsupported since Codex 0.115
Native Windows	Windows sandbox (`windows.sandbox` = `unelevated` \| `elevated` \| `mxc`)	`elevated` strongest (dedicated low-priv users, FS ACLs, firewall); `unelevated` weaker network isolation / may refuse unsupported split policies. PowerShell path = native; WSL2 = Linux sandbox

If policy cannot be enforced, Codex refuses the command rather than silently running unsandboxed (macOS / split policies called out on Permissions “Scope and enforcement”).

Containers: if host blocks namespaces / setuid bwrap / seccomp, either grant capabilities for inner bwrap, or treat the container as the boundary and run --sandbox danger-full-access inside. Reference: OpenAI secure devcontainer (firewall allowlist + bubblewrap). Warning: full-access inside a container can still exfiltrate anything in the container (including Codex credentials).

Debug helpers: codex sandbox macos|linux|windows [--permissions-profile <name>] [COMMAND]... (aliases include codex debug, sandbox seatbelt, sandbox landlock).

Relation to approval_policy and Approve for me

Intent	Sandbox	Approval	Reviewer
Ask for approval (UI)	`workspace-write` / `:workspace`	`on-request`	`user`
Approve for me (UI)	Same sandbox	`on-request`	`auto_review`
Full access (UI)	`danger-full-access`	`never`	N/A (nothing to review)
CI read-only quiet	`read-only`	`never`	—
Auto-review CLI	`workspace-write`	`on-request`	`-c approvals_reviewer=auto_review`

Granular policy can still surface sandbox_approval (and rules / MCP / request_permissions / skill) while auto-rejecting other categories. approval_policy = "untrusted" is retired for Codex / ChatGPT Work; use on-request + optional project trust_level = "untrusted" for stricter project-derived approvals.

Managed orgs: allowed_sandbox_modes, allowed_permission_profiles, allowed_approval_policies, allowed_approvals_reviewers in requirements.toml.

Minimal config cookbook

# ~/.codex/config.toml — interactive workspace agent
approval_policy = "on-request"
approvals_reviewer = "user"
sandbox_mode = "workspace-write"
allow_login_shell = false   # optional hardening

[sandbox_workspace_write]
network_access = false
# writable_roots = ["~/code/shared-lib"]

Permission-profile style (do not also set sandbox_mode):

default_permissions = ":workspace"
# or a custom profile extending :workspace with network.enabled + domains
# + features.network_proxy = true when domain enforcement is required

Sources

https://developers.openai.com/codex/sandboxing
https://developers.openai.com/codex/agent-approvals-security
https://developers.openai.com/codex/permissions
https://developers.openai.com/codex/config-reference (sandbox_mode, sandbox_workspace_write.*, default_permissions, permissions.*, approval_policy, approvals_reviewer, features.network_proxy, windows.sandbox)
https://developers.openai.com/codex/config-advanced
https://developers.openai.com/codex/config-sample
https://developers.openai.com/codex/cli/reference (--sandbox, --add-dir, --ask-for-approval, --yolo)
Related vault note: 2026-09-28 OpenAI Codex Approve for me
Upstream repo (implementation / guardian / sandbox helpers): https://github.com/openai/codex

Gaps / do-not-invent

Did not invent undocumented CLI flags or APIs; stuck to developers.openai.com + config reference.
--add-dir is documented on the official CLI reference (repeatable extra writable roots); pair with writable_roots for persistence. Known issues exist on some platforms/versions where --add-dir and apply_patch interact poorly — verify on your build if writes fail.
Did not deep-dive Windows mxc mode semantics beyond listing the config enum.
Did not paste Landlock/Seatbelt profile source from GitHub (rate/size); OS table is from official approvals + permissions enforcement sections.
Permission profiles remain beta and may change; legacy sandbox_mode still documented and actively used.
Silent ignore of legacy network_access under named default_permissions is a known migration footgun (GitHub issue reports) — confirm on your Codex version if network “does nothing.”

OpenAI Codex sandbox

OpenAI Codex sandbox

Two layers (plus reviewer)

Legacy sandbox modes (sandbox_mode)

[sandbox_workspace_write] keys

Protected paths (still read-only under writable roots)

Network: grant vs filter

Beta permission profiles (alternative system)

OS enforcement

Relation to approval_policy and Approve for me

Minimal config cookbook

Sources

Gaps / do-not-invent

Legacy sandbox modes (`sandbox_mode`)

`[sandbox_workspace_write]` keys