
Inside the Codex sandbox: OS-level sandboxing for AI agents

OpenAI describes the design and implementation of the Codex sandbox, a defense-in-depth layer for its coding agent harness. In addition to training and alignment, Codex restricts command execution in the user’s existing environment using OS sandbox facilities, not containers or VMs. Defaults aim to be conservative yet useful: within a Git workspace, writes are allowed but .git and .codex are read-only; reads are broad so compilers, runtimes, and build tools work; network is disabled by default to block exfiltration. The tradeoff is that sensitive files such as configs with API keys remain readable, and attacks like injecting code into node_modules/prettier can escape the sandbox if the user’s editor runs that package on save, hence the layered approach.
Codex uses each platform’s sandboxing mechanisms through a common API that takes a command and a permission profile, returning a Child handle. Child processes inherit the sandbox constraints, so restrictions apply throughout the process tree. Permission profiles are defined in config.toml, where filesystem entries can grant read, read/write, or deny access. Profiles can extend built-in profiles such as :workspace. Network configuration has roughly three options: disable all network access, enable full direct access, or restrict access to a proxy, which decides what to let through based on the profile. Domain rules support exact names and wildcards, with explicit deny rules taking precedence over allow rules. When a request matches no rule, the proxy can suspend it and delegate to the harness for user or auto-review approval.
The harness’s shell tool replaces subprocess.Popen() with spawn_command_under_sandbox(), supplying the permission profile and, when needed, a network proxy. The model can request different permissions for an individual command: use_default, with_additional_permissions, or require_escalated, but the harness decides whether to grant the request. The sandbox infrastructure is also reused for local file operations and exposed through the codex sandbox command, which runs an arbitrary command under a named permission profile. One notable example: MCP servers configured in config.toml are not sandboxed by default because Codex cannot reliably infer their needs, but they can be wrapped with codex sandbox to limit writes and block network access.
On macOS, Codex uses Seatbelt via Apple’s /usr/bin/sandbox-exec command, with policies written in Sandbox Profile Language (SBPL). The base profile starts with (deny default), so outbound connections remain blocked unless explicitly allowed. Apple does not document SBPL for third-party use and marks sandbox-exec deprecated, but macOS still ships Seatbelt profiles and third-party software such as Chrome relies on it, so OpenAI plans to continue using it.
On Linux, Codex combines bubblewrap (bwrap) and seccomp-bpf through an internal helper, codex-linux-sandbox. bwrap creates a filesystem view in a separate mount namespace using options like –bind, –ro-bind, and –perms 000 –tmpfs for deny entries. Codex also uses –unshare-ipc and –unshare-pid, and –unshare-net whenever networking is disabled or must go through the proxy. The seccomp filters are compiled with the seccompiler crate and applied to a launcher process so constraints are inherited by the entire process tree; no_new_privs prevents setuid privilege escalation. Deny globs are expanded to concrete paths before launch, so new matching paths are not automatically restricted.
For proxy routing on Linux, Codex creates a loopback TCP listener inside the sandbox’s isolated network namespace and uses a Unix socket pair to hand its file descriptor to a process outside the sandbox, which relays connections to the shared proxy. This gives the sandbox its own network namespace and loopback interface without exposing the host’s namespace.
On Windows, Codex is transitioning to Microsoft’s MXC (Microsoft eXecution Container) library, which uses native process isolation inside the existing environment. The transition addresses limitations of the previous sandbox: elevated admin access, slow ACL operations, and persistent host state such as ACLs, firewall rules, sandbox users, and control plane files. Codex builds an MXC execution request from a JSON configuration schema, translating filesystem and network rules into MXC settings. Drive-root grants are read-only and recursive, writable drive-root grants are expanded to immediate children, more-specific paths override ancestors, and deny globs are expanded to concrete paths before launch. Network domain rules are enforced by the shared network proxy, with MXC blocking direct external connections while allowing host-loopback access to the proxy.
Across all platforms, the network proxy is shared and starts both HTTP and SOCKS5 proxies, injecting standard and application-specific environment variables such as HTTP_PROXY and PIP_PROXY. Not all programs honor those variables, but OS-level sandbox restrictions block direct connections to external hosts. The proxy resolves hostnames only after a request is allowed or approved, because even a DNS lookup can leak information encoded in a hostname; broad wildcard rules or access to DNS services can still permit DNS-based exfiltration.

