Inside Codex Sandbox: How OpenAI Restricts Local AI Agent Permissions
OpenAI's Codex Sandbox enforces four permission boundaries: OS-level restrictions at command launch, separate MCP service permissions, proxy-enforced domain allowlists, and the critical insight that sandbox limits don't propagate to files executed later by external processes.
Command Launch-Time Restrictions
The core design: the model decides what command to run; the OS enforces restrictions at launch. In the source, exec_command passes the command, working directory, environment variables, and permission options to a unified executor. Codex translates permission configs into native sandbox rules, then starts the command so the OS applies constraints. Child processes (e.g., test frameworks, compilers) inherit the same limits, even if they outlive the original command.
The built-in :workspace profile allows writes to the workspace and system temp, denies network by default, and adds extra write protection for .git, .codex, .agents, .aws to prevent modification of Git hooks or .codex/config.toml. Read access is broader (SDKs, libraries, user config files including secrets), but default network denial blocks direct uploads — though files remain readable unless explicitly denied.
Profiles are adjustable per project: add write for external build caches, read for read-only directories, deny to block specific paths. Admins can constrain available profiles via requirements.toml. However, allowing workspace writes means unprotected files can be overwritten or deleted — the sandbox cannot distinguish necessary cleanup from accidental deletion. Database access similarly depends on DB-level credentials; Replit's production-data incident led to separating dev and prod databases.
Temporary privilege escalation follows an approval policy (user or auto-review). Approved requests take different launch paths depending on whether they expand sandbox-internal access or break out of the sandbox entirely.
MCP Services Use Separate Permissions
A local stdio MCP service (e.g., internal docs lookup) runs in the same Codex session as npm test, but via a different launch path. The Shell executor applies sandbox rules to test commands; the MCP client launches the service directly via stdio, reading config.toml for executable and args. By default, the service inherits its own runtime environment's permissions — not the workspace sandbox. Bolin explains: services have diverse needs (some read local indexes, others call internal networks at startup); a one-size-fits-all sandbox would break initialization.
To restrict a specific MCP service, wrap its launch with codex sandbox --permission-profile <profile>. This entry point works independently of the Agent session. The article shows a Memory MCP example using Permission Profiles (Beta, not additive with legacy sandbox_mode / sandbox_workspace_write):
[permissions.memory-mcp.filesystem]
":root" = "read"
"~/.npm" = "write"
"~/mcp-data" = "write"
[permissions.memory-mcp.network]
enabled = false
[mcp_servers.memory]
command = "codex"
args = [
"sandbox", "--permission-profile", "memory-mcp", "--",
"npx", "--offline", "@modelcontextprotocol/[email protected]"
]
[mcp_servers.memory.env]
MEMORY_FILE_PATH = "~/mcp-data/memory.jsonl"Broad read lets Node/npm find deps; write only to npm cache and service data dir. --offline constrains npm fetching; enabled = false blocks all network for the service process. Admins can restrict which MCP servers may start via requirements.toml (matching executable/args), but that only controls launch — runtime access still depends on the service's process permissions. Remote MCP services are governed server-side.
Domain Rules Enforced by Proxy
To allow only registry.npmjs.org, derive a profile from :workspace, enable network and the proxy feature:
default_permissions = "project-dev"
[features]
network_proxy = true
[permissions.project-dev]
extends = ":workspace"
[permissions.project-dev.network]
enabled = true
[permissions.project-dev.network.domains]
"registry.npmjs.org" = "allow"Two switches: network.enabled permits network use; features.network_proxy activates the proxy that enforces domain rules. If the proxy is off, the domain table is ignored — commands connect directly. With proxy on, Codex sets HTTP_PROXY / HTTPS_PROXY env vars. Programs ignoring these and attempting direct connections are blocked by the OS sandbox. The proxy evaluates domain rules: explicit deny first, unmatched domains may be denied or sent to approval. Proxy checks destination before DNS resolution to avoid leaking hostnames, though broad wildcards or allowed DNS servers could still exfiltrate data. Domain rules only govern traffic entering the sandboxed command — not model requests, built-in web search, or separately launched MCP services.
Three OS Implementations
macOS : Uses sandbox-exec with kernel Seatbelt. Workspace writable, subdirectories read-only expressed in generated policy. Proxy allowed via loopback port on host.
Linux : Uses bubblewrap to shape the filesystem view (project writable, .git read-only). Seccomp filters syscalls; no_new_privs prevents privilege escalation via setuid. Proxy: command in isolated network namespace, connects to internal loopback listener, relayed to host proxy.
Windows : Migrating to Microsoft MXC. Allows specific path overrides (drive read-only, workspace writable, .git read-only). Proxy mode blocks direct external connections, allows host loopback; other local loopback services may be reachable.
Glob deny patterns (e.g., **/*.env) have a timing gap: Linux bubblewrap and Windows MXC expand globs to concrete paths at launch. .env files created after launch won't be added to that run's deny list.
Files Don't Inherit Sandbox Limits
Bolin illustrates with a frontend project using project-local Prettier (in node_modules, git-ignored). If the Agent writes malicious code into that dependency (allowed by sandbox), the sandbox won't stop it. On next save, the editor loads the compromised Prettier — the editor process runs with its own permissions, outside the sandbox. Child processes inherit sandbox limits; files do not carry those limits to the next program that executes them.
Simon Willison notes an alternative: keep the Agent on the desktop, offload command execution via API to a separate Linux environment with selective directory mounts. But if host and sandbox share a writable directory, the editor can still load sandbox-modified files.
Verification Checklist
What to Verify and How to Check
Shell & child processes : Have sandboxed command and its children attempt writes to a forbidden test directory; confirm denial.
Local MCP service : Use a test service to attempt same writes; compare default launch vs. wrapped with codex sandbox --permission-profile.
Network proxy : Enable proxy; request an allowed and a denied domain; try bypassing proxy to connect directly; verify OS blocks it.
Editor taking over files : Confirm where formatter loads from, whether dependency dirs allow Agent writes; git-ignored dirs are in this chain.
Allowed actions succeeding only proves the path works; denied actions actually being blocked confirms the restriction is active.
Two key questions when delegating to an Agent: what permissions does this process hold, and who will execute the files it writes. Answering both clarifies what can be safely automated and what needs separate permission controls.
Signed-in readers can open the original source through BestHub's protected redirect.
This article has been distilled and summarized from source material, then republished for learning and reference. If you believe it infringes your rights, please contactand we will review it promptly.
How this landed with the community
Was this worth your time?
0 Comments
Thoughtful readers leave field notes, pushback, and hard-won operational detail here.
