For Codex CLI on Windows, start with the native Windows sandbox unless your toolchain and repository already live in WSL2. Native mode keeps PowerShell, Windows paths and Windows tooling in the same environment. WSL2 is the better fit when the work depends on Linux-native commands, packages or filesystem behaviour.

Applies to: Codex CLI on Windows; MXC checks require Codex CLI 0.162.0 or later. Official documentation checked 19 October 2026.

On this page

Native Windows or WSL2: the short answer

OpenAI documents both routes, but they solve different problems.

Choose When it fits Main trade-off
Native Windows sandbox Your project uses PowerShell, Windows SDKs, Windows paths or Windows-only tooling Sandbox support depends on the Windows version, device capabilities and policy
WSL2 Your repository and commands are Linux-first, or the native sandbox does not meet the workflow Keep the repository inside the Linux filesystem for good I/O and fewer path issues

The native route is not the same as Microsoft’s disposable Windows Sandbox app. Codex runs commands through its own Windows sandbox implementation and applies the active filesystem and network permissions. WSL2 instead runs Codex inside a Linux environment.

If you are still choosing between the terminal, desktop app and editor, read Codex CLI vs Codex app vs IDE extension first.

Install Codex CLI natively on Windows

The official Codex repository gives a PowerShell installer for Windows:

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

The repository also documents npm as an alternative:

npm install -g @openai/codex

Start the CLI from the project directory:

cd C:\path\to\your-project
codex

On first use, Codex can sign in with a ChatGPT account. The official repository recommends that route for access included with eligible ChatGPT plans; API-key use needs separate setup. The nearby Codex usage guide explains the plan allowance and the /status command without mixing it into installation.

How the native Windows sandbox is selected

OpenAI’s Windows documentation lists three implementations:

  • mxc is the recommended option on compatible Windows devices. It uses Microsoft Execution Containers for process isolation.
  • elevated is the preferred legacy fallback when MXC is unavailable or disabled. Its setup requires administrator approval, but commands inside the sandbox do not run as administrator.
  • unelevated is the secondary legacy fallback. It has weaker network isolation than elevated and does not support denied read paths.

For consumer accounts in the Windows desktop app, MXC is preferred automatically on supported devices. For standalone CLI use, the documentation shows this opt-in:

[features]
prefer_mxc = true

Put it in Codex’s config.toml. When the device or policy cannot use MXC, Codex follows the legacy selection and setup flow.

A compatible device is not established by “Windows 11” alone. OpenAI says MXC capabilities are being rolled out to Windows 11 24H2 build 26100.9278 and 25H2 build 26200.9278. Codex CLI 0.162.0 and later can test MXC for one command:

codex -c windows.sandbox=mxc sandbox --include-managed-config --permission-profile :workspace -- cmd.exe /d /c echo MXC_OK
$LASTEXITCODE

The expected result is MXC_OK with exit code 0. An explicit MXC selection fails when the required capability is missing or managed policy blocks it.

Set a legacy fallback deliberately

For a machine that cannot use MXC, select the allowed fallback instead of assuming which sandbox ran:

[windows]
sandbox = "elevated"

Use "unelevated" only when the administrator-approved setup is unavailable and policy permits the weaker fallback. OpenAI says elevated uses lower-privilege sandbox users, filesystem permission boundaries, firewall rules and local policy changes. unelevated uses a restricted token and ACL-based filesystem boundaries, but its network isolation is weaker.

Check the effective setup from an active CLI session:

/status
/debug-config

Those commands help separate a sandbox-selection problem from a Windows file-permission or managed-policy restriction. If a company laptop blocks setup, the official guidance is to involve the administrator rather than disable the sandbox.

Full-access mode removes the project boundary and can expose files outside the repository to unintended changes. Keep the sandbox in place and grant narrow exceptions. The Codex permissions guide covers the safer choices.

Install and run Codex in WSL2

Choose WSL2 when the repository and developer tooling already live in Linux, or when Linux-native behaviour matters more than Windows-native paths.

From an elevated PowerShell or Windows Terminal:

wsl --install
wsl

Then install Codex from the WSL shell:

curl -fsSL https://chatgpt.com/codex/install.sh | sh
codex

This is a separate Linux installation. A Codex binary installed in Windows PowerShell is not automatically the binary used inside WSL.

OpenAI no longer supports WSL1 for current Codex releases. The documentation says WSL1 was supported through Codex 0.114; starting with 0.115, the Linux sandbox uses bubblewrap, which requires WSL2.

Keep the repository in the Linux filesystem

Do not put a Linux-first Codex workflow under /mnt/c by default. OpenAI warns that Windows-mounted paths can be slower and can produce more symlink and permission problems. Clone the repository under the WSL home directory:

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

Windows Explorer can reach those files through \\wsl$\<distribution>\home\<user>.

For VS Code, open the project from the WSL shell:

cd ~/code/your-project
code .

Confirm that the editor shows WSL: <distro> and that the integrated terminal uses Linux paths such as /home/..., not C:\....

Troubleshoot the common split-brain cases

VS Code cannot find Codex inside WSL

Check the binary from the WSL terminal:

which codex || echo "codex not found"

If it is missing, install Codex inside WSL. Installing the Windows binary does not add it to the Linux PATH.

A large repository is slow in WSL

First check its location. Move it from /mnt/c/... to ~/code/.... OpenAI also suggests updating WSL and restarting it:

wsl --update
wsl --shutdown

The native sandbox setup fails

The documented causes include a declined UAC prompt, blocked local user or group creation, blocked firewall changes, missing sandbox-user logon rights and enterprise policy. Retry elevated only when the environment permits those changes. On a managed device, ask IT which implementation is allowed.

Codex falls back to unelevated

That mode still applies ACL-based filesystem boundaries, but it lacks the separate sandbox-user boundary and has weaker network isolation. Treat it as a fallback, not as equivalent to MXC or elevated.

A practical decision sequence

  1. Use native Windows first for PowerShell and Windows-native projects.
  2. Check /status and /debug-config so you know which sandbox and permissions are active.
  3. Prefer MXC when the device and policy support it.
  4. Otherwise use elevated; use unelevated only as an allowed secondary fallback.
  5. Move to WSL2 when the project depends on Linux tooling or already lives in WSL.
  6. In WSL2, keep the repository under ~/code, not /mnt/c.
  7. Do not solve sandbox trouble by switching to full access as the default.

Official sources

Documentation checked 19 October 2026.