Why WSL Is the Right Foundation for Codex on Windows
OpenAI treats WSL2 as the preferred path when you want Linux-native tooling for Codex on Windows. You get a real Ubuntu environment inside Windows with no dual-boot and no separate virtual machine to manage.
The difference shows up in sandbox behavior. Run Codex from PowerShell and it uses native Windows sandboxing. Run it from a WSL2 shell and it runs inside the Linux environment. Your repositories, shell tools, and Codex all live in one place, and VS Code connects to that workspace as a first-class remote.
By the end of this guide you will have:
- VS Code on Windows, configured to open into WSL by default
- Ubuntu on WSL2 with an updated package list
- Git and GitHub CLI authenticated to your GitHub account
- Codex CLI installed, verified, signed in, and used to build a Hello World web app
- An npm fallback path that keeps global installs at user level (no sudo)
Total time: under an hour on a modern machine with a decent connection.
This is the companion to our Claude Code on Windows guide. Steps 1 to 5 are the same, so the two read as a set.
Prerequisites
- Windows 10 (version 2004 or later) or Windows 11
- Administrator access to your Windows account
- A ChatGPT plan that includes Codex, or an OpenAI API key
- A GitHub account (or a few minutes to create one at Step 4)
Step 1: Install VS Code
- Go to https://code.visualstudio.com and download the Windows installer.
- Run it and accept the defaults.
- On Select Additional Tasks, check Add to PATH so
code . works from any terminal.
- Launch VS Code once so it finishes first-run setup.
Tip: Pin VS Code to your taskbar. You will open it constantly.
Step 2: Install WSL (Windows Subsystem for Linux)
2a. Open PowerShell as Administrator
Right-click the Start menu and choose Windows Terminal (Admin).
2b. Run the install command
wsl --install
This enables WSL, installs the Linux kernel, and sets up Ubuntu as the default distribution.
2c. Reboot when prompted
Ubuntu launches after the reboot and asks you to create a Linux username and password. Use a lowercase username with no spaces. You will need the password for sudo.
2d. Confirm you are on WSL2 and update Ubuntu
Codex needs WSL2. WSL1 is not supported from Codex 0.115 onward. In PowerShell:
wsl --update
wsl --list --verbose
The VERSION column should read 2. If it reads 1, run wsl --set-version Ubuntu 2, using your distribution's name from the list.
Then, in the Ubuntu terminal:
sudo apt update && sudo apt upgrade -y
sudo apt install -y bubblewrap
bubblewrap is the dependency behind the Linux sandbox. Installing it up front avoids first-run sandbox errors.
Step 3: Set WSL as the Default Terminal in VS Code
- Open VS Code and press Ctrl + Shift + P.
- Run
Terminal: Select Default Profile.
- Select WSL or Ubuntu (WSL).
New terminals (Ctrl + backtick) now open in Ubuntu with a prompt like:
yourname@DESKTOP-XXXXX:~$
If you see C:\Users\..., you are still in PowerShell. Repeat the steps.
Tip: Type code . in any WSL folder and VS Code installs the WSL Remote extension and reconnects. Look for WSL: Ubuntu in the bottom-left corner.
Step 4: Create Your GitHub Account
- Go to https://github.com and create a free account.
- Add a profile photo and your name.
- Students can apply for the GitHub Student Developer Pack at https://education.github.com/students.
Step 5: Install Git and GitHub CLI in WSL
sudo apt install git gh -y
git config --global user.name "Your Name"
git config --global user.email "your-github-email@example.com"
gh auth login
At the prompts choose GitHub.com, HTTPS, and Login with a web browser. Copy the one-time code, open the URL, paste it, and authorize. Then verify:
git --version
gh --version
gh auth status
All three should return versions or a confirmed login with no errors.
Step 6: Install Codex CLI and Build Your First App
Codex is OpenAI's coding agent for the terminal. You describe a task in plain language and it reads, edits, and runs code in your project, asking for approval at the boundaries you set.
6a. Install Codex with the standalone installer (recommended)
OpenAI's current WSL docs lead with the standalone installer:
curl -fsSL https://chatgpt.com/codex/install.sh | sh
codex --version
If codex --version prints a version number, you are ready to continue.
6b. Optional fallback: install with npm (Node.js 22 via nvm)
Use this path if your team standardizes CLI installs through npm.
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
source ~/.bashrc
nvm install 22
node --version
npm --version
Configure a user-level npm directory so global installs never need sudo:
mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
Install Codex through npm:
npm i -g @openai/codex
codex --version
6c. Sign in
Start Codex and choose how to authenticate:
codex login
- ChatGPT sign-in uses the access included with your plan. Complete the browser flow. If the browser cannot reach the CLI, run
codex login --device-auth and enter the one-time code.
- API key bills your OpenAI Platform account at API rates. Read the key without echoing it, then pipe it in:
read -rsp 'OpenAI API key: ' OPENAI_API_KEY && printf '\n'
printenv OPENAI_API_KEY | codex login --with-api-key
unset OPENAI_API_KEY
Never put a key in a repository, an AGENTS.md, or a prompt. Confirm either method worked with codex login status.
6d. Build your first app
mkdir -p ~/git/helloworld
cd ~/git/helloworld
git init
codex
Codex starts in its default approval mode, so it will ask before doing anything outside the workspace. Type:
Build me a simple Hello World web app with HTML, CSS, and JavaScript. Give it a clean modern look with a centered card, a heading that says 'Hello World', a subtitle with today's date, and a button that shows an alert when clicked. Save everything in this folder.
Approve the file writes as they come up. When it finishes, run /quit.
6e. Preview your app
In Windows Explorer, open:
\\wsl$\Ubuntu\home\yourname\git\helloworld\index.html
Double-click the file to open it in your browser.
Step 7: Open Your Project in VS Code
cd ~/git
code .
VS Code opens with WSL: Ubuntu in the bottom-left corner, and Explorer shows helloworld with the files Codex created. The integrated terminal drops into WSL, so you can edit, test, and commit as if you were on Linux.
Best Practices for AI-Assisted Development
Keep repositories under /home, not /mnt/c. Work in your WSL home directory, such as ~/git/my-app. Cross-filesystem I/O is slower and causes symlink and permission problems. If pwd starts with /mnt/c/, move the project.
Match the approval mode to the risk. Sandbox mode sets what Codex is allowed to touch. Approval policy sets when it must ask. Two settings cover most work:
# Normal development: edit inside the workspace, ask before crossing it
codex --sandbox workspace-write --ask-for-approval on-request
# Investigation and review: no edits
codex --sandbox read-only --ask-for-approval on-request
You can also switch mid-session with /permissions.
Know when full access is fine and when it is not. Full access (--yolo, or --dangerously-bypass-approvals-and-sandbox) removes both the sandbox and the approval prompts. It is reasonable in a disposable environment you can throw away, such as a scratch VM or a throwaway learning project. It is the wrong choice on a shared repository, a codebase with credentials nearby, or anything you cannot rebuild. For those, stay on workspace-write with on-request approval so you keep oversight.
Use /plan before non-trivial changes. Type /plan followed by your request. Codex investigates and proposes an approach without implementing it. Reviewing the plan takes a minute and prevents unwanted changes. Entering Plan mode does not grant write access, and permissions are a separate setting.
Use AGENTS.md as the counterpart to CLAUDE.md. Run /init inside Codex to create a starter AGENTS.md, then edit it. Record build and test commands, conventions, and what Codex must not change. Commit it so the whole team shares the rules. Keep it short, because those tokens load on every task. If your team also uses Claude Code, the same facts belong in both files.
Keep sessions short. Every file read, test log, and message consumes context. Run /status to see usage, /compact to summarize earlier conversation, and /new when the next job is unrelated. Small, focused sessions beat marathon ones. Restate any critical constraint after a compact.
Review before you commit. Run /diff, then /review for a second pass, then run your own tests and check git status.
Check your plan or billing. ChatGPT sign-in follows your plan's limits. API-key sign-in bills per token at platform.openai.com.
What's Next?
For teams looking to bring agentic AI into enterprise workflows with HITL controls, private-by-architecture deployment, and outcome-based contracts, talk to the lowtouch.ai team.
