How to think about agent sandboxing: read-only, workspace-write, and when to use each

Sandboxing is the difference between an AI agent that helps and one that hurts. Every coding agent operates with tool access — file reads, file writes, shell commands, network calls. The sandbox decides which of those tools actually work, and under what conditions.

Codex implements sandboxing as a first-class concept with three modes. Each mode is a contract: it says what the agent is allowed to touch, and what happens when it tries to touch something else. Understanding these modes — and more importantly, when to override them per agent — is the foundation of running agents safely.

The three sandbox modes

read-only is the safest default for any agent whose job doesn’t include modifying code. workspace-write is the standard mode for implementation work — the agent can edit project files but can’t touch system config or files outside the repo. full-write exists for setup and operational tasks but should be the exception, not the norm.

How sandbox inheritance works with subagents

When the main thread spawns a subagent, the child inherits the parent’s sandbox policy by default. This is convenient — you don’t need to configure every agent individually — but it means a permissive parent session creates permissive children.

The inheritance chain:

Parent session (workspace-write)
  └── subagent_1 (inherits workspace-write)
  └── subagent_2 (inherits workspace-write)
  └── subagent_3 (inherits workspace-write)

This is fine when every agent does implementation work. It’s dangerous when some agents should only observe.

Per-agent overrides as defense in depth

The fix is explicit sandbox_mode in custom agent definitions. An agent with sandbox_mode = "read-only" stays read-only regardless of what the parent session allows:

name = "pr_explorer"
description = "Read-only codebase explorer for gathering evidence."
model = "gpt-5.3-codex-spark"
sandbox_mode = "read-only"
developer_instructions = """
Stay in exploration mode. Do not propose or make changes.
"""

Even if the parent session runs with workspace-write and --yolo, the explorer cannot write files. The sandbox override is hardcoded in the agent definition — it’s not a suggestion, it’s a constraint.

This matters for two reasons. First, it prevents accidents: a model hallucinating an edit instruction gets blocked at the sandbox layer. Second, it makes agent roles self-documenting: you can tell from the config file whether an agent is supposed to change things or just observe.

The three-agent review pipeline: a worked example

Here’s a concrete sandbox configuration for a code review setup with three custom agents:

Parent session (workspace-write)
  ├── pr_explorer    → sandbox_mode = "read-only"  (hardcoded)
  ├── reviewer       → sandbox_mode = "read-only"  (hardcoded)
  └── ui_fixer       → inherits workspace-write    (can apply fixes)

The explorer and reviewer are hardcoded to read-only. The ui_fixer inherits workspace-write from the parent because its job is to apply the fixes the reviewer identifies. This means:

• The explorer can read the full codebase but can’t accidentally modify a file while tracing execution paths.
• The reviewer can run git diff and read files but can’t edit code it’s reviewing.
• The ui_fixer can apply targeted changes but can’t touch files outside the workspace.

Each agent gets exactly the permissions its role needs, and no more.

Runtime overrides and their scope

Codex reapplies the parent turn’s live runtime overrides when it spawns a child. That includes sandbox and approval choices set interactively during the session — /approvals changes, --yolo mode — even if the custom agent file sets different defaults.

The hierarchy is:

1. Per-agent sandbox_mode (hardcoded in TOML) — strongest, cannot be widened by inheritance
2. Parent session policy — inherited by agents that don’t have a hardcoded override
3. Runtime overrides (/approvals, --yolo) — applied on top of inherited policy

A read-only agent stays read-only regardless of levels 2 and 3. An agent without a hardcoded sandbox inherits whatever the parent is running, including runtime overrides.

Approval routing across sandbox boundaries

In interactive CLI sessions, approval requests can surface from any active agent thread, not just the one you’re looking at. The approval overlay shows which agent is asking:

[pr_explorer] Requests approval to run: npm test
Press 'o' to open thread, 'y' to approve, 'n' to deny

You can switch to the requesting agent’s thread, inspect what it’s doing, and decide. This matters because the agent asking for approval might be running under a different sandbox mode than the one you’re currently viewing.

In non-interactive flows (CI/CD, codex exec), actions that need fresh approval fail and surface the error to the parent workflow. The sandbox doesn’t silently degrade — it reports what it blocked.

Choosing a mode: the decision framework

The framework simplifies to one question: does this agent’s output include file modifications? If no, start with read-only. If yes, start with workspace-write and only widen to full-write if the agent demonstrably needs system access.

What sandboxes don’t protect against

Sandboxing constrains what files and commands an agent can access. It does not constrain what the agent can say or recommend. A read-only agent can still suggest destructive commands for you to run manually. It can still hallucinate API usage that doesn’t exist. It can still produce incorrect analysis.

Sandboxing is a file-system and process boundary. It sits alongside other safety layers — approval settings, tool allowlists, hook-based validation — but doesn’t replace them. An agent configured with read-only plus a PreToolUse hook that blocks rm and sudo is safer than either mechanism alone.

Getting started in 5 minutes

1. Audit your existing custom agents. Does every agent need the permissions it has?
2. Add sandbox_mode = "read-only" to any agent that shouldn’t modify files.
3. For implementation agents, leave sandbox unset so they inherit parent session policy.
4. Test the configuration by running a review prompt and verifying that explorers and reviewers can’t write files.
5. Add a PreToolUse hook that logs every tool call with the agent name and sandbox mode — this gives you an audit trail for debugging permission issues.

Start with the agents you run most often. A read-only explorer and reviewer are the highest-leverage changes — they prevent the most common class of accidental modification while costing nothing in capability.

Takeaways