Codex sandboxing: separate filesystem scope from approvals

A Codex permission decision has two independent parts: what the operating system sandbox permits, and whether Codex may ask to step outside that boundary. Treating those controls as one switch creates both false confidence and unnecessary full-access sessions.

The sandbox enforces the boundary

Codex exposes three sandbox modes. The mode controls filesystem writes and network access at the process boundary; instructions in a prompt do not replace that enforcement.

read-only does not mean “shell disabled.” Read operations still run. A command that needs to write, open the network, or cross another restricted boundary may require an approval, depending on the approval policy.

workspace-write is the useful implementation default. Network access remains a separate opt-in:

sandbox_mode = "workspace-write"

[sandbox_workspace_write]
network_access = true

This grants outbound network access without granting arbitrary writes outside the workspace.

Approval policy controls escalation

The approval policy determines whether Codex may pause and request permission for an operation outside the active sandbox. It does not change the sandbox by itself.

A read-only session with approvals available can request a write. A workspace-write session with approvals disabled cannot escape its workspace merely because a prompt asks it to. Full access removes the sandbox boundary; pairing it with an approval policy of never removes the interactive checkpoint as well.

Use /permissions during an interactive Codex session to inspect or change the active permission mode. The selected runtime state matters when work is delegated.

Subagents inherit the active runtime

A custom agent file can declare sandbox_mode as a reusable default. That declaration is not an immutable security ceiling.

When a subagent starts, omitted settings inherit from the parent. Active parent overrides — including choices made through /permissions or a full-access launch — are reapplied to the child even when its custom agent file declares different defaults.

name = "explorer"
description = "Maps code and reports evidence without making edits."
sandbox_mode = "read-only"
developer_instructions = """
Inspect the requested surface and cite file paths and line numbers.
Do not edit files or run mutation commands.
"""

The role file makes read-only exploration the normal behavior. It does not protect the child from a parent session that has already been widened.

Match the boundary to the job

Start from the operation the role must complete, then grant the narrowest boundary that supports it.

Network access deserves its own decision. Package installation, remote documentation, and API calls need it; most local review and implementation work does not.

Prompts still matter

Sandboxing limits capability, not intent. A workspace-write agent can still delete project files, rewrite a lockfile, or make a poor architectural change inside its permitted root.

Instructions, lifecycle hooks, review gates, and version-control recovery address those risks. The sandbox answers “where can this process act?” Other controls answer “which actions should it take?” and “how is a bad action detected or reversed?”

Takeaways