Key Windows Considerations: Native vs. WSL, How to Run Hassle-Free

📚 Series Navigation: The previous article "32 Migrate from Claude Code" talked about "how to smoothly switch to Codex once you are familiar with Claude Code." This article is specifically for Windows users—the first thirty-odd articles assumed you were running commands on Mac or Linux, but most of us use Windows. Paths, line endings, and sandboxing are completely different sets of rules. The next article "34 Capstone Project" will weave together everything learned in the Codex section into a complete project.

Let me share a foolish thing I did.

In March 2026, when I first installed Codex on my corporate Windows 11 laptop, I skipped installing WSL for convenience and ran it directly in native PowerShell. It installed fine, but as soon as I had it modify a file, it threw errors. I stared at the logs for a long time only to realize: the project I had git clone'd from my Mac had script files using LF line endings. Git on Windows had automatically converted them to CRLF by default. When Codex finished modifying and saved, the diff for the entire file was filled with ^M, meaning every single line was marked as "modified". I thought Codex had a bug and drafted an issue, only to realize I simply didn't understand Windows line ending rules.

To be honest, Codex can run natively on Windows now, and the experience isn't bad, but it's not the same as Mac/Linux. Windows has two unique sandboxing mechanisms, paths use backslashes, and line endings carry historical baggage. If you don't know these pitfalls in advance, you will trip over them sooner or later.

This article explains the ins and outs of Windows: how to install it, how to choose between native and WSL, how to avoid three Windows-specific pitfalls, how sandboxing differs from Mac/Linux, and finally, how to run a minimal example in PowerShell.

After reading this article, you will get:

• A one-line conclusion: What is the most hassle-free way to run on Windows, saving you from indecision
• Complete steps to install Codex using the official PowerShell script, plus several essential Windows prerequisites
• A trade-off comparison between "Native PowerShell vs. WSL2": What kind of developer you are and which path you should choose
• How to avoid three Windows-specific pitfalls: path backslashes, CRLF line endings, and the Everyone write permissions warning
• The differences between Windows' elevated / unelevated sandbox modes and Mac/Linux, and what to do when error 1385 occurs
• A hands-on process you can follow to run your first Codex task from scratch on Windows

⚠️ All commands, configurations, and default behaviors are based on the official Codex documentation. Model names, plan scopes, and version numbers will change with updates; please refer to your local codex --help and actual interface. I've labeled whether commands should run in PowerShell or WSL shell—don't run them in the wrong place.

---

01 One-line Conclusion: The Most Hassle-Free Way on Windows

Let's get straight to the point to save you from debating:

Use "Native Windows + elevated sandbox" by default. This is the officially recommended approach, offering the fastest speed with no compromise on security. Only fall back to WSL2 if your workflow is already centered in Linux, or if neither native sandbox mode can run on your corporate machine.

I know many older tutorials (including some localized sites) will tell you that "Windows recommends unelevated" or "WSL is recommended first"—these claims are outdated. The official documentation now clearly states: the native Windows sandbox offers the best performance and fastest speed, with security equivalent to other platforms. elevated is the first choice, while unelevated is only a fallback.

Analogy: Installing broadband. When the technician comes, they first install fiber-to-the-home (elevated), which is the fastest and most stable option. Only when there is no fiber in your building or cabling is blocked by property management do they fall back to a LAN cable (unelevated). If all else fails, you consider moving to an adjacent room with internet to work (WSL2). Most people can just connect to fiber directly, without needing to bother with the latter two.

In practice, this choice maps to three kinds of users:

• You just want to write code normally on Windows using the Windows toolchain—run natively under elevated without a second thought.
• You are on a managed corporate machine where IT locks administrator rights—you won't be able to install native elevated; use unelevated temporarily, and check with IT.
• Your projects are already in WSL and you are used to Linux tools—run directly in WSL2, avoiding jumping back and forth between Windows and Linux.

💡 Summary: Default to "Native Windows + elevated." WSL2 is reserved for those who "already live in Linux" and is not the default starting point.

---

02 Installation and Prerequisites

To install Codex CLI on Windows, the most direct official route is using the built-in PowerShell installation script, which gets it done in one line.

Run in PowerShell or Windows Terminal:

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

If you already have Node.js installed, you can also use npm as an official alternative path:

npm install -g @openai/codex

After installation, restart the terminal to let the PATH take effect, and verify:

codex --version

The expected output is a version number (the exact digits depend on your install) formatted like codex 0.x.x. If it prints, it is installed successfully.

Want a graphical interface instead of the command line? The official Windows desktop version of the Codex app is available directly from the Microsoft Store. Alternatively, install it with winget install Codex -s msstore. This article focuses on the CLI, and the commands below revolve around the codex command line.

Prerequisites to prepare beforehand to avoid issues:

Dependency	Why It's Needed	How to Resolve
Windows 11 (Recommended)	Official preferred baseline, most stable	Upgrade to Windows 11; Windows 10 is supported but requires version 1809 or newer
winget available	Needed for installing C++ build tools and the desktop app	If missing, update Windows or install App Installer
Admin approval privileges	Required for initializing the elevated sandbox	On personal PC, click "Agree"; company PC may block this
C++ Build Tools (when using IDE extension)	Some native dependencies require compilation	Run winget install --id Microsoft.VisualStudio.2022.BuildTools -e

When I first installed it on Windows 10, the IDE extension installed but kept spinning and was unresponsive. After struggling for twenty minutes, I found it in the troubleshooting section of the official docs—the C++ workload for Visual Studio Build Tools was missing. After running that winget install command and restarting VS Code, it worked immediately. So if you use the Codex extension in VS Code, we recommend preparing the C++ build tools from the start.

💡 Summary: A single PowerShell installation script handles the Codex CLI. Focus on checking the Windows version, ensuring winget is available, and securing administrator rights.

---

03 WSL vs. Native PowerShell: Which Path Suits You?

This is the very first question Windows users must figure out. Despite all the debates online, the standard is simple: look at where your code and daily workflow live.

Analogy: Choosing a city to settle in. Native PowerShell is like settling in the Windows city, following Windows procedures, which is fastest and smoothest. WSL2 is like renting a Linux apartment in the city—if you want to use Linux tools and run Linux scripts, you go inside to work. Both are livable, but you can't commute back and forth between the Windows and Linux offices every day—picking a primary workspace is much easier.

Dimension	Native PowerShell	WSL2
Setup Difficulty	✅ Handled in one installation script	❌ Requires running wsl --install to install a distro first
Speed	✅ Native is fastest	File I/O is slightly slower, crossing drive boundaries is slower
Sandbox Implementation	Windows-specific (elevated/unelevated)	Runs Linux's bubblewrap sandbox
Suitable Toolchain	✅ Windows native tools, .exe	✅ Linux native tools, bash scripts
Suitable For	Most Windows users	Developers whose projects are already in Linux

When to choose native PowerShell? If you are an ordinary Windows user writing code in VS Code and using Windows' Git—go native. Don't add the burden of WSL.

When to choose WSL2? Three scenarios: you need the Linux native toolchain; your repository and workflow are already in WSL2; or neither native sandbox mode works on your machine.

To go with WSL2, first install it in PowerShell as Administrator:

wsl --install
wsl

Once inside the WSL shell, Codex must be reinstalled in Linux (the Windows installation does not carry over):

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

Here's a pitfall I fell into in April 2026: I put the repository under /mnt/c/Users/... (Windows C drive, mounted and accessed from WSL) for convenience, and Codex ran incredibly slowly—even a git status took several seconds. I later learned that WSL access to Windows mounted drives (/mnt/c/...) suffers from very slow file I/O, so you must move the repository to the native Linux home directory:

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

Once moved, the speed became normal immediately. When you need to access these files from Windows, enter \\wsl$\Ubuntu\home\<user> in File Explorer (replace <user> with your Linux username). Also, WSL1 is no longer supported starting with Codex 0.115 (since the sandbox transitioned to bubblewrap). When you install WSL, it defaults to WSL2 anyway, so you don't need to worry.

💡 Summary: Use native PowerShell if your code is on Windows; use WSL2 and place the repository under ~/ (instead of /mnt/c) if your code lives on Linux.

---

04 Three Windows-Specific Pitfalls: Paths, Line Endings, and Permissions

This section is the core of this article. Pitfalls that Mac/Linux users never encounter are all present on Windows.

Pitfall 1: Path Backslashes

Windows paths use backslashes C:\Users\You\project, whereas Unix uses forward slashes /home/you/project. Codex usually handles this difference automatically, but you must pay attention in two places:

• Paths written to ~/.codex/config.toml: We recommend using strict absolute paths, like C:\absolute\directory\path.
• When adding sandbox readable directories to Codex: Paths must be absolute directories that already exist. Run this command (inside the Codex interactive terminal):

/sandbox-add-read-dir C:\absolute\directory\path

After running successfully, subsequent commands run in the sandbox during this session will be able to read this directory. Note that this is only valid for the current session; you must add it again if you start a new session.

Pitfall 2: CRLF Line Endings

Let's be clear: this is a general Git line ending issue on Windows, not a problem with Codex itself. However, because Codex modifies files, you are highly likely to encounter it here.

Analogy: Different electrical outlets. LF (Unix line endings) and CRLF (Windows line endings) are like different styles of outlets in different countries. While both represent a "line break," the underlying representation contains an extra \r. If you clone a project from Mac/Linux colleagues that uses LF, Git on Windows might convert it to CRLF by default. When Codex saves its edits, every line in the file "changes," causing the diff to blow up.

That was how I tripped. The solution is to unify the line endings policy. The easiest way is putting a .gitattributes file in the project root to stop Git from auto-converting:

* text=auto eol=lf

Or globally disable Git's automatic conversion (run in PowerShell):

git config --global core.autocrlf false

Which to choose depends on your team's agreement, but the core takeaway is: do not let line endings be secretly modified across platforms, otherwise every change you or Codex make will be drowned in line ending noise.

Pitfall 3: Everyone Write Permission Warning

When running natively, Codex might warn that "some folders are writable by Everyone." This is not a bug—it is warning you that these folders have too broad Windows permissions, preventing the sandbox from protecting them. The resolution is to remove the Everyone write permissions from those folders, then restart Codex or rerun the sandbox initialization. If you are unsure how to change permissions, consult IT instead of forcing it.

Pitfall	Symptoms	How to Avoid
Path Backslashes	Configurations/reading directories do not take effect	Use absolute paths; use existing absolute directories for /sandbox-add-read-dir
CRLF Line Endings	Every line is marked as modified in diff, full of ^M	Set eol=lf in .gitattributes or disable core.autocrlf
Everyone Writable	Codex warns that folder permissions are too broad	Remove Everyone write permissions and restart Codex

💡 Summary: Use absolute paths, lock line endings using .gitattributes, and don't ignore permission warnings. Address these three pitfalls, and the Windows experience will match Mac.

---

05 Sandboxing and Permissions: Windows vs. Mac/Linux

Codex's sandbox (the safety fence restricting file writes and network access) is implemented differently on each platform. Mac uses the system's sandbox-exec, Linux uses bubblewrap, and Windows features two completely independent modes of its own.

On native Windows, the sandbox in agent mode blocks "file writes outside the working folder" as well as "network access without your consent." You can configure it in ~/.codex/config.toml (write to config file):

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

Let me clarify the differences between the two modes:

Mode	Level	Implementation	When to Use
elevated (Preferred)	Stronger	Dedicated low-privilege sandbox user + file system boundaries + firewall rules + local policy adjustments	Use it by default; best performance and security
unelevated (Fallback)	Weaker	Restrained token derived from current user + ACL file system boundaries + environment-level offline control	Use as a fallback when elevated cannot be installed

Note: This is exactly opposite to older tutorials that "recommended unelevated." The official documentation explicitly states elevated is preferred, and unelevated is only a temporary fallback when elevated cannot be installed due to restricted privileges. Both modes also enable "private desktop" by default for UI isolation; unless you need compatibility with old Windows Station Winsta0\Default session desktop behaviors, do not disable windows.sandbox_private_desktop.

Why might elevated fail to install? It needs to create a dedicated sandbox user, modify firewall rules, and adjust local policies. These actions are often blocked by IT policies on corporate managed PCs. The most typical error is 1385—meaning Windows denies the sandbox user the logon rights required to start the command. If you encounter 1385, follow these official recommendations:

1. Ask IT to verify if device policies grant the required logon rights to the "sandbox user created by Codex."
2. If only certain machines are affected, compare Group Policy or OU differences.
3. If you need to work urgently, switch to unelevated as a temporary workaround.
4. Send sandbox.log under CODEX_HOME/.sandbox/ along with the Windows version to the team for troubleshooting.

🔒 Never share this folder: CODEX_HOME/.sandbox-secrets/ contains keys. When sending logs for troubleshooting, only share sandbox.log, do not include this directory.

If a command fails because the "sandbox cannot read a directory," refer back to the /sandbox-add-read-dir command in Section 04 to add the directory.

💡 Summary: Windows has two independent sandboxes. Use elevated by default, falling back to unelevated if installation fails. Error 1385 is usually caused by company policies blocking logon rights; consult IT.

---

06 Hands-on: Running Your First Codex Task on Windows

Enough theory, let's put it into practice. Run this workflow in native PowerShell to create a project, let Codex modify files, and follow along step-by-step.

Step 1: Create a minimal test project (in PowerShell):

mkdir codex-win-test
cd codex-win-test
git init
"console.log('hi')" | Out-File -Encoding utf8 app.js

Note: In older versions of PowerShell (5.1), Out-File -Encoding utf8 adds a BOM header to the file, which might introduce some encoding noise in subsequent git diff runs. In PowerShell 7+, you can use Set-Content -Encoding utf8NoBOM to write files without a BOM, ensuring cleaner line ending verification.

Step 2: Establish line endings rules first to avoid the pitfall mentioned at the beginning. Create .gitattributes in the project root:

* text=auto eol=lf

Step 3: Start Codex:

codex

The first time you run the native sandbox, Windows may show a UAC administrator prompt (which is elevated doing its initialization). On a personal PC, click "Yes." If it's a locked company PC and you can't authorize it, Codex will automatically fall back to unelevated. You'll see a line indicating the mode switched—this is the expected fallback behavior and you can continue working.

Step 4: Give Codex a minimal task; enter the following in the interactive terminal:

Change 'hi' to 'hello, codex on windows' in app.js

Expected output: Codex reads app.js, provides a diff, and asks for your approval (it asks by default). Once confirmed, it writes to disk. Now inspect the file:

Get-Content app.js

You should see:

console.log('hello, codex on windows')

Step 5: Verify that line endings did not get messed up—this is the most important habit to build on Windows:

git diff

If you set .gitattributes correctly earlier, the diff will show only that single line of content changes, without a screen full of ^M or indicating the entire file was modified. If the diff blows up, go back to Pitfall 2 in Section 04 and handle the line endings again.

Every time I set up Codex on a new Windows machine, I run this minimal workflow first, especially the final git diff check for line endings—this is muscle memory I paid for with a whole afternoon writing an issue draft.

💡 Summary: Create project -> set .gitattributes -> start -> assign minimal task -> check line endings with git diff. Run this five-step workflow, and you're set on Windows.

---

Summary

Looking back at this article, the core takeaways are:

• Default running mode: Native Windows + elevated sandbox. Officially preferred, fastest, and secure. WSL2 is for those who "already live in Linux."
• Installation: A single official PowerShell script installs the CLI. Keep an eye on Windows version, winget availability, and admin privileges. Set up C++ build tools if using the IDE extension.
• Three specific pitfalls: Use absolute paths, lock line endings to LF in .gitattributes, and don't ignore the Everyone write permissions warning.
• Sandbox differences: Windows features two independent sandbox modes: elevated and unelevated, differing from Mac's sandbox-exec and Linux's bubblewrap. Error 1385 is typically caused by corporate policies restricting logon rights.

You should now be able to: install Codex on a clean Windows machine; determine whether to use Native or WSL; avoid path and line ending pitfalls; and run your first file-modifying task while verifying line endings.

Ultimately, using Codex on Windows isn't harder than on Mac—it just requires dealing with line endings and sandbox modes, two Windows-specific concepts. Pay this tax once, and you'll never trip over them again.

---

The next article "34 Capstone Project" wraps up the Codex section. We will no longer discuss individual features, but instead weave together what we learned across the first thirty-odd articles (configurations, models, permissions, subagents, automation, migration, Windows adaptation, etc.) to run a complete real-world project from scratch.

A quick question to ponder: if you were to pick a project now, what are the first three things you would configure and the first rule you would establish before letting Codex run your first feature after git clone? Find out in the next article.

---

Recommended Reading

• Integrating domestic models like DeepSeek
• Four Common Workflows: Exploration, Bug Fixing, Refactoring, Writing Tests
• IDE Extensions (VS Code, etc.)