CDX-201a · Module 2

Sandbox Configuration & Tuning

3 min read

The sandbox is Codex's primary safety mechanism. On macOS, it uses Apple's Seatbelt (sandbox-exec). On Linux, it uses Bubblewrap (bwrap). Both restrict filesystem writes to the project directory and block network access by default. The sandbox mode setting in config.toml determines the baseline: workspace-write (default, write within project only), read-only (no writes at all), or no-sandbox (all restrictions removed).

For production-grade setups, workspace-write is the right default. Layer execpolicy rules on top for commands that need network access or special permissions. Reserve read-only for code review and analysis tasks where you want to guarantee Codex cannot modify anything. Use no-sandbox only in throwaway environments like CI containers where the sandbox itself conflicts with the container runtime.

# Profile-specific sandbox configuration
[profile.default]
model = "codex-1"
approval = "suggest"
# workspace-write is the implicit default

[profile.review]
model = "o3"
reasoning_effort = "high"
approval = "suggest"
# read-only for code review — no writes allowed

[profile.ci]
model = "gpt-4.1"
approval = "full-auto"
# In CI containers, sandbox may conflict with Docker
# Only use no-sandbox in disposable environments

Do This

  • Use workspace-write as the default for all development work
  • Use read-only profiles for code review and analysis tasks
  • Restrict no-sandbox to CI pipelines and disposable environments
  • Test sandbox behavior by attempting an out-of-scope write — verify it fails

Avoid This

  • Disable the sandbox because a command failed — fix the execpolicy instead
  • Assume read-only prevents all side effects — commands can still produce network traffic if allowed
  • Run no-sandbox on your development machine with production credentials in scope
  • Forget that sandbox behavior differs between macOS (Seatbelt) and Linux (bwrap)