Using Codex on Windows

Who this is for

This is for developers on Windows who want to run Codex in the desktop app, the CLI or the IDE extension. By the end you can install the app, choose between a PowerShell agent and a WSL2 agent, understand the three sandbox modes, and fix the most common setup errors.

Install the desktop app

The ChatGPT desktop app for Windows gives you one interface for working across projects, running parallel chats and reviewing results. It supports worktrees, scheduled tasks, Git, the built-in browser, file previews, plugins and skills.^[1] You can download it from Microsoft's installer link, or install it from the command line:^[1]

winget install --id 9PLM9XGG6VKS -s msstore

Pick where the agent runs

By default the app uses the Windows-native Codex agent, which runs commands in PowerShell. It can still work with projects in WSL2 through the wsl CLI when needed.^[1] To run the agent inside WSL2, open Settings, change the agent from Windows native to WSL, and restart the app. The change takes effect only after the restart.^[1]

WSL1 was supported through Codex 0.114. From Codex 0.115 the Linux sandbox moved to bubblewrap, so WSL1 is no longer supported.^[1]

Install developer tools

Codex works best with a few common tools: Git, which powers the review panel and lets you inspect or revert changes; Node.js and Python; the .NET SDK; and the GitHub CLI, which powers GitHub features in the app.^[1] The docs suggest installing them with winget:^[1]

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 so GitHub features work in the app.^[1] If you need another Python or .NET version, change the package IDs.^[1]

Windows sandbox modes

Codex has three Windows sandbox implementations: mxc, elevated and unelevated.^[2] The sandbox enforces the active filesystem and network permissions for commands and their child processes. Approval policy is a separate setting that controls when Codex asks to run commands with more access.^[2]

• mxc is the recommended option on compatible devices. It uses native process isolation without administrator-approved setup, extra Windows accounts or local firewall rules.^[2]
• elevated is the preferred legacy fallback when MXC is unavailable or disabled. It needs administrator-approved setup, and commands in the sandbox run without administrator privileges.^[2]
• unelevated is a legacy fallback for when elevated setup is not possible and your organization allows it. Its network isolation is weaker, and it does not support denied read paths.^[2]

Windows 11 is the recommended base. Recent, fully updated Windows 10 is best effort and needs version 1809 or newer for ConPTY support. Older Windows 10 builds are not recommended.^[2]

Turn on MXC, or choose a fallback

To prefer MXC, set this in config.toml:^[2]

[features]
prefer_mxc = true

When the device and policy support it, Codex uses MXC. Otherwise it falls back to the existing legacy selection and setup flow.^[2] MXC needs native capabilities that Microsoft introduced in Windows 11 24H2 (build 26100.9278) and 25H2 (build 26200.9278).^[2] To check one command without changing your saved setting, use Codex CLI 0.162.0 or later and run this from the project directory. The expected output is MXC_OK and exit code 0:^[2]

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

Keep in mind that windows.sandbox = "mxc" fails if the native capabilities are missing or policy blocks MXC. Child processes also stop when the foreground command exits, so a workflow that relies on a detached development server needs testing. Managed networking requires allow_local_binding = true.^[2]

To select the legacy fallback, set this in config.toml:^[2]

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

Administrators can block MXC with allow_mxc = false under [windows] in the managed requirements.toml. That blocks automatic selection and an explicit windows.sandbox = "mxc" alike.^[2]

Common problems

PowerShell says scripts are disabled. If PowerShell refuses to run npm.ps1 because scripts are disabled, a common fix is Set-ExecutionPolicy -ExecutionPolicy RemoteSigned. Read Microsoft's execution policy guide before you change the policy.^[1]

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned

Commands need admin rights. Start the ChatGPT desktop app itself as an administrator. The Codex agent inherits that permission level.^[1]

Error 1385. Sandboxed commands fail with error 1385 when Windows policy denies the logon type the sandbox user needs. Ask IT to grant the rights, or use unelevated while you investigate. When you report it, include CODEX_HOME/.sandbox/sandbox.log and your Windows version.^[2]

Folders are writable by Everyone. Codex may warn that some folders are writable by Everyone. Remove that write access if your environment allows it.^[2]

Git is missing. Without a native Git install, some app features are unavailable. Install it with winget install Git.Git.^[1]

Sharing config with WSL. The app and the native Windows CLI use %USERPROFILE%\.codex. A Codex CLI inside WSL uses the Linux home by default, so it does not share configuration, cached auth or session history. To point WSL at the Windows directory, set CODEX_HOME in your shell profile:^[1]

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

Full access mode. Full access means Codex is not limited to the project directory and might make destructive changes. Keep the sandbox boundaries, and use rules for specific exceptions.^[2]

Next steps

Install the app, confirm the agent runs where you want it, and check the MXC test before you rely on it for real work. The official pages cover the enterprise deployment options.^[1]