windows.sandbox
unsetPublished Jul 15, 2026 · Verified against the official config docs
Picks which native Windows sandbox Codex uses when you run it outside WSL. Set elevated for real isolation built from dedicated low-privilege sandbox users, firewall rules, and filesystem boundaries; unelevated falls back to a restricted token derived from your own account. Unset by default, and it goes in the [windows] table. If Codex keeps dying on Windows with 'setup refresh' errors, this key is where the debugging starts.
Values
windows.sandbox lives in the [windows] table and only matters when Codex runs natively on Windows, not through WSL.
| Value | What you get |
|---|---|
elevated |
Dedicated lower-privilege sandbox users, filesystem permission boundaries, firewall rules, and local policy changes. Needs admin approval for the setup helper. Strongest isolation, and the mode the docs prefer. |
unelevated |
A restricted Windows token derived from your current user, ACL-based filesystem boundaries, and environment-level offline controls. Works when admin approval is blocked. |
Default is unset. Two companions: windows.sandbox_private_desktop (default true) runs the sandboxed child process on a private desktop, and the top-level windows_wsl_setup_acknowledged just tracks whether you acknowledged the WSL setup guidance during onboarding.
[windows]
sandbox = "elevated" # or "unelevated"
sandbox_private_desktop = true # false only for old Winsta0\Default behaviorWhen to change it
- Native Windows with admin rights: set
elevatedand approve the UAC prompt when the setup helper runs. - Locked-down corporate machine where elevation is blocked: set
unelevated. Weaker isolation, but it runs. - A sandboxed tool needs the interactive desktop (window automation, GUI test runners): set
sandbox_private_desktop = falseto get the olderWinsta0\Defaultbehavior back. - Neither mode works: the docs’ own advice is to run Codex in WSL2 instead.
Gotchas
This key owns the noisiest failure class on Windows. windows sandbox: setup refresh failed with status exit code: 1 showed up in 0.95.0 on commands that didn’t request escalation; the same commands passed with escalated permissions (#10601, still open). 0.133.0 broke spawn setup refresh outright, and the only fix in the thread was downgrading to 0.132.0 (#24391). If you see ShellExecuteExW failed to launch setup helper: 1223, that’s Windows error 1223, ERROR_CANCELLED — the UAC prompt for codex-windows-sandbox-setup.exe got declined or blocked (#29072). apply_patch refusing with exit 1 under the default sandbox is #13574.
One more: older threads show experimental_windows_sandbox and elevated_windows_sandbox flags in reporter configs. The current reference only documents windows.sandbox, so don’t copy config out of 2025-era comments.
Related settings
- sandbox_mode sets the policy (read-only, workspace-write, full access);
windows.sandboxsets the mechanism that enforces it on Windows. - approval_policy controls when Codex asks before escalating out of the sandbox, which is the usual workaround while these bugs are open.