Sandbox Modes

Feature Definition

A coding agent that can execute arbitrary shell commands and write to disk needs guardrails. Sandbox modes define what the agent is allowed to do — which files it can read, which it can write, whether it can access the network, and what requires human approval. The “mode” is the UX-facing configuration layer that sits above the kernel-level enforcement documented in Platform Isolation.

The challenge is designing a permission model that is both safe by default and not so restrictive that it cripples the agent’s utility. A read-only sandbox prevents the agent from applying any edits. A fully open sandbox lets it rm -rf /. The sweet spot is somewhere in between, and different tools have landed on different answers.

There are two orthogonal axes: filesystem access (what can the agent read and write?) and approval policy (does the human need to confirm actions before they execute?). Some tools conflate these into a single “mode” selector. Others keep them separate. The interaction between them defines the actual security posture. For policy/UX tradeoffs around user approvals, see Permissions and Approval Flow.

Aider Implementation

Pin: b9050e1d5faf8096eae7a46a9ecc05a86231384b

Aider has no sandbox. It does not restrict filesystem access, network access, or command execution at the OS level. Its entire permission model is a single binary flag: --yes-always.

Confirmation Flow

The InputOutput class (aider/io.py:300-906) manages all user confirmations through confirm_ask() (line 866-869):

if self.yes is True:
    res = "n" if explicit_yes_required else "y"
elif self.yes is False:
    res = "n"

The yes attribute has three states:

• True — auto-approve all confirmations (set by --yes-always or --yes)
• False — auto-deny all confirmations
• None — prompt the user each time

When prompted, users can respond with:

• y / n — approve or deny a single action
• a / s — approve all or skip all (for batched confirmations)
• d — “don’t ask again” (persists for the current session via self.never_prompts set)

What Gets Confirmed

Confirmation is requested for specific UI actions, not for all file operations:

• Adding URLs to the chat context
• Adding new files the LLM wants to create
• Running lint or test commands after edits

File writes themselves (applying Search/Replace blocks) execute without confirmation — Aider trusts that the human approved the edit by sending the prompt. The safety net is git: auto_commits (default True in aider/coders/base_coder.py:308-413) commits changes immediately after edits, so git checkout can revert them. dirty_commits (default True) commits any uncommitted changes before the agent starts editing, preserving a clean restoration point.

No Granularity

There is no way to say “allow reads but block writes” or “allow writes to src/ but not to .env”. Aider either runs with full trust or requires manual approval for context changes. The expectation is that the user controls the environment externally (e.g., running Aider inside a container or VM).

Codex Implementation

Pin: 4ab44e2c5cc54ed47e47a6729dfd8aa5a3dc2476

Codex has the most sophisticated sandbox mode system, combining four sandbox policy tiers with three approval presets and platform-specific kernel enforcement.

SandboxPolicy Enum

Defined in codex-rs/protocol/src/protocol.rs:

pub enum SandboxPolicy {
    DangerFullAccess,
    ReadOnly { access: ReadOnlyAccess },
    ExternalSandbox { network_access: NetworkAccess },
    WorkspaceWrite {
        writable_roots: Vec<AbsolutePathBuf>,
        read_only_access: ReadOnlyAccess,
        network_access: bool,
        exclude_tmpdir_env_var: bool,
        exclude_slash_tmp: bool,
    },
}

ReadOnly: The agent can read files but cannot write anywhere. Network access is blocked. The ReadOnlyAccess sub-enum controls read scope:

• Restricted { include_platform_defaults, readable_roots } — only specified paths plus optional platform defaults (system libraries, CA certs)
• FullAccess — unrestricted reads across the entire filesystem

WorkspaceWrite: The agent can read everything and write to the current working directory plus explicitly listed writable_roots. /tmp and the per-user TMPDIR are writable by default (controlled by exclude_tmpdir_env_var and exclude_slash_tmp). Network access is off by default but configurable.

ExternalSandbox: The process is already isolated by an external sandbox (Docker, VM, CI runner). Codex grants full disk access and defers network control to the network_access field.

DangerFullAccess: No restrictions. The name is deliberately alarming.

Protected Subpaths

Even in WorkspaceWrite mode, certain directories within writable roots are always read-only:

• .git/ (entire directory, including hooks)
• .git file pointers (for worktrees and submodules)
• .agents/ directory
• .codex/ directory

This prevents the agent from modifying git hooks or Codex configuration files to escalate privileges in future sessions. Enforcement is in the sandbox setup code that builds the platform-specific policy (Seatbelt require-not clauses on macOS, Landlock path rules on Linux).

CLI Flags

The TUI CLI (codex-rs/tui/src/cli.rs) exposes:

--sandbox <MODE>       # read-only | workspace-write | danger-full-access
-s <MODE>              # Short form
--full-auto            # Convenience: --sandbox workspace-write + approval on-request
--dangerously-bypass-approvals-and-sandbox  # (alias: --yolo) No sandbox, no approvals

SandboxModeCliArg (codex-rs/utils/cli/src/sandbox_mode_cli_arg.rs) is the clap ValueEnum:

pub enum SandboxModeCliArg {
    ReadOnly,
    WorkspaceWrite,
    DangerFullAccess,
}

Note that ExternalSandbox is not available as a CLI argument — it is set programmatically when Codex detects it is running inside a managed environment (VS Code extension, CI).

Approval Presets

Codex bundles sandbox policies with approval policies into three presets (codex-rs/utils/approval-presets/src/lib.rs):

Preset	Label	Sandbox	Approval	Description
read-only	Read Only	ReadOnly	OnRequest	Can read files. Approval required for edits and network.
auto	Default	WorkspaceWrite	OnRequest	Can read/write workspace and run commands. Approval for network or external files. Identical to “Agent mode”.
full-access	Full Access	DangerFullAccess	Never	Can do anything. No approval prompts.

The TUI renders these in a permissions popup (codex-rs/tui/src/chatwidget.rs:open_permissions_popup()). Selecting “Full Access” triggers a separate confirmation dialog (open_full_access_confirmation()). On Windows, if the sandbox level is Unelevated (non-admin), Agent mode shows a degraded sandbox warning.

Approval Policy

The approval policy (AskForApproval) determines when the human must confirm:

• OnRequest — the agent asks for approval before executing tool calls that exceed the sandbox policy (e.g., network access in WorkspaceWrite mode)
• Never — no confirmation prompts (only safe with DangerFullAccess or in trusted CI environments)

Network Access

pub fn has_full_network_access(&self) -> bool {
    match self {
        SandboxPolicy::DangerFullAccess => true,
        SandboxPolicy::ExternalSandbox { network_access } => network_access.is_enabled(),
        SandboxPolicy::ReadOnly { .. } => false,
        SandboxPolicy::WorkspaceWrite { network_access, .. } => *network_access,
    }
}

When network is disabled, the sandbox sets CODEX_SANDBOX_NETWORK_DISABLED_ENV_VAR=1 so child processes can detect the restriction. On macOS, the Seatbelt profile denies network-outbound. On Linux, the seccomp filter blocks socket creation for AF_INET and AF_INET6 (while allowing AF_UNIX for local IPC).

Platform Sandbox Selection

The SandboxManager (codex-rs/core/src/sandboxing/mod.rs) selects the enforcement mechanism:

pub fn select_initial(&self, policy: &SandboxPolicy, pref: SandboxablePreference, ...) -> SandboxType

• SandboxablePreference::Auto — use platform sandbox for ReadOnly and WorkspaceWrite; skip for DangerFullAccess unless network management is needed
• SandboxablePreference::Require — always use platform sandbox
• SandboxablePreference::Forbid — never use platform sandbox (only for testing)

Available SandboxType variants: None, MacosSeatbelt, LinuxSeccomp, WindowsRestrictedToken.

Configuration File

~/.codex/config.toml supports persistent sandbox configuration:

sandbox_mode = "workspace-write"
allowed_sandbox_modes = ["read-only", "workspace-write"]

Per-directory .codex/config.toml overrides are supported. The allowed_sandbox_modes whitelist constrains what modes the TUI can select — if danger-full-access is not listed, it cannot be chosen even from the popup.

OpenCode Implementation

Pin: 7ed449974864361bad2c1f1405769fd2c2fcdf42

OpenCode has no OS-level sandboxing. Instead, it implements a granular permission system with pattern-matching rules that gate tool execution at the application layer.

Permission Actions

Three possible outcomes for any tool invocation (packages/opencode/src/permission/next.ts):

export const Action = z.enum(["allow", "deny", "ask"])

• "allow" — execute immediately, no user interaction
• "deny" — block execution, throw DeniedError
• "ask" — suspend execution, prompt the user via TUI or HTTP API

When asked, users respond with:

• "once" — approve this specific invocation
• "always" — approve all future invocations matching the same pattern (session-scoped)
• "reject" — deny this invocation

Rule Configuration

Rules are defined in opencode.json (packages/opencode/src/config/config.ts:588-654). Each tool can have either a simple action or a pattern-matched ruleset:

{
  "permission": {
    "read": "allow",
    "edit": {
      "*": "ask",
      "src/**": "allow",
      ".env*": "deny"
    },
    "bash": {
      "*": "ask",
      "git *": "allow",
      "npm test": "allow",
      "rm *": "deny"
    },
    "external_directory": "ask",
    "doom_loop": "ask"
  }
}

Tools that support granular pattern rules: read, edit (covers write, patch, multiedit), glob, grep, list, bash, external_directory, lsp, skill, task.

Tools with simple action-only rules: todowrite, todoread, question, webfetch, websearch, codesearch, doom_loop.

Pattern Matching

The evaluate() function (next.ts:236-243) resolves a permission for a given tool and input pattern:

export function evaluate(permission: string, pattern: string, ...rulesets: Ruleset[]): Rule {
    const merged = merge(...rulesets)
    const match = merged.findLast(
        (rule) => Wildcard.match(permission, rule.permission) &&
                  Wildcard.match(pattern, rule.pattern)
    )
    return match ?? { action: "ask", permission, pattern: "*" }
}

Last matching rule wins. Rulesets are arrays of { permission, pattern, action } evaluated in order. If no rule matches, the default is "ask".

Wildcards use shell-glob semantics: * matches any sequence within a path segment, ** matches across segments. Home directory expansion: ~/ and $HOME/ are expanded to os.homedir().

Bash Command Parsing

The bash tool (packages/opencode/src/tool/bash.ts:78-175) uses tree-sitter to parse the command AST and extract meaningful patterns:

for (const node of tree.rootNode.descendantsOfType("command")) {
    // Extract command text for permission check
    patterns.add(commandText)
    always.add(BashArity.prefix(command).join(" ") + " *")
}

This means git commit -m "fix" is checked against the bash rules as the pattern git commit -m fix. The always pattern for “always approve” is git commit *, allowing future git commit invocations without re-prompting.

External directory detection: if the command references paths outside the project root, a separate external_directory permission check is triggered.

Agent-Level Overrides

Permissions can be overridden per agent:

{
  "permission": {
    "bash": { "*": "ask", "git *": "allow" }
  },
  "agent": {
    "build": {
      "permission": {
        "bash": { "git commit *": "ask", "git push *": "deny" }
      }
    }
  }
}

Agent permissions merge with and override global rules.

Session-Scoped Approvals

When a user clicks “always”, the approved pattern is stored in the session’s in-memory approved ruleset (next.ts:196-206). All pending permission requests that now match are auto-resolved. Approvals are not persisted to disk — they reset when the session ends. A TODO comment notes this is intentional pending UI for managing persistent rules.

Doom Loop Detection

If the same tool is called three consecutive times with identical input (packages/opencode/src/session/processor.ts:165-225), a doom_loop permission check fires. This prevents the agent from retrying the same failing command in an infinite loop.

Server API

Permission requests are exposed via HTTP for headless/remote operation:

• GET /permission/ — list pending permission requests
• POST /permission/:requestID/reply — respond with {reply: "once" | "always" | "reject"}

Defaults

If no configuration is provided:

• Most tools: "allow" (reads, glob, grep, list, lsp, etc.)
• doom_loop: "ask"
• external_directory: "ask"
• read with .env* patterns: "deny" (except .env.example)

Claude Code Implementation

Source: Public documentation at code.claude.com (closed source, docs-inferred)

Claude Code’s sandboxing combines OS-level enforcement with a proxy-based network architecture, two sandbox operation modes, and a complementary relationship with the permission system. The sandbox is designed around a specific philosophy: reduce permission prompts by creating defined boundaries where the agent works freely.

Two Sandbox Operation Modes

Claude Code offers two modes, selectable via /sandbox in the TUI:

Auto-allow mode: Sandboxed bash commands run without approval prompts. Commands that cannot be sandboxed (e.g., requiring network access to non-allowed hosts) fall back to the standard permission flow. Explicit ask/deny rules configured by the user are always respected, even in auto-allow.

Regular permissions mode: All bash commands go through the standard permission flow, even when sandboxed. The sandbox still enforces OS-level restrictions, but every command prompts for approval.

In both modes, the sandbox enforces identical filesystem and network restrictions. The difference is only whether sandboxed commands are auto-approved.

Important interaction with permission modes: Auto-allow works independently of the permission mode setting. Even outside “accept edits” mode, sandboxed bash commands auto-approve in auto-allow mode. This means bash commands that modify files within sandbox boundaries execute without prompting, even when file edit tools would normally require approval.

Filesystem Isolation

• Default writes: Read/write access to the current working directory and its subdirectories
• Default reads: Read access to the entire computer, except directories denied by permission rules
• Blocked writes: Cannot modify files outside CWD without explicit permission
• Configurable: Custom allowed/denied paths through settings

Write access confined to the launch directory is a hard security boundary, not just a permission rule. This constraint is enforced at the OS level.

Filesystem deny rules from the permission system (Read and Edit deny rules) are enforced by the sandbox, not configured separately. This means a single Edit(.env*) deny rule blocks both the Edit tool and any bash command that tries to write to .env files.

Network Isolation: Proxy Architecture

Unlike Codex’s seccomp-based network blocking, Claude Code uses a proxy-based approach:

1. A proxy server runs outside the sandbox
2. All outbound network traffic from sandboxed processes routes through the proxy
3. The proxy performs domain-level filtering: only approved domains pass through
4. New domain requests trigger permission prompts to the user
5. All child processes spawned by sandboxed commands inherit the same restrictions

Proxy configuration:

{
  "sandbox": {
    "network": {
      "httpProxyPort": 8080,
      "socksProxyPort": 8081
    }
  }
}

Enterprise environments can implement a custom proxy to decrypt and inspect HTTPS traffic, apply custom filtering rules, log all network requests, and integrate with existing security infrastructure.

Domain allowlists are configured via WebFetch permission rules and the sandbox’s allowedDomains setting.

OS-Level Enforcement

Platform	Mechanism	Prerequisites
macOS	Seatbelt	Built-in, no installation needed
Linux	bubblewrap + socat	apt install bubblewrap socat (or dnf install)
WSL2	bubblewrap (same as Linux)	Same as Linux
WSL1	Not supported	Missing required kernel features
Windows	Not yet supported	Planned

All child processes inherit sandbox restrictions through the OS enforcement mechanism.

Escape Hatch

When a command fails due to sandbox restrictions (network connectivity, incompatible tools), Claude can retry with dangerouslyDisableSandbox parameter. Commands using this parameter go through the normal permission flow (user approval required).

Disable the escape hatch entirely:

{
  "sandbox": {
    "allowUnsandboxedCommands": false
  }
}

When disabled, all commands must run sandboxed or be listed in excludedCommands.

Excluded Commands

Some tools are incompatible with sandboxing:

{
  "sandbox": {
    "excludedCommands": ["docker", "watchman"]
  }
}

Excluded commands always run outside the sandbox and go through the standard permission flow. This is necessary for tools that require system-level access patterns the sandbox cannot accommodate (Docker socket access, filesystem watchers).

How Sandboxing Interacts with Permissions

Sandboxing and permissions are described as “complementary security layers”:

• Permissions control which tools Claude Code can use. Apply to ALL tools (Bash, Read, Edit, WebFetch, MCP, etc.). Evaluated before any tool runs.
• Sandboxing provides OS-level enforcement for Bash commands and their child processes only. Restricts filesystem and network access at the kernel level.

Filesystem restrictions in the sandbox use Read and Edit deny rules from the permission system, not separate sandbox configuration. Network restrictions combine WebFetch permission rules with the sandbox’s allowedDomains list.

Use both for defense-in-depth: permission deny rules block Claude from even attempting access, while sandbox restrictions prevent bash commands from reaching resources outside boundaries even if a prompt injection bypasses Claude’s decision-making.

Security Limitations (Documented)

Claude Code explicitly documents these sandbox limitations:

1. Domain-level network filtering only — the proxy does not inspect traffic content. Users must ensure they only allow trusted domains.
2. Domain fronting — attackers can potentially route through allowed CDN domains to reach unauthorized endpoints.
3. Unix socket access — allowUnixSockets can grant access to powerful system services (e.g., Docker socket grants host system access).
4. Broad domain risks — allowing github.com enables data exfiltration via push.
5. Linux nested sandbox — enableWeakerNestedSandbox for Docker-in-Docker environments considerably weakens security.
6. Filesystem escalation — overly broad write permissions to PATH directories or shell config files enable privilege escalation.

Open Source Sandbox Runtime

The sandbox runtime is published as @anthropic-ai/sandbox-runtime (npm package). It can sandbox arbitrary commands, not just Claude Code:

npx @anthropic-ai/sandbox-runtime <command-to-sandbox>

This is useful for sandboxing MCP servers or other untrusted processes.

---

Pitfalls & Hard Lessons

Application-Layer Sandboxing is Bypassable

OpenCode’s permission system runs in the same process as the agent. A sufficiently creative LLM can circumvent it — for example, using bash to invoke node -e "require('fs').writeFileSync(...)" to write files without going through the edit tool’s permission check. Codex addresses this with kernel-level enforcement (Seatbelt, seccomp, Landlock), where even arbitrary code execution cannot escape the sandbox.

Sandbox Defaults Must Be Safe

Codex defaults to WorkspaceWrite with OnRequest approval — the agent can modify project files but needs approval for network or external writes. This is the right default: useful enough to be productive, restrictive enough to prevent damage. Aider defaults to prompting for everything (yes=None), which is safe but creates approval fatigue. OpenCode defaults to allowing most tools, which is convenient but means a misconfigured rule can silently grant more access than intended.

Protected Paths Are Essential

Codex’s protection of .git/, .agents/, and .codex/ within writable roots prevents a critical escalation vector: the agent modifying git hooks to execute arbitrary code on the next git commit, or modifying its own instructions file to override safety constraints in the next session.

Proxy-Based vs Seccomp-Based Network Isolation

Codex blocks network at the syscall level (seccomp for Linux, Seatbelt for macOS). Claude Code routes all traffic through an external proxy for domain-level filtering. The proxy approach is more flexible: it can integrate with enterprise infrastructure, inspect HTTPS traffic, log requests, and apply domain-level rules that are understandable to non-experts. But it operates at a higher level and has known bypass vectors (domain fronting, DNS tunneling). The seccomp approach is lower-level and harder to bypass, but provides only binary allow/deny for all network rather than domain-level granularity.

Network Is the Forgotten Dimension

Filesystem sandboxing gets the most attention, but network access is equally important. An agent with network access can exfiltrate code, download malicious payloads, or make unauthorized API calls. Codex explicitly models network as a boolean per policy. Claude Code implements domain-level proxy filtering with allowedDomains configuration. OpenCode has webfetch and websearch as separate permission categories but no OS-level network blocking. Aider has no network controls.

Windows Is Hard

Codex’s Windows sandbox (WindowsRestrictedToken) runs in a degraded mode without admin elevation. The TUI warns about reduced protection. This is an honest acknowledgment that cross-platform sandboxing is an unsolved problem — the Windows security model (ACLs, restricted tokens) is fundamentally different from Unix sandboxing (namespaces, seccomp, Seatbelt).

Mode Changes Mid-Session

Codex allows changing the sandbox mode during a session via the TUI permissions popup. This creates a subtle hazard: commands executed before the mode change ran under the old policy. There is no mechanism to retroactively restrict what already happened.

OpenOxide Blueprint

Two-Layer Architecture

Follow Codex’s approach: combine an application-layer permission system with kernel-level sandbox enforcement.

Layer 1: Permission Policy (application-layer, cross-platform)

Define a PermissionPolicy enum:

pub enum PermissionAction {
    Allow,
    Deny,
    Ask,
}

pub struct PermissionRule {
    pub tool: String,        // "bash", "edit", "read", etc.
    pub pattern: String,     // Glob pattern matched against tool input
    pub action: PermissionAction,
}

pub struct PermissionPolicy {
    pub deny: Vec<PermissionRule>,   // Checked first -- always win
    pub allow: Vec<PermissionRule>,  // Checked second
    pub ask: Vec<PermissionRule>,    // Checked third
}

Evaluation follows Claude Code’s deny-first order: deny → allow → ask. Support per-agent overrides by merging rulesets. Store session-scoped “always” approvals in memory; persistent bash command approvals in .openoxide/approvals.toml.

Layer 2: OS Sandbox (kernel-level, platform-specific)

Define a SandboxMode enum combining Codex’s tiers with Claude Code’s operation modes:

pub enum SandboxMode {
    ReadOnly,
    WorkspaceWrite {
        writable_roots: Vec<PathBuf>,
        network: NetworkPolicy,
    },
    ExternalSandbox { network: NetworkPolicy },
    FullAccess,
}

pub enum NetworkPolicy {
    /// No outbound network access (seccomp block)
    None,
    /// Proxy-based domain filtering (Claude Code pattern)
    Proxy {
        http_port: u16,
        socks_port: Option<u16>,
        allowed_domains: Vec<String>,
    },
    /// Full network access
    Full,
}

pub enum SandboxAutoApprove {
    /// Auto-allow sandboxed bash commands (Claude Code auto-allow mode)
    AutoAllow,
    /// All commands go through permission flow (Claude Code regular mode)
    RequireApproval,
}

Map to platform enforcement:

• Linux: landlock crate for filesystem rules, seccomp-bpf for syscall filtering, optional bubblewrap for namespace isolation. Proxy process for network domain filtering.
• macOS: Generate Seatbelt profiles dynamically (.sbpl strings passed to sandbox-exec). Proxy process for network domain filtering.
• Windows: Restricted tokens + Job objects (degraded mode, warn user). Planned.

Proxy-Based Network Filtering

Add a proxy component (Claude Code pattern) alongside seccomp-based network blocking:

1. Spawn a proxy process outside the sandbox
2. Configure sandboxed processes to route traffic through the proxy
3. Proxy performs domain-level filtering against allowed_domains
4. Unknown domains trigger permission prompt to user
5. User can allow once, allow permanently, or deny

This provides domain-level granularity that seccomp alone cannot offer. Use seccomp as the hard floor (block if proxy is bypassed) and the proxy as the user-facing control surface.

Excluded Commands

Support excluded_commands in config for tools incompatible with sandboxing:

[sandbox]
excluded_commands = ["docker", "watchman"]

Excluded commands always run outside the sandbox and go through the standard permission flow.

Escape Hatch

Support dangerously_disable_sandbox parameter on bash tool calls (Claude Code pattern). Commands using this parameter go through normal permission flow. Disable with:

[sandbox]
allow_unsandboxed_commands = false

Protected Paths

Always protect within any writable root:

• .git/ and .git file pointers
• .openoxide/ (configuration)
• AGENTS.md, CLAUDE.md, CONTEXT.md (instruction files)

CLI Interface

openoxide --sandbox read-only
openoxide --sandbox workspace-write
openoxide --sandbox full-access
openoxide --full-auto          # workspace-write + auto-approve
openoxide --yolo               # full-access + no approvals (warns loudly)

Configuration

Support ~/.openoxide/config.toml and per-project .openoxide/config.toml:

[sandbox]
mode = "workspace-write"
allowed_modes = ["read-only", "workspace-write"]
network = false

[permissions]
default = "ask"

[[permissions.rules]]
tool = "bash"
pattern = "git *"
action = "allow"

[[permissions.rules]]
tool = "edit"
pattern = ".env*"
action = "deny"

Crates

• landlock — Linux filesystem access control
• seccompiler or libseccomp — Linux syscall filtering
• clap — CLI argument parsing with ValueEnum
• globset — fast glob matching for permission patterns
• tree-sitter + tree-sitter-bash — bash command parsing for pattern extraction
• serde + toml — configuration parsing