Codex Sandbox & Approval Modes: Full Guide (2026)

- Codex's sandbox/approval mechanics (and the newer Permission Profiles layer) change fast, and the official docs are currently split across multiple paths on learn.chatgpt.com; the details below were cross-checked against the official docs at the time of writing (08/2026) - verify the live docs before you depend on them.

Sandbox mode vs. approval policy - two different questions

Codex asks itself two completely separate questions before doing anything: "What am I ALLOWED to do?" (sandbox mode) and "When must I ASK first?" (approval policy). Per the official learn.chatgpt.com/codex/sandboxing docs, the two layers operate independently - a wide-open sandbox doesn't mean Codex stops asking you, and a strict approval policy doesn't mean Codex is automatically limited in what it can touch.

New to Codex? Read what OpenAI Codex is before this configuration deep-dive. One line to avoid confusion: this is Codex's own permission system - it has nothing to do with installing AgentKit on top of it.

The three sandbox modes

Sandbox mode decides what Codex can touch on your machine WITHOUT waiting for you to confirm. Per the official sandboxing docs (accessed 08/2026), there are three levels:

workspace-write is what Codex picks by default when you don't specify anything - it's also what I use for most everyday coding, since it's wide enough for real work without opening up the whole machine.

Quick example: open Codex in a repo you're already coding in, change nothing, and it defaults to workspace-write - free to edit files inside the repo. But if it tries to write outside that scope (say, touching ~/.ssh/ or another system directory), that's an out-of-sandbox action - it gets blocked outright or triggers a separate ask step, depending on whatever approval policy is set at the same time.

The three approval policies

Approval policy decides when Codex must STOP and ask you, completely separate from what it's allowed to do. Per the official agent approvals & security docs (accessed 08/2026), there are three levels:

The part most guides miss: the official docs state on-request is the default "for version-controlled folders" - not an unconditional default for every folder. Nearly every other guide I checked (in both languages) skips that condition. If you're running Codex outside a git-tracked directory, don't assume on-request is active - check your actual config.

How to switch modes - /permissions, CLI flags, config.toml

Three common ways to set sandbox mode + approval policy:

• In-session (CLI): type /permissions to open the picker and choose directly.
• IDE/desktop: a permission control right in the composer.
• Startup flags: --sandbox and --ask-for-approval.
• Persistent config: the sandbox_mode and approval_policy keys in ~/.codex/config.toml.

A real example for a CI pipeline (nobody around to answer prompts):

codex --sandbox read-only --ask-for-approval never

This pair works for non-interactive runs because Codex never stops to wait for input (never), while read-only keeps it from writing anything unexpected. This configuration pairs directly with how you set up AGENTS.md for Codex - see the AGENTS.md guide for Codex to combine both into one workflow.

Permission Profiles - the newer configuration layer

Beyond the classic sandbox_mode/approval_policy pair above, Codex has a newer configuration layer: Permission Profiles, confirmed via a direct fetch of learn.chatgpt.com/docs/permissions (accessed 08/2026). How it works:

• The default_permissions key points to a built-in or custom profile.
• Three built-in profiles: :read-only, :workspace, :danger-full-access - roughly matching the three sandbox modes above, just under different names.
• You can write your own profile with a [permissions.<name>] table, declaring which paths are readable, writable, or explicitly denied.
• Network access is split out: network.enabled (network on/off) is separate from features.network_proxy (routed through a controlled proxy).

Honestly: almost nobody covers this in the English or Vietnamese search results I checked while researching this piece - only one article mentions it, and in isolation, never placed next to the sandbox_mode/approval_policy pair for comparison. And one thing the official docs do not spell out: precedence if you set both default_permissions and sandbox_mode/approval_policy at once. Some unofficial sources guess that sandbox_mode wins, but I couldn't find a primary docs page confirming that directly - so don't treat it as fact. The safe move in practice: pick one system and stay consistent - either the full legacy pair or full Permission Profiles, don't mix them.

A conceptual example to picture the real value of this layer (not confirmed official field syntax): you want a profile that reads the entire repo but can only write to a logs/ directory, while explicitly denying a couple of sensitive paths like .env or .ssh/ even though they'd otherwise fall inside the broader read scope. That's per-path control the classic sandbox_mode/approval_policy pair (only three broad levels) can't do. Verify the exact field syntax against the live docs before relying on it, since this is a recently added part of the documentation.

Decision table - which mode for which task

This is the table I actually use to decide in under a minute, instead of re-thinking it every time I open Codex:

One line to remember: never pair danger-full-access with never/--yolo outside a disposable environment. It's the only row in this table that trades away both safety layers at once.

The production-safety lesson - a real slap

The table above sounds reasonable on paper, but the reason it exists isn't theoretical. This site's own how to use /goal effectively article tells "Slap #1": the goal was written clearly - only deploy to staging - but after a few auto-compacts, the agent drifted out of context, forgot the boundary, and deployed straight to production, even with a hook reminding it of the task after every compact.

That's exactly the failure this decision table prevents: the safety line has to live in a real sandbox_mode/approval_policy (a technical limit Codex must obey), not in a note inside a prompt or goal (something an agent can forget after enough context compaction). If your production environment is anywhere within Codex's reach, don't set approval_policy = never for that scope, no matter how sure you are you already told it not to.

In other words, the decision table above isn't a theoretical exercise to hang on a wall. It's the technical answer to the exact question Slap #1 raises: how do you stop a persistent agent that has drifted out of context from touching something it shouldn't. A prompt reminder can be forgotten; a limit set in sandbox_mode/approval_policy cannot.

AgentKit runs inside whichever mode you choose

To be straight about the boundary: AgentKit doesn't touch or bypass Codex's sandbox or approval policy. It's just a skills/workflow layer that runs inside whatever mode is currently active - if you set read-only + untrusted, AgentKit is bound by that exact same limit, with no special privilege of its own. Installing for Codex: ak kit init engineer --target codex, then call $ak:cook inside a new Codex session - see how to use AgentKit with Codex for the full walkthrough.

Frequently asked questions (FAQ)

What's the default Codex sandbox mode?

workspace-write - Codex can read/write inside the current workspace directory, without free access to the whole system. It pairs with the default approval policy, on-request, for version-controlled folders.

Does on-request always ask before every command?

No. on-request lets Codex decide for itself which commands are safe to run directly, and only asks when it judges a command risky or outside the current sandbox scope - unlike untrusted, which asks before most commands.

What's the difference between danger-full-access and --yolo?

danger-full-access is one value of sandbox_mode (it removes the filesystem boundary). --yolo (the bypass-both flag) goes further - it bundles the widest sandbox with a never approval policy into one flag, making it riskier than danger-full-access alone. Confirm the exact flag name on your install before using it, since this surface changes often.

Can you use Permission Profiles and sandbox_mode together?

Technically you can declare both, but the official docs don't spell out which one wins in a conflict. Don't treat any precedence claim as confirmed - the safe approach is to pick one system (legacy or Permission Profiles) and stay consistent.

Which mode should you use for CI/CD?

read-only (or a narrowly scoped workspace-write) paired with never - since nobody is there to answer prompts in a pipeline, approval has to be never, so compensate with the tightest sandbox that still works.

Does /permissions permanently change my config.toml?

That's a detail to verify live before depending on it - behavior may differ between a session-only change and something actually written back to config.toml. The safest check is to open config.toml after switching via the picker and confirm for yourself whether it was saved.

Conclusion

Codex's safety model comes down to two independent layers: sandbox mode (what it can do) and approval policy (when it must ask). The default workspace-write + on-request fits most everyday coding; never pair danger-full-access with never/--yolo outside a disposable environment. Use the decision table above instead of guessing, and remember the lesson from Slap #1: the safety line belongs in configuration, not in a prompt note.