Building a safe, effective sandbox to enable Codex on Windows

Building a safe, effective sandbox to enable Codex on Windows

OpenAI has developed a custom sandbox implementation for Codex on Windows to eliminate the user's need to choose between inefficient manual command approval and unrestricted "Full Access" mode. This sandbox allows Codex to read files broadly while restricting write access to specific workspaces and blocking unauthorized network access, bringing the Windows experience in line with the safety and usability of Codex on macOS and Linux.

Why Existing Windows Isolation Tools Were Insufficient

OpenAI evaluated several native Windows isolation primitives but found they were incompatible with the open-ended nature of developer workflows (shells, Git, Python, and various build tools).

  • AppContainer: While offering a strong OS boundary, it was designed for tightly scoped applications and was too restrictive for the broad range of binaries a coding agent needs to execute.
  • Windows Sandbox: This lightweight VM provides strong isolation but is unsuitable because Codex must operate on the user's actual local checkout and environment rather than a disposable guest OS. Additionally, it is unavailable on Windows Home SKUs.
  • Mandatory Integrity Control (MIC): Using low-integrity labeling was deemed too risky because marking a workspace as low-integrity makes it a "sink" for any low-integrity process on the host, rather than granting targeted access only to the sandbox.

The "Unelevated Sandbox" Prototype

The first prototype focused on running without administrator privileges (unelevated), utilizing Security Identifiers (SIDs) and write-restricted tokens to manage filesystem access.

Filesystem Write Restrictions

To control where Codex could modify files, the team used a combination of synthetic SIDs and write-restricted tokens:

  1. Synthetic SIDs: A custom sandbox-write SID was created to define permissions in Access Control Lists (ACLs) without interfering with other system users.
  2. Write-Restricted Tokens: These tokens require two checks for a write operation to succeed: the normal user identity must be allowed, and at least one SID in the token's restricted list (including the sandbox-write SID) must also be granted access.

This allowed Codex to be granted write/execute/delete access to the current working directory and configured writable_roots, while explicitly denying access to sensitive areas like .git, .codex, and .agents folders.

Network Access Limitations

Because the prototype was unelevated, it could not use the Windows Firewall. Instead, it relied on "advisory" restrictions, such as poisoning environment variables (HTTPS_PROXY, GIT_HTTPS_PROXY) and prepending a denybin directory to the PATH to intercept SSH and SCP calls. This approach was found to be too weak, as processes could easily bypass environment variables or open sockets directly.

The Final "Elevated Sandbox" Architecture

To achieve robust network suppression, OpenAI transitioned to an "elevated sandbox" that requires administrator permissions during setup to implement firewall rules and dedicated system users.

Setup and Permissions

The codex-windows-sandbox-setup.exe binary handles the elevated configuration:

  • User Creation: It creates two local users: CodexSandboxOffline (blocked by firewall rules) and CodexSandboxOnline (not blocked).
  • Credential Management: User credentials are encrypted via the Windows Data Protection API (DPAPI).
  • Firewall Rules: Outbound network access is completely blocked for the CodexSandboxOffline user.
  • Read ACLs: Because the sandbox users are distinct from the real user, the setup asynchronously grants read/execute permissions to essential directories (e.g., C:\Users\<real-user>, C:\Windows\, C:\Program Files\) to ensure the agent can still read the necessary files.

The Command Execution Flow

Due to Windows privilege boundaries, codex.exe cannot directly spawn a process as a different user with a restricted token. This required the introduction of codex-command-runner.exe to split the execution flow:

  1. Initiation: codex.exe uses CreateProcessWithLogonW to launch codex-command-runner.exe as the designated sandbox user.
  2. Restriction: Inside the runner, the process opens its own token, creates a restricted token using CreateRestrictedToken, and then uses CreateProcessAsUserW to launch the final child process (e.g., a Python script or Git command).

Summary of the Sandbox Component Stack

The final architecture consists of four distinct layers to balance security and developer productivity:

  • codex.exe: The main unelevated harness.
  • codex-windows-sandbox-setup.exe: Handles elevated setup, user creation, and firewall configuration.
  • codex-command-runner.exe: Mints restricted tokens and spawns the final child process as the sandbox user.
  • The Child Process: The actual command executed by the agent under restricted permissions.

Sources