Installing Codex CLI on Windows: Native, WSL or the App

Codex CLI runs natively on Windows. One PowerShell command installs it, and when it runs in PowerShell it uses its own Windows sandbox, so you do not need WSL or a virtual machine. WSL 2 is the other route, for projects built with a Linux toolchain. And if you would rather not live in a terminal, the ChatGPT desktop app for Windows has a Codex view with the same agent behind it. OpenAI recommends the native sandbox by default and WSL when you need Linux-native tools or already work in WSL 2. Whichever you choose, your settings and sign-in live in one folder, %USERPROFILE%\.codex.

This page is only about Windows. Signing in, writing an AGENTS.md and adding MCP servers work the same on every platform and are covered in Codex CLI setup.

Three ways to run Codex on Windows

• Native CLI in PowerShell. Nothing else to install. Commands run inside the Windows sandbox. Use it for .NET, Node or Python projects that already build on Windows.
• CLI inside WSL 2. Codex runs as a Linux program with the Linux sandbox. Use it when the project builds with Linux tools, or your team already works in WSL.
• The ChatGPT desktop app. Choose Codex from the top-left menu for projects, parallel threads, Git worktrees, a built-in browser and scheduled tasks, with the agent running natively or in WSL.

Install natively from PowerShell

The openai/codex README↗ (opens in a new tab) gives one command for Windows. Run it in a normal PowerShell window; it needs no administrator rights.

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"
# then open a new PowerShell window
codex --version
codex

The script itself is short enough to read before you run it. It supports only 64-bit Windows, on x64 or ARM64. It downloads a release, checks its SHA-256 digest, unpacks it under %USERPROFILE%\.codex\packages\standalone, and exposes codex.exe from %LOCALAPPDATA%\Programs\OpenAI\Codex\bin, which it adds to your user PATH. The window you installed from can run codex at once; other windows need reopening to pick up the new PATH.

If you prefer npm, npm install -g @openai/codex also works on Windows. Do not keep both. The installer notices an npm-managed copy and offers to uninstall it, and warns that with two installs, PATH order decides which one runs. That is the usual cause of “I updated Codex but it still reports the old version”.

How the Windows sandbox works

When Codex runs natively, its commands run in a sandbox that blocks writes outside your working folder and blocks network access unless you approve it. OpenAI’s Windows sandbox documentation↗ (opens in a new tab) describes two implementations, chosen in config.toml.

• Elevated, the preferred one. Setup creates dedicated lower-privilege sandbox users, sets filesystem boundaries with ACLs, adds firewall rules and makes local policy changes. It needs an administrator to approve the setup, which is the UAC prompt you see the first time.
• Unelevated, the fallback. Commands run with a restricted token derived from your own user, with ACL-based file boundaries and environment-level offline controls instead of the firewall rule. It is weaker, and meant for machines where you have no admin rights or policy blocks the elevated setup.

[windows]
sandbox = "elevated"   # or "unelevated" if elevated setup is blocked

The same page sets expectations by Windows version: Windows 11 is recommended, recent Windows 10 (1809 or later) is best effort, and older Windows 10 is not recommended because it lacks console components Codex needs. It also expects winget to be available. When a task needs to read a folder outside the working directory, grant it for the session with /sandbox-add-read-dir C:\absolute\path; the folder must already exist.

The sandbox is the boundary; approvals are what happens at it. Codex’s sandbox and approvals page↗ (opens in a new tab) describes sandbox_mode (read-only, workspace-write or danger-full-access) and approval_policy, and /permissions changes them mid-session. Those behave the same on Windows as anywhere else.

Install inside WSL 2

In WSL, Codex is a Linux program: install it with the Linux installer from inside your distribution. The WSL guide↗ (opens in a new tab) is firm on one point: WSL 1 is no longer supported. It worked up to Codex 0.114; from 0.115 the Linux sandbox moved to bubblewrap, which needs WSL 2.

wsl --install
wsl
# inside WSL
curl -fsSL https://chatgpt.com/codex/install.sh | sh
mkdir -p ~/code && cd ~/code/my-repo
codex

Keep the repository in your Linux home, such as ~/code/my-repo, not under /mnt/c. The same guide says working through /mnt/c is much slower. From Windows you can still reach the files through \\wsl$\ in Explorer, and running code . inside WSL opens VS Code connected to the distribution, with the Codex extension working there.

The ChatGPT desktop app

Codex’s app on Windows is now part of the ChatGPT desktop app, with Codex as its own view and its own history. Install it from the Microsoft Store or with winget, as the Windows app page↗ (opens in a new tab) shows. If the CLI is already installed, codex app opens the app, or starts the installer when it is missing; on Windows it prints the workspace path for you to open.

winget install --id 9PLM9XGG6VKS -s msstore

• Agent environment. Windows native by default, using the same Windows sandbox. To switch, open Settings, change the agent from Windows native to Windows Subsystem for Linux, and restart the app.
• Integrated terminal. PowerShell by default, with Command Prompt, Git Bash and WSL available. This is a separate choice from the agent environment.
• Tools. OpenAI suggests Git, Node.js LTS, Python, the .NET SDK and GitHub CLI, all installable with winget.

Where your settings and sign-in live

Everything is in %USERPROFILE%\.codex: config.toml, a global AGENTS.md if you write one and, unless you store it in the Windows credential store, auth.json. Set CODEX_HOME to move it. OpenAI’s authentication page↗ (opens in a new tab) warns that auth.json contains access tokens, so treat it like a password and keep it out of any repository.

The CLI inside WSL has its own ~/.codex by default. To have WSL and Windows share one configuration and one sign-in, point WSL at the Windows folder.

export CODEX_HOME=/mnt/c/Users/<windows-user>/.codex

Updating and uninstalling

• Update the standalone install by running the PowerShell command again, or with codex update where your release supports self-update. The script reports the old and new versions.
• Update an npm install with npm install -g @openai/codex, and remove it with npm uninstall -g @openai/codex.
• Remove the standalone install by deleting %LOCALAPPDATA%\Programs\OpenAI\Codex\bin and %USERPROFILE%\.codex\packages\standalone, then taking the bin folder off your user PATH. Leave the rest of .codex if you may come back; it holds your settings.

Windows errors the docs name

• Native sandbox setup failed. Usually a declined UAC prompt, or policy that blocks creating local users and groups or firewall rules. Retry and accept the prompt, or set sandbox = "unelevated".
• Windows error 1385. The sandbox users were created but policy denies them the logon type they need. That is a machine or domain policy for your IT team.
• A warning that Everyone can write to a folder. The folder’s permissions are too broad for the sandbox to protect. Remove the broad write access.
• Network unreachable inside a task. Often deliberate: the permission mode runs that task offline.
• It worked yesterday and not today. Moving the repository, changing its permissions or a Windows policy update can all break the sandbox; restart Codex and let it run setup again.
• npm scripts fail with an execution policy error. The Windows app guide suggests Set-ExecutionPolicy -ExecutionPolicy RemoteSigned.
• Git is missing. Install it with winget install --id Git.Git.

For a report to OpenAI, the sandbox log is CODEX_HOME\.sandbox\sandbox.log. Do not send anything from the .sandbox-secrets folder beside it.

Once it runs: give it a list to work from

Nothing about the board changes on Windows except the path. MCP servers go in %USERPROFILE%\.codex\config.toml, and codex mcp add writes them there for you. Connect fenbs and Codex reads the task in Next Up, moves it to In Progress, comments what it did and moves it to Completed, all under your role and recorded in the board’s History under its name. The steps are in Codex CLI on fenbs, and the day-to-day rhythm in Codex CLI setup.