sandbox_mode
read-only (per the config-sample; the reference doesn't state one)Published Jul 15, 2026 · Verified against the official config docs
sandbox_mode sets how much of your machine Codex can touch when it runs commands: read-only, workspace-write, or danger-full-access. The reference doesn't publish a default, but the shipped config-sample marks read-only as the default. Most sessions run workspace-write so the agent can actually edit files; danger-full-access turns the sandbox off entirely, so save it for containers and throwaway VMs.
Values
| Value | What Codex can do |
|---|---|
read-only |
Read files anywhere. No writes, no network. |
workspace-write |
Write inside the workspace (your cwd) plus temp dirs. Outbound network stays off unless you enable it. |
danger-full-access |
No sandbox. Full filesystem and network (the name is honest, at least). |
The config reference doesn’t state a default. The config-sample comments read-only as the default, and that’s what ships.
When to change it
- Any session where Codex edits code: set
workspace-write. This is the day-to-day setting. - Commands need the network (
npm install,pip, curl):workspace-writeblocks outbound network by default. Enable it in the companion table rather than jumping to full access. - Codex runs inside a container or disposable VM that already provides the isolation:
danger-full-accessis defensible there and nowhere else.
# ~/.codex/config.toml
sandbox_mode = "workspace-write"
[sandbox_workspace_write]
writable_roots = [] # extra writable dirs beyond the workspace
network_access = false # flip to true for installs inside the sandboxGotchas
Windows is where this key hurts. #10601 (open) is a 0.95.0 regression where non-escalated commands under workspace-write die during sandbox setup with windows sandbox: setup refresh failed with status exit code: 1; the same commands worked in 0.94.0. #13574 reports apply_patch under workspace-write on Windows exiting 1 with no error text, while the same patch works elevated and on macOS.
Also on Windows, the native sandbox has its own switch: the [windows] table’s sandbox key takes unelevated or elevated per the config reference, so sandbox_mode alone doesn’t decide behavior there.
One more: /tmp and $TMPDIR are writable by default in workspace-write — exclude_slash_tmp and exclude_tmpdir_env_var both default to false in the config-sample.
Related settings
- approval_policy sets when Codex pauses to ask before running a command; the two keys work as a pair.
sandbox_workspace_writeholdswritable_roots,network_access, and the tmp-dir excludes that refineworkspace-write.