Sandboxing

Understand Codex’s security model and platform-specific isolation

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

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"

workspace-write

Workspace-write mode (default) permits:

• Reading files anywhere
• Writing files in the working directory (cwd)
• Writing to additional directories specified with --add-dir
• Protected paths like .git/ remain read-only
• Network access (if enabled)

Use for: Development, testing, file modifications

codex --sandbox workspace-write "add unit tests"

danger-full-access

Full-access mode disables the sandbox:

• No filesystem restrictions
• No network restrictions
• Full system access

Only use in trusted environments. The agent can modify any file and execute any command.

codex --sandbox danger-full-access "install system packages"

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

Permission denied writing to /usr/local

/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 connection refused

Network access may be restricted. Enable with:

codex -c sandbox_policy.network_access=enabled

Cannot modify .git directory

.git is protected by default. Use danger-full-access or manually run git commands outside Codex.

Landlock not supported on this kernel

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