Skip to content

Instantly share code, notes, and snippets.

@rtzll

rtzll/codex-sandboxing.md

Created January 17, 2026 15:54
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save rtzll/8ec03ad8a4cca3ae43ce3db7eb7dcc09 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save rtzll/8ec03ad8a4cca3ae43ce3db7eb7dcc09 to your computer and use it in GitHub Desktop.
Download ZIP
Raw
codex-sandboxing.md

Codex Sandboxing

2026-01-17 - created by codex

This report explains how sandboxing is implemented in this repo and what it implies for Codex usage as a terminal coding agent. It’s written for a software engineer who is new to sandboxing and this codebase.

1) Mental Model (High-Level)

Codex’s sandboxing is policy-driven and platform-specific:

  • Policy says what should be allowed (read-only, workspace-write, external-sandbox, danger-full-access, network on/off).
  • Platform implementation enforces policy using OS mechanisms (macOS Seatbelt, Linux Landlock+seccomp, Windows restricted token/ACLs).
  • Execution pipeline converts a “command spec” into a platform-specific sandboxed spawn, runs it, and detects denials.

The core crate chooses and applies sandboxing per command, and can sometimes retry commands without sandboxing if approvals allow.

2) Policy Layer (What Gets Allowed)

Policy is defined in codex-rs/protocol/src/protocol.rs:

SandboxPolicy variants

  • read-only: no filesystem writes, no network.
  • workspace-write: writes allowed in cwd and additional configured roots; network is off by default.
  • external-sandbox: Codex does not enforce a sandbox and assumes the caller already sandboxed it; network access is still tracked.
  • danger-full-access: no sandbox at all.

Writable roots in workspace-write

workspace-write always includes:

  • current working directory (CWD),
  • /tmp on Unix (unless excluded),
  • $TMPDIR on macOS (unless excluded),
  • plus any configured writable_roots.

Inside writable roots, .git and .codex are explicitly made read-only subpaths to prevent modifying repo metadata or Codex config even when the workspace is writable.

Implementation: codex-rs/protocol/src/protocol.rs.

Network access flag

The network toggle is part of the policy. When network is restricted, a sandbox marker is injected into the command environment and platform-specific network blocks are applied.

Implementation: codex-rs/protocol/src/protocol.rs, codex-rs/core/src/spawn.rs.

3) Execution Pipeline (Where the Sandbox Is Applied)

3.1 Execution entrypoint

All tool execution runs through codex-rs/core/src/exec.rs:

  • selects a SandboxType based on policy.
  • transforms the command into a platform-specific wrapper via SandboxManager.
  • executes and classifies results, including sandbox denials.

3.2 SandboxManager transformation

codex-rs/core/src/sandboxing/mod.rs:

  • injects env markers (e.g., CODEX_SANDBOX_NETWORK_DISABLED=1).
  • transforms command into a platform-specific wrapper:
    • macOS → sandbox-exec + generated policy text.
    • Linux → codex-linux-sandbox helper + JSON policy.
    • Windows → sandbox enforced in-process at execution time.

3.3 Denial detection

codex-rs/core/src/exec.rs detects “sandbox denied” using:

  • keyword scan in stderr/stdout,
  • SIGSYS checks for seccomp on Linux,
  • exit code heuristics.

This is best-effort and intentionally conservative.

4) Platform Implementations (How Enforcement Works)

4.1 macOS — Seatbelt (sandbox-exec)

Files:

  • codex-rs/core/src/seatbelt.rs
  • codex-rs/core/src/seatbelt_base_policy.sbpl
  • codex-rs/core/src/seatbelt_network_policy.sbpl

Mechanism:

  • Builds a Seatbelt policy dynamically.
  • Inserts writable roots and read-only subpaths.
  • Network rules are appended only if policy enables network access.
  • Uses /usr/bin/sandbox-exec to run the command under this policy.

Key behavior:

  • Default policy is deny by default.
  • It explicitly allows PTYs, basic system calls, and safe sysctls.
  • Writes are allowed only for declared writable roots.

4.2 Linux — Landlock + Seccomp

Files:

  • codex-rs/linux-sandbox/src/landlock.rs
  • codex-rs/linux-sandbox/src/linux_run_main.rs
  • codex-rs/core/src/landlock.rs

Mechanism:

  • codex-linux-sandbox helper applies policy to current thread:
    • Landlock: read everywhere, write only to /dev/null and writable roots.
    • Seccomp: blocks network syscalls (connect, bind, sendto, etc.), allows AF_UNIX only.
  • Then execs the target command.

This enforces both filesystem and network rules inside the kernel.

4.3 Windows — Restricted Tokens + ACLs + Env Shaping

Files:

  • codex-rs/windows-sandbox-rs/src/lib.rs
  • codex-rs/windows-sandbox-rs/src/allow.rs
  • codex-rs/windows-sandbox-rs/src/env.rs
  • codex-rs/windows-sandbox-rs/src/audit.rs

Mechanism:

  • Creates a restricted token (read-only or workspace-write).
  • Computes allowed/denied paths for writable roots, denying .git.
  • Applies “no-network” behavior via env vars, PATH stubs, proxy settings.
  • Optionally audits and applies denies for world-writable locations.

This relies more on token security + filesystem ACLs + environment than a single kernel sandbox primitive.

5) External Sandbox Mode (When Codex Doesn’t Enforce)

If SandboxPolicy::ExternalSandbox is used:

  • Codex does not apply its own platform sandbox.
  • It still communicates network access state to tools and MCP servers.
  • This is for cases where Codex is already running inside a container or VM.

Documentation: codex-rs/app-server/README.md.

6) How Codex Uses This as a Terminal Coding Agent

6.1 What commands are affected

All shell tool calls run through the sandbox pipeline unless:

  • danger-full-access is used,
  • external-sandbox is specified,
  • or the exec policy allows bypass.

6.2 Default behavior

Default policies are conservative:

  • No network access unless explicitly allowed.
  • Write access is limited to the workspace roots.
  • .git and .codex are read-only even in workspace-write.

6.3 Approvals and bypass

The exec policy layer (codex-rs/core/src/exec_policy.rs) and approval system can:

  • deny commands,
  • require approvals,
  • or bypass sandboxing for “allow” rules.

This is a separate layer from the OS sandbox. It’s a policy gate, not enforcement.

7) Implications for Codex Usage

7.1 Practical restrictions you will see

As a terminal agent:

  • Writes outside workspace roots are blocked in workspace-write.
  • Network calls fail in read-only and workspace-write unless enabled.
  • Git metadata is protected: .git (and gitdir targets) are read-only even if the repo is writable.
  • Codex config is protected: .codex is read-only inside writable roots.

7.2 Workflows that will be restricted

  • Running npm install, cargo build with remote dependencies, or fetching packages can fail when network is disabled.
  • Attempting to write into /etc, /usr, or unrelated directories is blocked.
  • Writing into .git hooks or modifying .git internals is denied.

7.3 What cannot be fully restricted (limitations)

There are intentional or practical limitations:

  • Read access is effectively always full. The policy API advertises “full disk read access” (has_full_disk_read_access always returns true). There is no read-only partial filesystem sandbox. See codex-rs/protocol/src/protocol.rs.

  • Sandbox detection is heuristic. Failures are inferred from stderr keywords and exit codes. This can be noisy or miss some cases. See codex-rs/core/src/exec.rs.

  • External-sandbox mode bypasses enforcement. If you choose external-sandbox, Codex does not enforce local sandbox rules.

  • Windows network blocking is mostly env-based. It’s strong but not a kernel-level network filter; some tools might still bypass it if they ignore environment configuration. See codex-rs/windows-sandbox-rs/src/env.rs.

  • No multi-level read restrictions. You cannot say “read only within this subtree” today; only write restrictions are enforced.

8) Configuration and UX Signals

CLI control

codex --sandbox <mode> sets policy quickly:

  • read-only
  • workspace-write
  • danger-full-access

Documented in codex-rs/README.md.

Environment signals

Commands inside the sandbox may receive:

  • CODEX_SANDBOX_NETWORK_DISABLED=1
  • CODEX_SANDBOX=seatbelt (macOS)

These can change runtime behavior (e.g., reqwest disables proxy usage when seatbelt is detected). See codex-rs/core/src/spawn.rs, codex-rs/core/src/default_client.rs.

9) Quick Reference (Key Files)

  • Policy definitions: codex-rs/protocol/src/protocol.rs
  • Sandbox orchestration: codex-rs/core/src/sandboxing/mod.rs
  • Exec pipeline + denial detection: codex-rs/core/src/exec.rs
  • macOS Seatbelt: codex-rs/core/src/seatbelt.rs
  • macOS policies: codex-rs/core/src/seatbelt_base_policy.sbpl, codex-rs/core/src/seatbelt_network_policy.sbpl
  • Linux Landlock + seccomp: codex-rs/linux-sandbox/src/landlock.rs
  • Linux helper: codex-rs/linux-sandbox/src/linux_run_main.rs
  • Windows sandbox core: codex-rs/windows-sandbox-rs/src/lib.rs
  • Windows allow/deny paths: codex-rs/windows-sandbox-rs/src/allow.rs
  • Windows network env: codex-rs/windows-sandbox-rs/src/env.rs
  • Exec policy (approvals): codex-rs/core/src/exec_policy.rs

10) Summary

Codex uses a policy-first model, then enforces that policy using OS-specific sandboxing:

  • macOS → Seatbelt (sandbox-exec)
  • Linux → Landlock + seccomp
  • Windows → restricted token + ACLs + network env shaping

As a terminal agent, Codex will be restricted from writing outside the workspace, blocked from networking by default, and prevented from modifying repo metadata. It cannot restrict read access today, and it relies on heuristics for denial detection.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment