Windows

Use Codex on Windows with the native Codex app, the CLI, or the IDE extension.

Use the Codex app on Windows

Work across projects, run parallel agent threads, and review results in one place with the native Windows app.

Depending on the surface and your setup, Codex can run on Windows in three practical ways:

• natively on Windows with the stronger elevated sandbox,
• natively on Windows with the fallback unelevated sandbox,
• or inside Windows Subsystem for Linux (WSL), which uses the Linux sandbox implementation.

Windows sandbox

When you run Codex natively on Windows, agent mode uses a Windows sandbox to block filesystem writes outside the working folder and prevent network access without your explicit approval.

Native Windows sandbox support includes two modes that you can configure in config.toml:

[windows]
sandbox = "elevated" # or "unelevated"

elevated is the preferred native Windows sandbox. It uses dedicated lower-privilege sandbox users, filesystem permission boundaries, firewall rules, and local policy changes needed for sandboxed command execution.

unelevated is the fallback native Windows sandbox. It runs commands with a restricted Windows token derived from your current user, applies ACL-based filesystem boundaries, and uses environment-level offline controls instead of the dedicated offline-user firewall rule. It is weaker than elevated, but it is still useful when administrator-approved setup is blocked by local or enterprise policy.

If both modes are available, use elevated. If the default native sandbox doesn’t work in your environment, use unelevated as a fallback while you troubleshoot the setup.

By default, both sandbox modes also use a private desktop for stronger UI isolation. Set windows.sandbox_private_desktop = false only if you need the older Winsta0\\Default behavior for compatibility.

Sandbox permissions

Windows version matrix

Additional environment assumptions:

• winget should be available. If it is missing, update Windows or install the Windows Package Manager before setting up Codex.
• The recommended native sandbox depends on administrator-approved setup.
• Some enterprise-managed devices block the required setup steps even when the OS version itself is acceptable.

Grant sandbox read access

When a command fails because the Windows sandbox can’t read a directory, use:

/sandbox-add-read-dir C:\absolute\directory\path

The path must be an existing absolute directory. After the command succeeds, later commands that run in the sandbox can read that directory during the current session.

We recommend using the native Windows sandbox by default. The native Windows sandbox will offer the best perfomance and highest speeds while keeping the same security. Choose WSL when you need a Linux-native environment on Windows, when your workflow already lives in WSL, or when neither native Windows sandbox mode meets your needs.

Windows Subsystem for Linux

If you choose WSL, Codex runs inside the Linux environment instead of using the native Windows sandbox. This is useful if you need Linux-native tooling on Windows, if your repositories and developer workflow already live in WSL, or if neither native Windows sandbox mode works for your environment.

Launch VS Code from inside WSL

For step-by-step instructions, see the official VS Code WSL tutorial.

Prerequisites

• Windows with WSL installed. To install WSL, open PowerShell as an administrator, then run wsl --install (Ubuntu is a common choice).
• VS Code with the WSL extension installed.

Open VS Code from a WSL terminal

# From your WSL shell
cd ~/code/your-project
code .

This opens a WSL remote window, installs the VS Code Server if needed, and ensures integrated terminals run in Linux.

Confirm you’re connected to WSL

• Look for the green status bar that shows WSL: <distro>.

• Integrated terminals should display Linux paths (such as /home/...) instead of C:\.

• You can verify with:

  echo $WSL_DISTRO_NAME

  This prints your distribution name.

Use Codex CLI with WSL

Run these commands from an elevated PowerShell or Windows Terminal:

# Install default Linux distribution (like Ubuntu)
wsl --install

# Start a shell inside Windows Subsystem for Linux
wsl

Then run these commands from your WSL shell:

# https://learn.microsoft.com/en-us/windows/dev-environment/javascript/nodejs-on-wsl
# Install Node.js in WSL (via nvm)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash

# In a new tab or after exiting and running `wsl` again to install Node.js
nvm install 22

# Install and run Codex in WSL
npm i -g @openai/codex
codex

Working on code inside WSL

• Working in Windows-mounted paths like /mnt/c/… can be slower than working in Windows-native paths. Keep your repositories under your Linux home directory (like ~/code/my-app) for faster I/O and fewer symlink and permission issues:

  mkdir -p ~/code && cd ~/code
  git clone https://github.com/your/repo.git
  cd repo

• If you need Windows access to files, they’re under \wsl$\Ubuntu\home<user> in Explorer.

Troubleshooting and FAQ

If you are troubleshooting a managed Windows machine, start with the native sandbox mode, Windows version, and any policy error shown by Codex. Most native Windows support issues come from sandbox setup, logon rights, or filesystem permissions rather than from the editor itself.

which codex || echo "codex not found"