Skip to main content
Codex executes all commands in a sandbox by default, isolating filesystem access and network operations to protect your system. The sandbox uses platform-specific technologies to enforce security boundaries.

​
Sandbox modes

Codex supports three sandbox modes with increasing levels of access:
Read-only mode permits:
  • Reading files anywhere on the filesystem
  • No write operations
  • Network access (if enabled)
Use for: Code analysis, searching, reviewing
codex --sandbox read-only "analyze the codebase structure"

​
Platform-specific implementation

Codex uses different sandboxing technologies depending on your operating system:

​
Linux: Landlock + seccomp

On Linux, Codex uses Landlock (kernel-level access control) combined with seccomp (system call filtering):
  • Landlock enforces filesystem access rules
    • Available on kernel 5.13+ (full support on 5.19+)
    • Hierarchical path-based access control
    • Restricts file read/write at the syscall level
  • seccomp restricts system calls
    • Blocks network operations when network access is disabled
    • Prevents privilege escalation
    • Filters dangerous syscalls
Bubblewrap pipeline (experimental): Codex also supports Bubblewrap for more comprehensive isolation:
  • Namespace isolation (PID, network, mount)
  • Read-only root filesystem with selective bind mounts
  • Protected paths (.git, .codex) re-bound as read-only
  • Managed network proxy for restricted network access
Enable with: 
codex -c features.use_linux_sandbox_bwrap=true

​
macOS: Seatbelt (App Sandbox)

On macOS, Codex uses Seatbelt, Apple’s sandbox profile system:
  • Enforces filesystem access rules via sandbox profiles
  • Restricts network access when disabled
  • Integrates with macOS security frameworks
  • Uses sandbox-exec to apply profiles
The Seatbelt profile is dynamically generated based on:
  • Sandbox mode (read-only, workspace-write, etc.)
  • Writable roots (cwd and --add-dir paths)
  • Protected paths (.git, .codex, etc.)
  • Network access settings

​
Windows: Restricted tokens + job objects

On Windows, Codex uses restricted tokens and job objects:
  • Restricted tokens limit privileges
    • Removes admin rights
    • Restricts access to sensitive resources
  • Job objects enforce resource limits
    • Process isolation
    • Resource quotas
    • Network policy enforcement
Windows sandboxing supports both elevated and unelevated modes. Use windowsSandbox/setupStart via the app-server API to configure.

​
Protected paths

Even in workspace-write mode, certain paths are always read-only:
  • .git/ - Git repository data
  • .codex/ - Codex configuration and data
  • gitdir: symlinks - Git worktree references
These protections prevent accidental corruption of critical data.
Protected paths are enforced recursively. For example, .git/hooks/ is also read-only.

​
Network access

Network access is controlled independently of filesystem sandboxing: 
# Enable network access
codex -c sandbox_policy.network_access=enabled "fetch latest API docs"

# Disable network access (default in some modes)
codex -c sandbox_policy.network_access=restricted "work offline"

​
Network proxy (Linux Bubblewrap)

When using Bubblewrap with restricted network:
  • Network namespace is isolated via --unshare-net
  • A managed proxy routes allowed traffic
  • TCP connections are bridged through Unix domain sockets
  • seccomp blocks new socket creation after setup
This allows fine-grained network policy enforcement.

​
Additional writable directories

Extend the writable scope beyond cwd: 
codex --add-dir /tmp/scratch --add-dir ~/documents "process data files"
All specified directories:
  • Must be absolute paths
  • Are added to the sandbox’s writable roots
  • Still respect protected path rules

​
Sandbox escalation

When a command needs to escape the sandbox (e.g., to install packages, access /usr/local, or make network requests), the agent can request escalation.

​
How escalation works

1

Agent detects restriction

The command fails due to sandbox constraints (e.g., permission denied, network unreachable)
2

Agent requests approval

Codex prompts you to run the command outside the sandbox:
Command failed in sandbox. Allow running unrestricted?

npm install express

[a] Accept once
[s] Accept for session  
[p] Accept and add to policy
[d] Decline
3

You approve or decline

Choose the appropriate approval level based on trust and scope
4

Command re-runs

If approved, the command executes outside the sandbox with full access

​
Approval integration

Sandbox escalation integrates with the approval system:
  • never - Auto-approve escalation (no sandbox)
  • on-request - Prompt for escalation approval
  • unless-trusted - Always prompt unless covered by policy
  • on-failure - Only prompt after sandbox failures

​
Debugging sandbox issues

If commands fail unexpectedly in the sandbox:

​
Check sandbox status

# View current sandbox mode
codex -c sandbox_policy.mode=read-only --help

# Test a specific command
codex exec "ls -la /etc"

​
Enable full access temporarily

codex --sandbox danger-full-access "install dependencies"

​
Review sandbox logs

On Linux with Landlock: 
# Check kernel support
codex debug landlock

# View sandbox diagnostics
RUST_LOG=debug codex "test command"
On macOS with Seatbelt: 
# Check Seatbelt denials
log show --predicate 'eventMessage contains "Sandbox"' --last 1h

​
Common issues

/usr/local is outside the workspace. Either:
  • Use --add-dir /usr/local to make it writable
  • Use --sandbox danger-full-access for full access
  • Allow the agent to request escalation
Network access may be restricted. Enable with:
codex -c sandbox_policy.network_access=enabled
.git is protected by default. Use danger-full-access or manually run git commands outside Codex.
Landlock requires Linux kernel 5.13+. On older kernels:
  • Upgrade your kernel, or
  • Use danger-full-access mode (no sandbox)

​
Configuration

Configure sandboxing in ~/.codex/config.toml: 
[sandbox_policy]
mode = "workspace-write"  # read-only | workspace-write | danger-full-access
network_access = "enabled"  # enabled | restricted

# Additional writable roots
writable_roots = [
  "/tmp/codex-scratch",
  "/Users/me/data"
]

# Protected paths (added to defaults)
protected_paths = [
  ".env",
  "secrets/"
]

​
Best practices

Use workspace-write by default

Provides good balance between safety and functionality

Enable network selectively

Only enable when tasks require internet access

Review escalation requests

Carefully examine commands before approving escalation

Use full-access sparingly

Reserve danger-full-access for trusted environments only

​
Next steps

Approvals

Configure when to prompt for permission

Non-interactive mode

Use sandboxing in CI/CD