Native Windows or WSL2?

The default is the Windows-native agent, running commands in PowerShell with the native Windows sandbox; the app can still work with projects that live in WSL2 by using the wsl CLI when needed. To run the agent itself in WSL2, open Settings, switch the agent from Windows native to WSL, and **restart the app**. Note that WSL1 was supported through Codex 0.114 — from 0.115 the Linux sandbox moved to bubblewrap and WSL1 is no longer supported.

Where should the project live?

If you plan to keep using the Windows-native agent, the documentation prefers storing projects on the Windows filesystem and accessing them from WSL through /mnt/ /..., calling that more reliable than opening projects directly from the WSL filesystem. If you do need to add a project from the WSL filesystem, click Add new project or press Ctrl+O, type \\\\wsl$\\ into the File Explorer window, then choose your distribution and folder.

How do I know the sandbox is actually applied?

The documentation is direct about this: the native Windows sandbox applies when the agent runs in PowerShell, Linux sandboxing applies in WSL2, and **to apply sandbox protections in either mode you must select Ask for approval beneath the composer before sending messages to Codex**.

npm says "running scripts is disabled" in PowerShell.

That is the execution policy. The documentation notes this can happen if you have never used tools such as Node.js or npm in PowerShell before, or if Codex creates PowerShell scripts for you. A common fix is Set-ExecutionPolicy -ExecutionPolicy RemoteSigned, and the documentation recommends checking Microsoft's execution policy guide for details and other options before changing it.

Does Codex CLI in WSL share my Windows sign-in?

Not automatically. The Windows app uses %USERPROFILE%\\.codex as its Codex home, while a CLI inside WSL uses the Linux home directory by default. Two documented ways to share them - sync WSL's ~/.codex with %USERPROFILE%\\.codex on the filesystem, or point WSL at the Windows Codex home by setting CODEX_HOME.

Running the ChatGPT desktop app and Codex on Windows

Installing on Windows, choosing between the native sandbox and WSL2, setting the editor and integrated terminal, which dev tools to install, and the PowerShell execution policy, Git detection and CODEX_HOME issues you will actually hit.

CurrentLast verified 2026-09-10

Platforms

ChatGPT desktop app (Windows)

What the official documentation says

The Windows app supports core workflows including worktrees, scheduled tasks, Git functionality, the built-in browser, file previews, plugins and skills.
ChatGPT desktop app for Windows
It runs natively on Windows using PowerShell and the Windows sandbox, or can be configured to run in WSL2.
ChatGPT desktop app for Windows
The command-line install path is: winget install --id 9PLM9XGG6VKS -s msstore.
ChatGPT desktop app for Windows
The native Windows sandbox applies when the agent runs in PowerShell and Linux sandboxing applies in WSL2; to apply sandbox protections in either mode you must select Ask for approval beneath the composer before sending messages.
ChatGPT desktop app for Windows
The documentation warns that running Codex in full access mode means it is not limited to your project directory and might perform unintentional destructive actions leading to data loss.
ChatGPT desktop app for Windows
You can choose a default app for Open such as Visual Studio or VS Code and override it per project; a project-specific choice already made from the Open menu takes precedence.
ChatGPT desktop app for Windows
The integrated terminal can be PowerShell, Command Prompt, Git Bash or WSL, and the change applies only to new terminal sessions.
ChatGPT desktop app for Windows
By default the app uses the Windows-native Codex agent running commands in PowerShell; to add a project from the WSL filesystem, click Add new project or press Ctrl+O and type \\\\wsl$\\ into the File Explorer window.
ChatGPT desktop app for Windows
If you keep using the Windows-native agent, the documented preference is storing projects on the Windows filesystem and accessing them from WSL through /mnt/<drive>/..., which is more reliable than opening projects directly from the WSL filesystem.
ChatGPT desktop app for Windows
To run the agent itself in WSL2, switch the agent from Windows native to WSL in Settings and restart the app; the change does not take effect until you restart.
ChatGPT desktop app for Windows
WSL1 was supported through Codex 0.114; starting in 0.115 the Linux sandbox moved to bubblewrap, so WSL1 is no longer supported.
ChatGPT desktop app for Windows
The Windows app uses the same Codex home directory as native Codex on Windows, %USERPROFILE%\\.codex.
ChatGPT desktop app for Windows
To run commands with elevated permissions, start the ChatGPT desktop app itself as an administrator; the Codex agent inherits that permission level.
ChatGPT desktop app for Windows

The Windows build is not a cut-down build

To settle a common worry first: the Windows ChatGPT desktop app supports the core workflows, and the documentation names them — worktrees, scheduled tasks, Git functionality, the built-in browser, file previews, plugins and skills.

It runs natively on Windows using PowerShell and the Windows sandbox, or it can be configured to run in WSL2.

Install from the Microsoft Store, or from the command line:

winget install --id 9PLM9XGG6VKS -s msstore

Enterprise installation and update paths have their own deployment documentation.

Decision one: where the agent runs

This is the most consequential setting on Windows, because it decides the environment commands execute in.

Default: the Windows-native agent. Commands run in PowerShell, with the native Windows sandbox. Even so, the app can still work with projects that live in WSL2 by using the wsl CLI when needed.

Alternative: WSL2. Open Settings, switch the agent from Windows native to WSL, and restart the app — the documentation calls out specifically that the change does not take effect until you restart. Your projects should remain in place afterwards.

One version fact to keep: WSL1 was supported through Codex 0.114. Starting in 0.115 the Linux sandbox moved to bubblewrap, so WSL1 is no longer supported.

And one that is easy to conflate: the integrated terminal is configured independently from the agent. You can keep the agent in WSL and still use PowerShell in the terminal, or use WSL for both.

The sandbox has a manual step

This deserves its own heading because it does not happen by default.

The documentation says it plainly: the ChatGPT desktop app on Windows supports a native Windows sandbox when the agent runs in PowerShell, and uses Linux sandboxing when the agent runs in WSL2 — and to apply sandbox protections in either mode, select Ask for approval beneath the composer before sending messages to Codex.

The accompanying warning is not softened either: running Codex in full access mode means Codex is not limited to your project directory and might perform unintentional destructive actions that can lead to data loss. The documented guidance is to keep sandbox boundaries in place and use rules for targeted exceptions — or, based on your approval and security setup, set your approval policy to never so Codex attempts to solve problems without asking for escalated permissions.

Which filesystem the project should live on

This is where Windows + WSL setups most often go wrong, and the documentation has a clear preference.

If you plan to keep using the Windows-native agent: store projects on the Windows filesystem and access them from WSL through /mnt/<drive>/.... The documentation states directly that this setup is more reliable than opening projects from the WSL filesystem.

If you do need to add a project from the WSL filesystem: click Add new project or press Ctrl+O, type \\wsl$\ into the File Explorer window, then choose your Linux distribution and folder.

A related known issue: Git may not be detected for projects opened from \\wsl$. The documented workaround is exactly the advice above — keep the project on the native Windows drive and reach it from WSL through /mnt/<drive>/....

Configuring your dev setup

Preferred editor — choose a default app for Open, such as Visual Studio, VS Code or another editor. You can override that per project; if you already picked a different app from the Open menu for a project, that project-specific choice takes precedence.

Integrated terminal — depending on what you have installed, the options include PowerShell, Command Prompt, Git Bash and WSL. This change applies only to new terminal sessions: if an integrated terminal is already open, restart the app or start a new chat before expecting the new default.

Developer tools — the documentation lists what Codex works best with, and what each one buys you:

Git — powers the review panel in the desktop app and lets you inspect or revert changes.
Node.js — commonly used by the agent to perform tasks more efficiently.
Python — same.
.NET SDK — useful for building native Windows apps.
GitHub CLI — powers GitHub-specific functionality in the app.

Install them in one go:

winget install --id Git.Git
winget install --id OpenJS.NodeJS.LTS
winget install --id Python.Python.3.14
winget install --id Microsoft.DotNet.SDK.10
winget install --id GitHub.cli

After installing the GitHub CLI, run gh auth login to enable GitHub features in the app. Change the package IDs if you need a different Python or .NET version.

Three problems you will actually hit

PowerShell's execution policy blocks commands. If you have never used tools such as Node.js or npm in PowerShell before — or if Codex creates PowerShell scripts for you — you may see:

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

A common fix:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned

The documentation recommends checking Microsoft's execution policy guide for details and other options before changing the policy.

You need elevated permissions. The documented approach is to start the ChatGPT desktop app itself as an administrator — after installation, find it in the Start menu and choose Run as administrator. The Codex agent inherits that permission level.

The CLI in WSL does not share your sign-in. The Windows app uses the same Codex home directory as native Codex on Windows: %USERPROFILE%\.codex. A Codex CLI running inside WSL uses the Linux home directory by default, so it does not automatically share configuration, cached auth, or session history. Two documented options:

Sync WSL's ~/.codex with %USERPROFILE%\.codex on your filesystem.
Point WSL at the Windows Codex home:

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

Add it to your WSL shell profile — ~/.bashrc or ~/.zshrc — to make it apply in every shell.

Local environment scripts

If your local environment uses cross-platform commands such as npm scripts, you can keep one shared setup script or set of actions for every platform. Create Windows-specific setup scripts or actions only when you need Windows-specific behaviour.

One execution-context distinction is worth remembering: actions run in the environment used by your integrated terminal, while local setup scripts run in the agent environment — WSL if the agent uses WSL, PowerShell otherwise.

How to do it

Install the ChatGPT desktop app; from the command line, run winget install --id 9PLM9XGG6VKS -s msstore in PowerShell.
Decide where the agent runs — Windows native (PowerShell plus the Windows sandbox) by default, or switch to WSL in Settings and restart the app.
Select Ask for approval beneath the composer before sending messages so sandbox protections apply.
Set the default editor for Open and the default integrated terminal.
Install the common developer tools — Git, Node.js, Python, the .NET SDK and the GitHub CLI.
Run gh auth login after installing the GitHub CLI to enable GitHub features in the app.

On Windows

Install: winget install --id 9PLM9XGG6VKS -s msstore
Dev tools: winget install --id Git.Git, winget install --id OpenJS.NodeJS.LTS, winget install --id Python.Python.3.14, winget install --id Microsoft.DotNet.SDK.10, winget install --id GitHub.cli. Change the package IDs if you need a different Python or .NET version.
If PowerShell blocks scripts (for example: npm.ps1 cannot be loaded because running scripts is disabled on this system), a common fix is Set-ExecutionPolicy -ExecutionPolicy RemoteSigned — check Microsoft's execution policy guide before changing it.
For elevated permissions, find the app in the Start menu and choose Run as administrator.
To share config and auth with WSL, either sync WSL's ~/.codex with %USERPROFILE%\.codex, or set export CODEX_HOME=/mnt/c/Users/<windows-user>/.codex in WSL (add it to ~/.bashrc or ~/.zshrc to make it permanent).

On mobile

N/AThis tutorial covers configuring a Windows desktop environment. The official Windows page does not describe mobile behaviour. To check or steer work on this Windows host from a phone, see the Codex Remote tutorial.

Use cases

Setting up a Codex development environment on Windows for the first time.
Deciding where a project should live and which agent to use when the codebase is in WSL.
Diagnosing npm scripts blocked by the PowerShell execution policy.

Common mistakes

Switching the agent to WSL in Settings and not restarting the app. The documentation states the change does not take effect until you restart.
Using the Windows-native agent with projects stored directly on the WSL filesystem. The documented preference is the Windows filesystem, reached from WSL through /mnt/<drive>/....
Expecting the review panel to work without Git installed.
Reaching for full access to save time. The documentation attaches an explicit data-loss warning to it.
Assuming a Codex CLI running inside WSL shares the Windows app's configuration and cached auth.

FAQ

Native Windows or WSL2?: The default is the Windows-native agent, running commands in PowerShell with the native Windows sandbox; the app can still work with projects that live in WSL2 by using the wsl CLI when needed. To run the agent itself in WSL2, open Settings, switch the agent from Windows native to WSL, and **restart the app**. Note that WSL1 was supported through Codex 0.114 — from 0.115 the Linux sandbox moved to bubblewrap and WSL1 is no longer supported.
Where should the project live?: If you plan to keep using the Windows-native agent, the documentation prefers storing projects on the Windows filesystem and accessing them from WSL through /mnt/<drive>/..., calling that more reliable than opening projects directly from the WSL filesystem. If you do need to add a project from the WSL filesystem, click Add new project or press Ctrl+O, type \\\\wsl$\\ into the File Explorer window, then choose your distribution and folder.
How do I know the sandbox is actually applied?: The documentation is direct about this: the native Windows sandbox applies when the agent runs in PowerShell, Linux sandboxing applies in WSL2, and **to apply sandbox protections in either mode you must select Ask for approval beneath the composer before sending messages to Codex**.
npm says "running scripts is disabled" in PowerShell.: That is the execution policy. The documentation notes this can happen if you have never used tools such as Node.js or npm in PowerShell before, or if Codex creates PowerShell scripts for you. A common fix is Set-ExecutionPolicy -ExecutionPolicy RemoteSigned, and the documentation recommends checking Microsoft's execution policy guide for details and other options before changing it.
Does Codex CLI in WSL share my Windows sign-in?: Not automatically. The Windows app uses %USERPROFILE%\\.codex as its Codex home, while a CLI inside WSL uses the Linux home directory by default. Two documented ways to share them - sync WSL's ~/.codex with %USERPROFILE%\\.codex on the filesystem, or point WSL at the Windows Codex home by setting CODEX_HOME.

Official sources

These are the pages this tutorial is checked against. Follow them if you need the vendor's exact wording.

ChatGPT desktop app for Windows
https://learn.chatgpt.com/docs/windows/windows-app.md

Source status