agent-sandboxing
A sandbox is a constrained execution environment: the OS launches an agent’s command with reduced permissions, and those constraints propagate down the entire process tree — every descendant process stays inside the same boundary (2026-07-12-codex-windows-sandbox-engineering). For coding agents, the sandbox is what turns the harness‘s execution boundary from policy text into something the operating system actually enforces.
Why agents need one
An agent running with the real user’s permissions can do everything the user can — run tests, edit files, create Git branches, and also delete data or exfiltrate it to the internet. Without enforcement, the user faces a bad dichotomy: approve nearly every command (defeating the point of an agent), or grant full access (removing oversight) (2026-07-12-codex-windows-sandbox-engineering). A sandbox is what makes the middle setting — codex‘s default of read almost anywhere, write only in the workspace, no network unless approved — mechanically true rather than aspirational.
Two properties recur as the load-bearing requirements (2026-07-12-codex-windows-sandbox-engineering):
- Enforcement, not advice. Env-var tricks (dead proxy endpoints, PATH stubs) catch well-behaved tools but are bypassed by anything that opens sockets directly — including well-intentioned binaries that simply ship their own network stack. OpenAI killed its first Windows prototype over exactly this.
- Process-tree inheritance. The boundary must apply to whatever the agent spawns (shells, Git, Python, package managers, arbitrary binaries), not just the agent binary itself.
OS primitives, per platform
| Platform | Primitive | Notes |
|---|---|---|
| macOS | Seatbelt | codex generates the .sbpl profile dynamically — semantics are cheap to change (2026-07-12-codex-windows-sandbox-engineering) |
| Linux | seccomp, bubblewrap | (2026-07-12-codex-windows-sandbox-engineering) |
| Windows | none out-of-the-box | AppContainer (wrong shape for open-ended dev workflows), Windows Sandbox (throwaway VM, not the user’s real checkout; missing on Home SKUs), MIC labels (relabeling the workspace low-integrity opens it to all low-integrity processes) all rejected (2026-07-12-codex-windows-sandbox-engineering) |
The Windows gap forced OpenAI to compose its own from SIDs, write-restricted tokens, dedicated local users (CodexSandboxOffline/CodexSandboxOnline), DPAPI-encrypted credentials, and firewall rules — a four-binary architecture whose full design history is on the source page (2026-07-12-codex-windows-sandbox-engineering).
Design axes the Windows case surfaces
- Enforcement strength vs. elevation cost. True network enforcement on Windows required admin-elevated setup and running commands as a separate OS principal; the unelevated design could enforce writes but only advise on network (2026-07-12-codex-windows-sandbox-engineering).
- Semantics changeability. ACL-based restrictions are expensive to adjust after the fact; a regenerated Seatbelt profile is not. Sandbox mechanism choice constrains how fast policy can evolve (2026-07-12-codex-windows-sandbox-engineering).
- Write carve-outs inside writable roots. The agent may edit the workspace but is explicitly denied
<cwd>/.git,<cwd>/.codex,<cwd>/.agents— it cannot rewrite Git metadata or its own configuration/instructions (2026-07-12-codex-windows-sandbox-engineering). A containment measure against self-modification, sibling in spirit to keeping the evaluator outside the loop (self-improving-harness). - The sandbox must not unlock itself. Sandbox-user credentials are stored where the sandbox users cannot read them (2026-07-12-codex-windows-sandbox-engineering).
- Agent workloads are open-ended. Classic app sandboxes (AppContainer) assume the app declares its needs up front; a coding agent is “let an agent operate like a developer” — the workload shape is what made every native Windows option miss (2026-07-12-codex-windows-sandbox-engineering).
Relation to other concepts
- harness — the sandbox is the OS-level instantiation of the execution boundary row (workspace isolation, allowlist); claude-hooks is the application-level sibling in the claude-code ecosystem.
- prompt-injection — sink-side containment: blocking outbound network at the process-tree level closes the exfiltration sink even when injection succeeds; complements the source-side defenses (tagging, confirmation) on that page.
- long-running-agents — overnight unattended runs presuppose a boundary the agent can’t wander out of; sandboxing is part of what makes releasing that autonomy defensible (harness‘s “harness → rollback → autonomy” ordering).