| name | codex-sandbox-preflight |
| description | Use at the start of a Codex session (especially sandboxed) to run `scripts/codex-sandbox-preflight.sh` and interpret network + writable_roots constraints. |
Codex sandbox preflight
When to use
- Start of a new Codex session (default).
- You see sandbox-ish errors like
PermissionError: [Errno 1] Operation not permitted, seccomp, or unexpected “Permission denied” when paths look writable.
- You need to know if network is disabled in the tool sandbox before attempting auth, installs,
git push, etc.
Workflow
- Run the preflight helper:
scripts/codex-sandbox-preflight.sh
- If you’re in a normal shell and want to see what happens when network is enabled inside the sandbox:
scripts/codex-sandbox-preflight.sh --with-network
- Summarize results (don’t paste the full output unless asked):
- Tool sandbox network:
socket() allowed vs blocked (and DNS if allowed).
- Writable roots: whether
~/.config/wbg-auth is writable inside the sandbox.
- Config drift: whether
~/.codex/config.toml is symlinked to dotfiles or has diverged.
Interpretation cheatsheet
INFO- socket() syscall blocked:
- Tool sandbox has network disabled (expected in many sandboxed sessions).
- Avoid network-dependent commands/tools inside the sandbox.
- To allow sandbox network, start Codex with
-c sandbox_workspace_write.network_access=true (still sandboxed, but with egress).
WARN missing_writable_root=$HOME/.config/wbg-auth (or similar) / sandbox write fails for ~/.config/wbg-auth:
wbg-auth will crash on startup due to log file creation.- Fix by adding
~/.config/wbg-auth to sandbox_workspace_write.writable_roots in ~/.codex/config.toml.
Notes / pitfalls
- Running this from inside an already-restricted tool sandbox cannot “prove” that enabling network would work; outer seccomp will still block
socket(). Use --with-network from a normal shell for that.
- This helper must never print secrets; it only checks tool presence, config linkage, writability, and basic DNS.