Codex · Part 2

Codex — Part 2 — Installing Codex CLI (and Fixing It When It Breaks)

A practical install walkthrough for Windows, macOS, and Linux, plus a troubleshooting table for the sandbox and package-name mistakes that trip up IT engineers most often.

By K Shankar R Karanth Codex Series Part 2
Quick idea: Installing Codex is a single command, but the Windows sandbox it runs commands inside has its own setup requirements that are worth understanding before you hit them as an error.
@openai/codex

The exact npm package name. The bare codex package on npm is an unrelated project from 2012.

Native on Windows

Runs directly on Windows through a dedicated sandbox model, no WSL or virtual machine required.

codex login

The command that authenticates your session, with a device-code fallback for headless machines.

Introduction

Part 1 covered what Codex is. This post is the practical follow-up: getting it installed, signed in, and confirming it works, plus the specific errors that show up most often on a Windows work machine.

System Requirements

Codex runs natively on Windows, macOS, and Linux. On Windows, Windows 11 is the recommended version; Windows 10 1809 and later works on a best-effort basis, and older builds are not recommended. The native Windows sandbox depends on winget being available and a modern console with ConPTY support.

Practical note: Codex runs directly on native Windows without needing WSL or a virtual machine. It supports parallel tasks, worktrees, git operations, and Skills the same way on Windows as elsewhere.

Installing Codex CLI

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

# macOS and Linux
curl -fsSL https://chatgpt.com/codex/install.sh | sh

# npm (any platform with Node installed)
npm install -g @openai/codex

# Homebrew (macOS, or Linux with Homebrew installed)
brew install --cask codex
Important: The npm package is @openai/codex, not codex. Running npm install -g codex installs an unrelated package from 2012 that has nothing to do with OpenAI’s tool. This is the single most common install mistake reported by users.

Verify and Sign In

# Confirm the binary is installed and on PATH
codex --version

# Sign in through the ChatGPT browser flow
codex login

# For headless machines: device-code flow instead of a browser
codex login --device-auth

# Check which authentication method is currently active
codex login status
Key point: If you sign in with an email and password rather than a social login provider, OpenAI requires MFA on your account before you can access Codex cloud. Social login users are not required to enable MFA on ChatGPT itself for this.

The Windows Sandbox, Briefly

On Windows, Codex enforces filesystem and network boundaries using a sandbox rather than relying on WSL isolation. There are two modes, configured in config.toml. 

# %USERPROFILE%\.codex\config.toml
[windows]
sandbox = "elevated"   # preferred: dedicated low-privilege sandbox user, firewall rules
# sandbox = "unelevated"  # fallback: ACL-based boundaries, weaker, used when admin approval is blocked

The elevated mode is preferred and creates a dedicated lower-privilege sandbox user with real filesystem permission boundaries and firewall rules. The unelevated fallback uses a restricted Windows token derived from your own account instead, weaker but available when administrator approval for the elevated setup is blocked by policy.

Troubleshooting Cheat Sheet

Symptom Likely Cause Fix
codex command runs but behaves nothing like documented The wrong npm package was installed Run npm uninstall -g codex, then install the correct package with npm install -g @openai/codex.
Sandbox helper not found during setup The Windows install layout was not fully resolved on PATH after a fresh install Close and reopen the terminal so the updated PATH takes effect, then re-run Codex; if it persists, reinstall with the PowerShell installer command above.
Windows error 1385 during sandbox setup Local Windows policy is denying the logon type the sandbox user needs Contact your IT team to confirm sandbox user logon rights are permitted, or switch to sandbox = "unelevated" in config.toml as a fallback.
Elevated sandbox setup fails outright The UAC or administrator prompt was declined, or the machine blocks local user or group creation Approve the prompt if you have the rights to, or set sandbox = "unelevated" to use the ACL-based fallback instead.
IDE extension fails to build or run correctly on Windows Missing C++ build tools that the extension depends on Install them directly: winget install --id Microsoft.VisualStudio.2022.BuildTools -e.
Production note: If your organisation blocks local user creation or unusual logon types by policy, that is almost certainly deliberate. Talk to your security team about the elevated sandbox’s requirements rather than working around the policy yourself.

Final Thoughts

Installing Codex itself is a one-line command on every platform. Nearly every real problem an IT engineer hits afterward is either the npm package-name mix-up or something related to how the Windows sandbox needs to create a low-privilege user and firewall rules, both of which have documented, specific fixes rather than being mysterious.

Once codex --version and codex login status both return clean output, the tool itself is working and any remaining issue is project or configuration, not installation.

Key takeaway: Double-check the npm package name is @openai/codex before anything else. On Windows, a sandbox setup failure is almost always a policy or permissions question your IT team can answer, and sandbox = "unelevated" is the documented fallback while that gets sorted out.
Next in this series

Next, we create and navigate a real project: what happens the first time you point Codex at a folder, and how to work with it session to session.