Codex CLI approval and sandbox settings explained

Codex CLI has two separate safety controls, and most confusion comes from mixing them up. The official docs split them like this: the sandbox mode is what Codex can do technically when it runs commands, and the approval policy is when Codex must stop and ask you first.

This page covers the values each one takes, the config.toml keys, what "full access" means, and how codex exec differs. I checked the flags against codex --help on Codex 0.167.0 and the settings against OpenAI's docs, linked inline.

Sandbox modes: sandbox_mode

--sandbox (-s) and the sandbox_mode config key take one of three values, described in the sandboxing docs:

• read-only: Codex can inspect files but can't edit them or run commands without approval.
• workspace-write: Codex can read files, edit inside the workspace and run routine local commands. The docs call it the default low-friction mode for local work.
• danger-full-access: no sandbox restrictions, so no filesystem or network boundary.

In workspace-write, the workspace is the current directory plus temporary directories like /tmp, and network access is off by default (see defaults). Paths such as .git, .agents, .codex and .aws inside a writable root stay read-only (protected paths). To allow network access you opt in with sandbox_workspace_write.network_access.

Approval policies: approval_policy

--ask-for-approval (-a) and the approval_policy key currently accept two named values, which is also all codex --help lists:

• on-request: Codex works inside the sandbox and asks when it needs to go beyond it.
• never: Codex doesn't stop for approval prompts. Failures go back to the model instead.

The configuration reference also allows a granular table that keeps some prompt categories interactive and auto-rejects the others. It says untrusted is unsupported and on-failure is deprecated; use on-request for interactive runs and never for non-interactive ones. If an old config still sets untrusted, the docs say it can stop Codex from starting, and give a migration path.

The same settings in config.toml

The approvals page shows these keys in ~/.codex/config.toml. Here is the usual interactive setup:

approval_policy = "on-request"
sandbox_mode    = "workspace-write"

[sandbox_workspace_write]
# network_access = true   # off by default

You can also save presets as profile files. A file named ~/.codex/readonly_quiet.config.toml layers on top of your base config when you run codex --profile readonly_quiet. Any single setting can be overridden per run with -c key=value.

Common combinations

• Auto preset: --sandbox workspace-write --ask-for-approval on-request. Codex edits and runs commands in the workspace on its own, and asks before editing outside it or using the network (docs).
• Read-only with questions: --sandbox read-only --ask-for-approval on-request.
• Read-only, no prompts, for CI: --sandbox read-only --ask-for-approval never. The docs say -a never works with every sandbox mode.
• Automatic review: -c approvals_reviewer=auto_review, or the --approve-for-me flag in codex --help. Eligible requests go to a reviewer agent instead of you (auto-review). The default reviewer is user.

Full access, yolo and bypassing permissions

This is what "full permissions" or "ignore permissions" means in Codex. The docs define full access as sandbox_mode = "danger-full-access" together with approval_policy = "never" (sandboxing). The one-flag version is --dangerously-bypass-approvals-and-sandbox, with the alias --yolo. The approvals page lists it as no sandbox, no approvals, "not recommended". codex --help says it is "intended solely for running in environments that are externally sandboxed".

That is the reasonable use: a throwaway container, a VM or a CI runner, where the isolation is the boundary and Codex's own sandbox would only get in the way. On your normal machine, workspace-write with on-request keeps the sandbox and still lets Codex work without constant prompts.

Full access also changes web search. With --yolo or another full access setting, web search defaults to live results instead of the cache, and the docs warn about prompt injection from live content. Separately, --dangerously-bypass-hook-trust in codex --help skips the hook trust check; the help text says it is for automation that already vets hook sources.

codex exec is different

Per the non-interactive docs, codex exec runs in a read-only sandbox by default. You widen it with --sandbox workspace-write or --sandbox danger-full-access, and the docs say to use the latter only in a controlled environment. --full-auto is no longer supported; use --sandbox workspace-write, or --approve-for-me for automatic review.

On 0.167.0, codex exec --help lists --sandbox but no --ask-for-approval, and the configuration reference says to use never for non-interactive runs. handup's Codex docs go further: in Codex 0.159.2, codex exec forces approval policy never, even with -c 'approval_policy="on-request"'. So codex exec can't pause for an approval at all. Use the interactive CLI for that.

Getting approval prompts off the terminal

With on-request, an approval prompt blocks the terminal you are not looking at. handup moves those prompts to your desktop or phone. Its Codex setup installs a PermissionRequest hook, so when Codex asks for permission the request goes to handup, and you approve or deny it there.

handup integrate codex --dry-run   # preview the changes
handup integrate codex             # install the hook and MCP server
codex --sandbox workspace-write --ask-for-approval on-request

These are the commands from the handup docs. handup integrate codex merges the hook into $CODEX_HOME/hooks.json and the handup MCP server into $CODEX_HOME/config.toml, keeps your other handlers and backs up changed files. handup integrate codex --uninstall removes both. Codex requires you to review and trust a new hook, so approve it in Codex before the first run.

A deny can carry a reason, for example handup deny ID -m 'Use staging instead', and Codex receives it as the decision message. The docs spell out the limits: the hook runs only when Codex actually asks for permission, not for commands the sandbox already allows. It never edits the tool call. If the daemon is unreachable, Codex falls back to its own prompt, and handup never approves in its place.

That also means full access and handup don't mix. Under never or --yolo, Codex asks for nothing, so there is nothing to forward. For those runs, handup's MCP tools let the agent ask on its own before risky steps. See the Codex setup guide for the full flow, or download handup.