Codex CLI now supports a Windows-native workflow with an official standalone installer and a native Windows sandbox. WSL2 remains a useful option when a project already depends on Linux tooling, but it is no longer the default recommendation for every Windows user. This guide separates those paths and uses the current OpenAI terminology for installation, authentication, models, permissions, and sandboxing.
Key takeaways
- Start with the official Windows standalone installer unless your development workflow already lives in WSL2.
- The preferred native sandbox is
elevated;unelevatedis a weaker fallback for machines where policy blocks the stronger setup. - WSL2 uses the Linux sandbox, which now relies on
bwrap(bubblewrap) plus seccomp. WSL1 is no longer supported by current Codex releases. - The npm package declares Node.js 16 or newer, but a current LTS release is the sensible operational baseline. The standalone installer needs no Node.js runtime.
- Use
/permissionsfor session permissions andcodex login --with-api-keyfor API-key login. Do not store a raw key in a PowerShell profile or repository.
Choose native Windows or WSL2
Use native Windows when the repository, terminal, IDE, build tools, and deployment workflow are Windows-based. OpenAI documents Windows 11 as the recommended baseline and recent, fully updated Windows 10 as best-effort support. Native operation keeps paths, Git, PowerShell, IDE integration, and the sandbox in one operating-system boundary.
Choose WSL2 when your repository and toolchain already live in Linux, you need Linux-native dependencies, or neither native Windows sandbox implementation works under your organization’s device policies. Keep a WSL repository under the Linux filesystem, such as ~/code, instead of /mnt/c to avoid cross-filesystem performance overhead.
Install Codex CLI natively on Windows
Open PowerShell and run the official standalone installer:
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"
codex --version
codex loginThe installer places the visible codex command under the user’s local application data by default. Re-running the command updates the standalone installation. For managed or unattended installs, OpenAI also documents CODEX_NON_INTERACTIVE=1; use that only after your organization has reviewed the installer and chosen its defaults.
Optional npm installation
If your team already manages developer tools through Node.js, install the scoped package. The published package supports Node.js 16 or newer; a maintained LTS version gives a better security and support posture.
npm install -g @openai/codex
codex --versionUse @openai/codex, not the unrelated unscoped codex package. A direct binary from the official openai/codex releases is another auditable option for golden images and locked-down build agents.
Configure the native Windows sandbox
Native Windows Codex supports two sandbox implementations. The preferred elevated mode uses dedicated lower-privilege sandbox users, filesystem boundaries, firewall rules, and required local policy changes. The unelevated fallback uses a restricted token, ACL-based filesystem boundaries, and environment-level offline controls. It is useful when enterprise policy blocks the stronger setup, but it provides weaker isolation.
# %USERPROFILE%.codexconfig.toml
[windows]
sandbox = "elevated" # preferred; use "unelevated" only as a fallbackIf the stronger setup fails, retry it with the required administrator approval, then ask IT to review local user or group creation, firewall changes, sandbox-user logon rights, and group policy. Error 1385 commonly indicates that Windows denied the logon type required by a sandbox user. Do not bypass the sandbox as a routine troubleshooting step.
Install Codex in WSL2
Install WSL from an elevated PowerShell session, start the Linux distribution, and then run the official Linux installer inside WSL:
# Elevated PowerShell
wsl --install
# Inside the WSL2 shell after setup
mkdir -p ~/code
cd ~/code
curl -fsSL https://chatgpt.com/codex/install.sh | sh
codex --version
codex loginCurrent Codex releases use bwrap plus seccomp for the Linux sandbox. If the distribution does not already provide bubblewrap, install it with the distribution package manager. Starting with Codex 0.115, the move to bubblewrap ended WSL1 support.
Authenticate without persisting raw keys
For interactive local work, run codex login and complete the ChatGPT browser flow. This uses subscription access and workspace controls. API-key authentication uses the OpenAI Platform account, standard API billing, and that organization’s data settings; some ChatGPT-connected features may be unavailable.
When API-key login is required, pipe the value to the login command instead of writing it into a PowerShell profile:
$secureKey = Read-Host "OpenAI API key" -AsSecureString
$plainKey = [System.Net.NetworkCredential]::new('', $secureKey).Password
$plainKey | codex login --with-api-key
Remove-Variable plainKey, secureKey
codex login statusIn CI, keep the credential in the CI provider’s secret store and expose it only to the trusted Codex step. For GitHub Actions, OpenAI recommends the official Codex action because its proxy design reduces API-key exposure to repository-controlled scripts and dependencies.
Select a model and permissions
Codex currently recommends the GPT-5.6 family: Sol for complex, open-ended work, Terra for everyday work, and Luna for clear, repeatable or high-volume work. Exact availability depends on the surface, account, workspace policy, and authentication method. Use /model and /status to inspect the live catalog instead of relying on a fixed plan or pricing table in an installation guide.
Type /permissions in an interactive CLI session to choose a permission mode or an administrator-approved named profile. Permission modes combine a sandbox boundary with an approval policy; changing who reviews an approval does not automatically expand the sandbox.
| Mode | Use |
|---|---|
| Read Only | Inspect files and plan; edits and commands require approval. |
| Workspace | Read, edit, and run routine commands inside the workspace boundary. |
| Full Access | Removes sandbox restrictions; reserve it for intentionally isolated environments. |
Windows troubleshooting checklist
The elevated sandbox setup fails
Confirm the UAC prompt was approved and that enterprise policy permits local sandbox users, firewall changes, and the required logon rights. Use unelevated temporarily while IT investigates, then return to elevated.
Codex warns about folders writable by Everyone
Review the exact paths in the warning and remove overly broad write ACLs when appropriate. Restart Codex or rerun sandbox setup after the permissions are corrected.
A sandboxed command needs another readable directory
Use /sandbox-add-read-dir C:absolutepath for an existing absolute directory. Grant only the narrow path the task needs.
WSL2 is slow
Move the repository from /mnt/c to a path such as ~/code/project, update WSL with wsl --update, and reopen the Linux shell.
Primary Sources
- OpenAI: Windows sandbox
- OpenAI: WSL
- OpenAI: Codex CLI
- OpenAI: Authentication
- OpenAI: Permissions
- OpenAI: Models
- OpenAI: Codex GitHub Action
Deploy AI development tools with a governed security boundary
ITECS helps organizations align AI coding tools with endpoint policy, identity, networking, secrets management, code review, and compliance requirements.
Schedule a consultation