Codex CLI on Windows: native PowerShell or WSL?

Run Codex CLI on Windows natively, from PowerShell, unless your project is built with Linux tools. Native Codex runs commands inside its own Windows sandbox, and OpenAI recommends Windows 11 for it. Choose WSL2 when your repo and toolchain already live in Linux: there Codex uses its Linux sandbox, which needs bubblewrap, and WSL1 no longer works at all.

We read OpenAI's Windows pages for this on 24 October 2026. They now live on learn.chatgpt.com; the old developers.openai.com/codex/windows address redirects there.

Native PowerShell vs WSL2 at a glance#

WSL1 isn't a column, because OpenAI dropped it: "WSL1 was supported through Codex 0.114. Starting in Codex 0.115, the Linux sandbox moved to bubblewrap, so WSL1 is no longer supported."

mxc, elevated or unelevated: the three Windows sandboxes#

Native Codex can sandbox commands three ways, and they protect you to different degrees. The sandbox decides what a command may touch; whether Codex stops to ask first is a separate setting, the approval policy, explained in our guide to Codex CLI approval modes.

mxc is what OpenAI now recommends. It uses Microsoft Execution Containers, process isolation built into Windows, so there's no administrator setup, no extra Windows accounts and no firewall rules. Microsoft added it in Windows 11 24H2 (build 26100.9278) and 25H2 (build 26200.9278) and is still rolling the capability out, so a fully updated PC may not have it yet. The desktop app picks it by itself for consumer accounts when the PC supports it; for the CLI you switch it on in config.toml:

[features]
prefer_mxc = true

Codex CLI 0.162.0 added a way to try MXC on a single command while your saved setting stays as it is. Run this in your project folder. It prints MXC_OK, and $LASTEXITCODE should then read 0:

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

Under MXC, child processes stop when the foreground command exits. So a dev server that an agent starts in the background stops as soon as the command that launched it returns.

elevated is the fallback when MXC isn't there. Setting it up creates dedicated low-privilege sandbox users and adds filesystem boundaries, firewall rules and some local policy changes, which is why it needs one administrator-approved setup. The commands themselves still run without administrator rights.

unelevated is the last resort. Commands run under a restricted token derived from your own user, and ACLs draw the filesystem boundary. OpenAI names two gaps compared with elevated: weaker network isolation, and no way to deny reads of specific paths. Pick it when a company laptop refuses the elevated setup.

You choose a fallback in config.toml. When none is set and both are allowed, OpenAI says Codex prefers elevated:

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

Our Codex config.toml guide has where the file lives and the other keys.

How to install Codex CLI on Windows natively#

OpenAI recommends Windows 11. A recent, fully updated Windows 10 is "best effort", and it has to be version 1809 or newer, because Codex needs the modern console (ConPTY). OpenAI also says winget should be there.

1. Open a new PowerShell window. It doesn't need to be an administrator one: the installer puts Codex in %LOCALAPPDATA%\Programs\OpenAI\Codex\bin and adds that folder to your user PATH.

2. Run OpenAI's installer:

   powershell

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

   If you'd rather use npm and already have Node.js, npm install -g @openai/codex works too.

3. Open another new PowerShell window, cd into a project and run codex.

4. Pick Sign in with ChatGPT, or another sign-in method, the first time.

5. If Codex asks to set up its sandbox, pick "Set up default sandbox (requires Administrator permissions)" and approve the Windows prompt. The other choices are "Use non-admin sandbox (higher risk if prompt injected)", which is unelevated, and "Quit".

The installer's -ExecutionPolicy ByPass applies to that one PowerShell process only. Your machine's policy stays as it was, which matters for the npm.ps1 error further down.

How to run Codex CLI in WSL2#

1. In PowerShell opened as administrator, run wsl --install. It installs WSL and, unless you name another, Ubuntu.
2. Run wsl to open a shell inside it.
3. Install bubblewrap: sudo apt install bubblewrap (sudo dnf install bubblewrap on Fedora).
4. Install Codex: curl -fsSL https://chatgpt.com/codex/install.sh | sh.
5. Put your code in your Linux home, mkdir -p ~/code && cd ~/code, clone there and run codex.

Codex uses the first bwrap on your PATH. Without one it falls back to a bundled helper, which only works if the distro allows unprivileged user namespaces, and Codex shows a warning at startup when neither works. On Ubuntu 24.04 that warning can stay after bubblewrap is in. OpenAI's fix loads an AppArmor profile:

sudo apt update
sudo apt install apparmor-profiles apparmor-utils
sudo install -m 0644 /usr/share/apparmor/extra-profiles/bwrap-userns-restrict /etc/apparmor.d/bwrap-userns-restrict
sudo apparmor_parser -r /etc/apparmor.d/bwrap-userns-restrict

Still on WSL1? wsl -l -v lists each distro with its WSL version. Convert one from PowerShell with wsl --set-version <distribution name> 2. Microsoft warns that converting a big distro can take a while and can fail, so back it up first.

Codex not working on Windows: the usual errors#

The sandbox setup didn't finish#

When the elevated setup fails, Codex CLI says "Couldn't set up your sandbox with Administrator permissions" and offers "Try setting up admin sandbox again" or "Use Codex with non-admin sandbox". OpenAI lists the usual causes: the administrator prompt was declined, or the PC doesn't allow creating local users or groups, changing firewall rules or granting the sandbox users their logon rights. Try again and approve the prompt. On a managed laptop, ask IT whether it allows those steps. If it doesn't and policy permits, use unelevated meanwhile.

IT can also set up the elevated sandbox for you, so you don't need administrator rights yourself, with codex sandbox setup --elevated --user '<user>' --codex-home '<path>' (for example --user 'DOMAIN\alice' --codex-home 'C:\Users\alice\.codex').

A thread on OpenAI's community forum, started 2 June 2026, reports windows sandbox failed: spawn setup refresh on Codex 0.135.0 with [windows] sandbox = "elevated". Two days later the same user wrote that 0.137.0 seemed to work, and in July that nothing had gone wrong since 0.139. One user is not a confirmed fix, but updating Codex is the cheap first step.

Codex is using the unelevated sandbox#

Without the elevated setup, Codex can drop to unelevated. Commands stay sandboxed behind ACLs, but there are no separate sandbox users and network isolation is weaker. For a managed laptop OpenAI gives an order: first find out whether the PC supports MXC, and only if it doesn't, ask IT to set up elevated.

Windows error 1385#

Codex created its sandbox users, but Windows policy refuses them the logon type they need to start a command. IT has to grant those logon rights. Unelevated keeps you working meanwhile.

A warning about folders Everyone can write to#

The sandbox can't fully protect a folder that every account on the PC can write to. Remove Everyone's write access from the folders Codex lists, then restart Codex or run the sandbox setup again.

"npm.ps1 cannot be loaded because running scripts is disabled on this system"#

PowerShell's execution policy is blocking a script, here npm's own npm.ps1. OpenAI's suggestion is Set-ExecutionPolicy -ExecutionPolicy RemoteSigned, after reading Microsoft's execution policy guide. The same error with codex.ps1, claude.ps1 or gemini.ps1, and the narrower fixes, are in our guide to running scripts is disabled.

'codex' is not recognized#

Open a new PowerShell window: the installer changed your user PATH, and windows opened before it don't see the change. If it still fails, check that %LOCALAPPDATA%\Programs\OpenAI\Codex\bin is on your PATH. With an npm install, npm's global folder has to be on it instead.

codex isn't found in WSL#

Run which codex || echo "codex not found" inside WSL. A Windows install doesn't count there: install Codex again inside the distro.

Codex is slow in WSL#

Your repo is probably under /mnt/c. Move it into your Linux home; OpenAI also suggests wsl --update and wsl --shutdown.

If nothing here fixes it, OpenAI asks for CODEX_HOME/.sandbox/sandbox.log, your Windows build number and which sandbox you use. Never send the contents of CODEX_HOME/.sandbox-secrets/.

How Shuriken runs Codex on Windows#

Shuriken is a desktop app for Windows 10 and 11 (x64). It runs Codex natively, the left-hand column of the table above.

When Codex is missing from the PC, Shuriken says so and shows an Install Codex button. That runs npm install -g @openai/codex with its prefix set to %USERPROFILE%\.shuriken\tools, a folder Shuriken owns, so the install needs no administrator rights and leaves your own global npm alone. Shuriken calls npm's npm-cli.js directly instead of going through npm.ps1, which is why the execution-policy error above can't block it. Before it trusts the new Codex, it checks each package's registry signature, the same check npm audit signatures makes. A Codex older than 0.132.0 counts as out of date and is updated.

Shuriken adds no sandbox of its own; it asks Codex for one. A Codex chat in Default Permissions asks for workspace-write with on-request approvals, the pair OpenAI's docs call Auto. Full Access asks for danger-full-access with no approvals, which turns Codex's sandbox off.

Every chat except a project's Main chat gets its own branch in its own git worktree. When one of your ChatGPT accounts nears its limit, hot swapping moves the chat to another of your accounts (source switching has how it picks). Use accounts you own and are entitled to use, because OpenAI's terms may not allow sharing a sign-in.

Windows may show a SmartScreen warning the first time you install Shuriken, because our Windows builds aren't code-signed yet. Updates after that are checked against our signature before they install (Shuriken on Windows has the steps).

Claude Code comes out differently on the same question, because on Windows its sandbox works only inside WSL 2: see Claude Code on Windows: native or WSL?. To have Codex installed for you on Windows, download Shuriken for Windows.