OpenAI Codex Sandbox Modes Explained: Auto, Manual and Full Access

Why Codex Even Needs a Sandbox

The first time you point an autonomous coding agent at your actual codebase, a quiet question shows up in the back of your mind: what stops this thing from running rm -rf on the wrong directory, or quietly curling your .env file to some random endpoint because a prompt injection told it to? OpenAI Codex CLI answers that question with a layered sandbox system, not a single on/off switch. It gives you filesystem isolation, network isolation, and a separate approval layer that governs when Codex is allowed to ask you for more rope.

This matters more than it sounds like on paper. Codex isn't just autocompleting lines anymore — it plans multi-step changes, runs shell commands, installs packages, edits multiple files, and executes tests, often without you watching every keystroke. Under the hood, Codex runs commands inside an OS-level sandbox: Seatbelt profiles on macOS, and Landlock plus seccomp on Linux. Docker container isolation is also common in CI environments. These aren't cosmetic restrictions bolted onto the CLI — they're enforced at the kernel or OS boundary, which means a jailbroken prompt can't simply talk its way past them.

The practical upshot is that Codex exposes three main operating modes — often called Auto, Read Only, and Full Access in the UI, with --sandbox and --ask-for-approval flags doing the heavy lifting underneath — plus curated presets that combine both dimensions. If you've been running Codex with --full-auto because it was the first flag that worked, or you've been babysitting every single command with manual approval, there's a good chance you're leaving either safety or productivity on the table. This article walks through exactly how each mode behaves, what flags control them, and how to pick the right one for a given task — from a quick prototype in a throwaway repo to a PR against a production monorepo.

The Two Independent Dimensions: Sandbox and Approval

Before diving into named modes, it helps to understand that Codex CLI actually controls two separate things:

• Sandbox policy — what Codex is *physically allowed to do* on your machine: which directories it can write to, and whether it can reach the network at all. This is enforced by the OS, not by Codex's own judgment.
• Approval policy — when Codex has to *stop and ask you* before proceeding, regardless of what the sandbox would technically allow.

These two are configured independently, and that's the part people miss. You can have a very permissive sandbox with strict approvals (Codex can do a lot, but always asks first), or a very restrictive sandbox with loose approvals (Codex barely needs to ask because it physically can't do much damage anyway).

The sandbox is controlled with --sandbox, which accepts:

# read-only: Codex can read any file, but cannot write anywhere
# and cannot reach the network
codex --sandbox read-only

# workspace-write: Codex can write inside the current project
# directory (and a few OS temp paths), network still blocked
codex --sandbox workspace-write

# danger-full-access: no filesystem or network restrictions at all
codex --sandbox danger-full-access

Approval behavior is controlled with --ask-for-approval (often shortened to -a):

codex --ask-for-approval untrusted   # approve almost everything
codex --ask-for-approval on-failure  # only ask if a sandboxed command fails
codex --ask-for-approval on-request  # Codex decides when it needs to ask
codex --ask-for-approval never       # don't prompt, ever

Everything you see described as "Auto," "Manual," or "Full Access" in the Codex UI and docs is really a named combination of these two knobs, sometimes with the --full-auto and --dangerously-bypass-approvals-and-sandbox convenience flags layered on top.

Manual Mode: Read-Only Sandbox With Approval Gates

Manual mode — technically --sandbox read-only paired with an approval policy that prompts on anything meaningful — is the mode you want when you're exploring a new codebase, doing a security-sensitive review, or simply don't trust the task yet.

In this mode, Codex can freely read files, grep across the repo, and reason about code, but it cannot write to disk and cannot make network calls on its own. Any time it wants to actually change something — edit a file, run npm install, execute a shell command with side effects — it has to stop and present you with the exact command or diff, and wait for your explicit yes.

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

This combination is deliberately conservative. Even a command as innocuous-looking as git status might get flagged for approval under the untrusted policy, because the policy doesn't try to be clever about what's "safe" — it defers almost everything to you. That's the point: in a codebase you don't fully trust, or when you're testing a Codex workflow for the first time, you want maximum visibility before anything touches disk.

The tradeoff is obvious — friction. If you're doing a large refactor that touches forty files, approving each one individually turns Codex from a force multiplier into a slower version of doing it yourself. Manual mode earns its keep specifically in situations where the cost of an unreviewed mistake is high: production infrastructure code, database migration scripts, anything touching authentication or payments, or a repo you just cloned from someone else and haven't audited yet.

A practical pattern is to start a session in manual/read-only mode, let Codex explore and propose a plan, and only escalate to a write-enabled sandbox once you've read and approved that plan.

Auto Mode: Workspace-Write With Smart Approvals

Auto mode is the default sweet spot for most day-to-day work, and it's what you get from the friendly --full-auto flag or by picking "Auto" in the Codex UI. Under the hood it maps to:

codex --sandbox workspace-write --ask-for-approval on-failure

Here, Codex is allowed to write files inside your current working directory (and a small set of OS-managed temp locations) without asking permission for every single edit. It can create files, modify files, delete files scoped to the workspace, and run most shell commands — as long as those commands don't reach outside the sandboxed directory or try to hit the network. Network access stays off by default even in workspace-write, which is an important detail: writing files and calling the internet are treated as separate privileges, not bundled together.

The on-failure approval policy means Codex only interrupts you when something it tried to do actually failed inside the sandbox — for example, a command that needs network access (like pip install reaching PyPI) gets blocked by the sandbox, and only then does Codex surface a request asking whether you want to grant an escalated, one-off exception for that specific command.

# Example: Codex wants to run this, but workspace-write sandbox
# blocks outbound network by default
pip install requests

# Codex will pause and ask something like:
# "This command requires network access, which is currently
#  restricted. Approve running it with network enabled?"

This is the mode that makes Codex feel genuinely autonomous without feeling reckless. You can hand it a ticket — "add pagination to the users endpoint and write tests" — and it will read the relevant files, write new code, run the test suite, iterate on failures, and only tap you on the shoulder when it hits a wall the sandbox put up on purpose. For most feature work, bug fixes, and refactors inside a single repository, this is the mode you should default to.

There's also a middle-ground approval setting worth knowing: on-request, which lets the model itself decide when a command is risky enough to warrant asking, rather than only asking after a hard sandbox failure. This is a bit more chatty than on-failure but slightly more cautious, since Codex can flag things it merely suspects might be sensitive (like a destructive git command) before actually attempting them.

codex --sandbox workspace-write --ask-for-approval on-request

Full Access Mode: When the Sandbox Comes Off Entirely

Full Access is the mode that removes both restrictions at once — no filesystem boundary, no network boundary. It corresponds to:

codex --sandbox danger-full-access --ask-for-approval never

or the single convenience flag that does the same thing:

codex --dangerously-bypass-approvals-and-sandbox

The naming isn't accidental. OpenAI put "dangerous" directly in the flag so it can't be invoked by muscle memory. In this mode, Codex can write anywhere on your filesystem it has OS permissions for, execute arbitrary shell commands, and make arbitrary network requests, all without stopping to ask. There is no safety net beyond your own review of the diff afterward.

This mode has legitimate uses. It's genuinely useful in an already-isolated environment — a disposable Docker container, a throwaway VM, a CI runner that only exists for the duration of one job — where the "sandbox" is really the entire machine, and that machine is expendable. It's also the mode you reach for when a task fundamentally requires crossing the workspace boundary: installing a global system dependency, writing to a config file in your home directory, or hitting an internal API during a scripted integration test.

What it should not be used for is your daily driver on a laptop with your SSH keys, cloud credentials, and personal files sitting a few directories up from the project root. A prompt injection hidden in a scraped web page, a malicious dependency's postinstall script, or simply a confused multi-step plan can do real damage with zero warning in this mode, because there's nothing left to warn you — you already told Codex not to ask.

# Reasonable use: inside an ephemeral container built just for this task
docker run --rm -it my-codex-sandbox-image \
  codex --dangerously-bypass-approvals-and-sandbox \
  "run the full integration suite and fix any failing tests"

If you find yourself reaching for Full Access outside of a genuinely disposable environment because Auto mode's prompts are annoying you, that's a signal to fix the underlying friction — usually by pre-approving a specific command pattern or restructuring the task — rather than removing the sandbox altogether.

Configuring Modes Through config.toml Instead of Flags

Typing --sandbox workspace-write --ask-for-approval on-failure on every invocation gets old fast. Codex CLI reads persistent configuration from ~/.codex/config.toml, and you can set your preferred defaults there so a bare codex invocation already behaves the way you want.

# ~/.codex/config.toml

# Default sandbox and approval behavior for this machine
sandbox_mode = "workspace-write"
approval_policy = "on-failure"

# Fine-grained control over what workspace-write actually allows
[sandbox_workspace_write]
network_access = false
writable_roots = ["/Users/pramod/projects"]

# Per-project overrides — useful if one repo needs different rules
[projects."/Users/pramod/projects/internal-billing-service"]
sandbox_mode = "read-only"
approval_policy = "untrusted"

Notice the writable_roots array under sandbox_workspace_write — this is how you extend the write boundary beyond just the current directory, for example if your project writes build artifacts to a shared cache folder outside the repo. You can also flip network_access to true for a specific project if that project's normal workflow genuinely requires hitting package registries or internal APIs, without having to grant full filesystem access to get it.

Per-project overrides are worth setting up deliberately rather than relying on memory. A pattern that works well in practice: keep the global default at workspace-write / on-failure for personal and experimental repos, then explicitly pin sensitive repos — anything touching secrets, billing, infra-as-code, or auth — to read-only / untrusted in the [projects."..."] table, so you can never accidentally run a looser session against them just because that was your last global setting.

Practical Recipes for Common Scenarios

Putting the flags together, here's how the modes map onto real workflows.

• First look at an unfamiliar repo: codex --sandbox read-only --ask-for-approval untrusted — let Codex read and summarize without any write risk.
• Day-to-day feature work in your own project: codex --full-auto (equivalent to workspace-write + on-failure) — fast, but network calls still require a nod from you.
• Installing dependencies as part of a task: stay in workspace-write, but expect and accept the network approval prompt rather than jumping straight to full access.
• Running Codex inside CI on a fresh runner: danger-full-access with never approvals is reasonable, because the "sandbox" is the ephemeral runner itself.
• Reviewing a security-sensitive PR: read-only with untrusted, always — you want every proposed change surfaced as a diff before anything touches disk.
• Long unattended agent runs (e.g., overnight refactor jobs): workspace-write with on-request, so Codex can self-flag genuinely risky commands without needing you awake at 2 a.m., but still can't reach the network or leave the directory unsupervised.

A command-line shortcut worth memorizing for quick escalation mid-session, instead of restarting Codex with different flags, is the interactive approval prompt itself — when Codex asks to run a blocked command, you can typically approve it once, approve it for the rest of the session, or reject it outright. Reaching for "approve for session" on a specific, well-understood command (like enabling network for a known npm install) is a much smaller risk than starting the whole session in Full Access mode.

Common Mistakes and How to Avoid Them

The most common mistake is treating --full-auto as "the safe default" because it sounds tame compared to danger-full-access. It's a reasonable default for trusted, low-stakes repos, but people forget that "auto" still means Codex is writing to disk without per-edit confirmation — it's not a read-only preview mode.

The second common mistake is running Full Access on a real laptop "just for this one task" and forgetting to revert. Sandbox settings configured via flags don't persist beyond that invocation, but if someone bakes sandbox_mode = "danger-full-access" into their global config.toml to get past a one-time annoyance, every future session inherits that risk silently. If you ever need to drop to full access, prefer doing it as a one-off flag on a single command rather than a persistent config change.

Third, people conflate filesystem write access with network access and assume granting one grants the other. They don't. workspace-write explicitly keeps network access off unless you set network_access = true or approve an escalation request — this is precisely why a stray pip install or curl inside an otherwise-normal Auto-mode session triggers a prompt instead of silently succeeding or silently failing.

Finally, don't assume the sandbox protects against everything. OS-level sandboxing (Seatbelt on macOS, Landlock/seccomp on Linux) stops filesystem and network escapes, but it doesn't stop Codex from writing genuinely bad code inside the directories it's allowed to touch, or from accidentally deleting a file you cared about that happens to live inside the workspace. The sandbox is a blast-radius control, not a correctness guarantee — you still need to read the diffs.

Bringing It All Together

Codex CLI's sandbox design reflects a mature answer to a real problem: agentic coding tools need to move fast, but "move fast" and "unrestricted filesystem plus network access" shouldn't be the same setting. By splitting the decision into a sandbox policy (read-only, workspace-write, danger-full-access) and an approval policy (untrusted, on-failure, on-request, never), Codex gives you a genuinely tunable dial instead of a binary trust decision.

The practical rule of thumb: default to workspace-write with on-failure for everyday work, drop to read-only with untrusted whenever you're in unfamiliar or sensitive territory, and reserve danger-full-access for environments that are disposable by design — containers and CI runners, not your primary machine. Configure your defaults once in ~/.codex/config.toml, override per-project where the stakes differ, and resist the urge to reach for full access just because a prompt was mildly inconvenient.

If you want to go deeper than flags and config files — actually building repeatable, safe agentic workflows with Codex CLI across real projects, from sandbox configuration to multi-file refactors to CI integration — that hands-on depth is exactly what we cover in the OpenAI Codex CLI Tutorial course on teachyou.ai.