Skip to main content
Codex implements defense-in-depth sandboxing to isolate AI-executed commands from sensitive system resources, using platform-native security primitives.

​
Overview

All commands executed by Codex run inside a sandbox that restricts:
  • Filesystem access — Read-only by default, configurable write permissions
  • Network access — Optional restrictions or proxy routing
  • Process capabilities — Reduced privileges and system call filtering
  • Protected paths — .git, .codex always read-only even in writable roots

macOS

Seatbelt sandbox profiles via /usr/bin/sandbox-exec

Linux

Landlock LSM + Bubblewrap container isolation

Windows

Process isolation and token restrictions

​
Sandbox Modes

Codex provides three sandbox policies:

​
Read-Only (Default)

read-only

Maximum security: entire filesystem is read-only, network blocked.Use case: Exploring unfamiliar code, running untrusted prompts
codex --sandbox read-only

​
Workspace Write

workspace-write

Balanced security: write access within workspace, network optional.Use case: Active development, file modifications needed
codex --sandbox workspace-write
Protected paths (always read-only):
  • .git directory or pointer file
  • Resolved gitdir: target
  • .codex directory

​
Danger Full Access

danger-full-access

No sandbox enforcement: full system access.Use case: Running in external container/VM, advanced users
codex --sandbox danger-full-access
Only use this mode if you are already running Codex inside a container or other isolated environment.

​
Platform Implementations

​
macOS (Seatbelt)

Codex uses Apple’s Seatbelt sandbox via /usr/bin/sandbox-exec.
Location: codex-core expects /usr/bin/sandbox-execFeatures:
  • Network access control via SandboxPolicy
  • Filesystem read/write roots configuration
  • Protected path enforcement (.git, .codex)
  • Seatbelt profile generation at runtime
Seatbelt supports macOS-specific permission extensions:No extension profile:
  • Legacy default preferences read access (user-preference-read)
Extension profile with no macos_preferences grant:
  • No preferences access clauses added
macos_preferences = "readonly":
  • cfprefs read clauses
  • user-preference-read operation
macos_preferences = "readwrite":
  • All readonly clauses
  • user-preference-write operation
  • cfprefs shm write clauses
macos_automation = true:
  • Broad Apple Events send permissions
macos_automation = ["com.apple.Notes", ...]:
  • Apple Events send only to listed bundle IDs
macos_accessibility = true:
  • com.apple.axserver mach lookup
macos_calendar = true:
  • com.apple.CalendarAgent mach lookup
Test sandbox behavior with:
codex sandbox macos [--full-auto] [--log-denials] [COMMAND]...

# Legacy alias
codex debug seatbelt [--full-auto] [--log-denials] [COMMAND]...
Flags:
  • --full-auto — Run command automatically
  • --log-denials — Log all denied operations

​
Linux (Landlock + Bubblewrap)

Codex uses a dual-mode Linux sandbox with legacy and modern pipelines.
Crate: codex-linux-sandboxProduces:
  • Standalone codex-linux-sandbox executable (bundled with npm CLI)
  • Library crate exposing run_main() for arg0 routing
arg0 Routing: When the binary detects arg0 is codex-linux-sandbox, it executes sandbox logic instead of normal CLI.
Original implementation using Landlock LSM and mount namespaces.Features:
  • Landlock filesystem restrictions
  • Mount protection
  • Default when use_linux_sandbox_bwrap feature is off
Standardized container-based isolation using vendored bubblewrap.Feature gate: use_linux_sandbox_bwrap (temporary during rollout)CLI flag: -c features.use_linux_sandbox_bwrap=trueIsolation mechanisms:
  1. Process hardening:
    • PR_SET_NO_NEW_PRIVS applied in-process
    • seccomp network filter
  2. Filesystem isolation:
    • Read-only by default: --ro-bind / /
    • Writable roots: --bind <root> <root>
    • Protected subpaths re-applied: --ro-bind for .git, gitdir:, .codex
    • Symlink blocking: mount /dev/null on symlinks or missing components
  3. Namespace isolation:
    • PID namespace: --unshare-pid
    • Network namespace: --unshare-net (when network restricted)
    • Fresh /proc: --proc /proc (skip with --no-proc in restricted containers)
  4. Managed proxy mode:
    • --unshare-net + internal TCP→UDS→TCP bridge
    • Tool traffic reaches only configured proxy endpoints
    • seccomp blocks new AF_UNIX/socketpair creation for user command
Test sandbox behavior with:
codex sandbox linux [--full-auto] [COMMAND]...

# Legacy alias
codex debug landlock [--full-auto] [COMMAND]...
Flags:
  • --full-auto — Run command automatically

​
Vendored Bubblewrap

Codex vendors bubblewrap for consistent behavior across distributions.Location: codex-rs/vendor/bubblewrap/The vendored build ensures Codex doesn’t depend on system package versions.

​
Windows Sandbox

Platform-specific process isolation for Windows.
Crate: codex-windows-sandbox (inferred from Cargo.toml)Testing:
codex sandbox windows [--full-auto] [COMMAND]...
Setup: App-server exposes windowsSandbox/setupStart for elevated/unelevated modes.

​
Process Hardening

All Codex processes apply security hardening pre-main.

codex-process-hardening

Cross-platform hardening applied via #[ctor::ctor] before main().Hardening steps:
  1. Disable core dumps
    • Prevents process memory dumps
    • Protects sensitive data (API keys, tokens)
  2. Disable ptrace attach (Linux/macOS)
    • Blocks debugger attachment
    • Prevents runtime inspection
  3. Remove dangerous environment variables
    • LD_PRELOAD — Prevents shared library injection
    • DYLD_* — Blocks macOS dynamic linker attacks
Usage:
#[ctor::ctor]
fn harden() {
    codex_process_hardening::pre_main_hardening();
}

​
Execution Policy

Codex tracks command trust decisions via execution policies.
Modern execution policy management.Features:
  • Command allow-lists
  • Session-scoped approvals (acceptForSession)
  • Persistent trust decisions
  • Amendment proposals from approvals
Legacy execution policy support for backwards compatibility.

​
Approval Flows

Codex implements interactive approval for sensitive operations.

​
Command Approvals

1

Command proposed

Agent proposes a shell command.
2

Approval requested

Based on approval_policy config, Codex may request approval.Available decisions:
  • accept — Run this command once
  • acceptForSession — Trust for current session
  • acceptWithExecpolicyAmendment — Add to allow-list
  • applyNetworkPolicyAmendment — Allow network host
  • decline — Reject command
  • cancel — Cancel entire turn
3

Command executed

If approved, command runs in sandbox with configured permissions.
4

Result returned

Output, exit code, and duration returned to agent.

​
File Change Approvals

1

Changes proposed

Agent proposes file modifications (edits, creates, deletes).
2

Diff shown

User sees unified diff of all changes.
3

Approval requested

User accepts or declines the entire patch.Available decisions:
  • accept — Apply changes
  • decline — Reject changes
4

Patch applied

If approved, changes written to disk.

​
Network Access Control

Codex supports multiple network access modes: 
[sandbox]
network_access = "restricted"

​
Managed Proxy Mode

Linux bubblewrap pipeline supports managed proxy routing:
  1. Network namespace isolation — --unshare-net
  2. Internal bridge — TCP→UDS→TCP routing
  3. Endpoint filtering — Only configured hosts reachable
  4. seccomp enforcement — Block new socket creation after bridge setup

​
Configuration

Sandbox settings are configured in ~/.codex/config.toml: 
# Quick sandbox mode selection
sandbox_mode = "workspace-write"

​
CLI Override

Override sandbox mode per-invocation: 
# Read-only
codex --sandbox read-only

# Workspace write
codex --sandbox workspace-write

# Danger mode
codex --sandbox danger-full-access
Same setting available via: 
codex -c sandbox_mode=workspace-write

​
External Sandbox Mode

For pre-sandboxed environments (containers, VMs):
Tell Codex it’s already sandboxed externally:
{
  "sandboxPolicy": {
    "type": "externalSandbox",
    "networkAccess": "enabled"
  }
}
Behavior:
  • Codex won’t enforce its own sandbox
  • Agent sees full filesystem access in context
  • networkAccess state passed through environment context
Use cases:
  • Docker containers
  • Kubernetes pods
  • VMs with dedicated Codex instances

​
Testing Sandboxes

Codex provides dedicated commands to test sandbox behavior: 
codex sandbox macos [--full-auto] [--log-denials] [COMMAND]...
Flags:
  • --full-auto — Automatically run the command (non-interactive)
  • --log-denials — Log all denied operations (macOS only)
Example usage: 
# Test file write restrictions
codex sandbox linux --full-auto touch /tmp/test.txt

# Test network access
codex sandbox macos --log-denials curl https://example.com

​
Security Properties

Defense in Depth

Multiple security layers:
  • Process hardening
  • Sandbox isolation
  • Approval flows
  • Execution policies

Principle of Least Privilege

Minimum required permissions:
  • Read-only by default
  • Writable roots explicit
  • Network opt-in
  • Protected paths enforced

Platform-Native

OS security primitives:
  • macOS Seatbelt
  • Linux Landlock/Bubblewrap
  • Windows token restrictions

User Control

User in the loop:
  • Interactive approvals
  • Configurable policies
  • Session-scoped trust
  • Persistent allow-lists

​
Documentation References

For more information, see:
  • Official Sandbox Documentation — Codex sandboxing and approvals
  • docs/sandbox.md — Additional sandbox details
  • codex-rs/core/README.md — Core sandbox expectations
  • codex-rs/linux-sandbox/README.md — Linux implementation details

​
Next Steps

Architecture Overview

High-level architecture of Codex CLI

Rust Crates

Workspace structure and crate organization