Windows setup

Codex on Windows: the app or the CLI, and how to set up each one

Updated November 17, 20268 min read

Codex on Windows runs natively in PowerShell with no WSL needed, and it comes in two forms: the Codex app inside the ChatGPT desktop app, and the Codex CLI that you type into a terminal. The table below shows how the two differ. After that, one section sets up each, then come the Windows problems worth knowing about and a way to run Codex beside Claude Code.

Codex app vs Codex CLI on Windows, side by side

Codex appCodex CLI
What it isA window inside the ChatGPT desktop app for projects, parallel chats and reviewing changesThe codex command, running in your terminal
How you install itMicrosoft Store, or winget install --id 9PLM9XGG6VKS -s msstoreOpenAI's PowerShell installer, or npm install -g @openai/codex
Where the agent runsWindows native by default. You can switch it to WSL in SettingsWherever you start it: PowerShell, or inside WSL2
Extras built inWorktrees, a built-in browser, a review pane and a terminal panelSlash commands, codex exec for scripts, codex resume, MCP servers
Plans that include it (as of November 2026)Free and Go get Codex in the desktop app for lighter tasks, subject to rollout. Plus and up get moreChatGPT Plus ($20/month) and higher, or an OpenAI API key
Best forPeople who would rather click than typePeople who live in a terminal or want to script Codex

Both sign in with the same ChatGPT account, so you can install both and switch whenever you like. OpenAI's Windows docs say the app and the CLI both run natively on Windows with PowerShell and a Windows sandbox (a safety fence that limits which files and network access Codex gets).

Windows 11 is recommended. A fully updated Windows 10, version 1809 or newer, is supported on a best-effort basis. That version matters because it added ConPTY, the Windows feature that lets a program act like a real terminal.

Setting up the Codex app on Windows

  1. 1

    Install the ChatGPT desktop app

    The Codex app on Windows lives inside the ChatGPT desktop app. Get it from the Microsoft Store, or paste the first command below into PowerShell.

  2. 2

    Add the developer tools Codex leans on

    OpenAI says Codex works best with a few common tools already installed. Git matters most: without it, some app features do not work. The second code block installs Git, Node.js, Python, the .NET SDK and GitHub CLI with WinGet.

  3. 3

    Connect GitHub

    After GitHub CLI installs, run gh auth login and follow the prompts. That turns on the app's GitHub features.

  4. 4

    Sign in and add a project

    Open the app, sign in with your ChatGPT account and add the folder you want Codex to work in.

  5. 5

    Pick native or WSL

    Codex runs its agent natively by default. To use WSL instead, open Settings, switch the agent from Windows native to WSL, then restart the app. The change only applies after a restart.

  6. 6

    Choose a terminal shell

    The built-in terminal can use PowerShell, Command Prompt, Git Bash or WSL, depending on what you have installed. This is set separately from where the agent runs.

winget install --id 9PLM9XGG6VKS -s msstore
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

To keep the sandbox switched on in the app, choose Ask for approval under the message box. You only need the tools for languages you actually use, so skip Python or .NET if your projects never touch them.

Installing the Codex CLI in PowerShell

  1. 1

    Open a new PowerShell window

    A normal window is fine. You do not need to run it as Administrator.

  2. 2

    Run OpenAI's Windows installer

    Paste the first command below. The -ExecutionPolicy ByPass part lets the script run once without changing your PC's settings.

  3. 3

    Or use npm if you already have Node.js

    The npm package installs the same CLI. Pick one method, not both, so you always know which copy is running.

  4. 4

    Start it in your project and sign in

    Use cd to move into the project folder, type codex and choose Sign in with ChatGPT. You can also sign in with an OpenAI API key, billed per use.

  5. 5

    Give it a first task

    Try Tell me about this project. When Codex wants to run a command or edit a file, it asks first unless you change its permissions with /permissions.

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

To update later, run the same install command again. If something feels off, codex doctor checks your setup. Our Codex CLI guide covers the commands and slash commands in more depth.

Where the Codex CLI keeps its files on Windows

  • Your personal settings: %USERPROFILE%\.codex\config.toml. This is where you set defaults such as the model or sandbox type.
  • Settings for one project: a .codex\config.toml file inside the project. Codex only loads it for projects you have marked as trusted.
  • Project instructions: an AGENTS.md file in the project folder. Type /init in a session and Codex writes a first version for you. Add your build command, your test command and anything Codex must never touch.

For scripts or scheduled jobs, codex exec "your task" runs a task from start to finish without asking you anything. Keep that for projects you have committed to git, since nobody is there to say no.

Running the Codex CLI inside WSL

  1. Open PowerShell as Administrator, run wsl --install and restart.
  2. Open Ubuntu from the Start menu and create your Linux user.
  3. Install Codex inside Ubuntu with the Linux command below.
  4. Keep your project on the Windows drive and open it from WSL through /mnt/c/.... OpenAI suggests this because Git detection is more reliable that way.
curl -fsSL https://chatgpt.com/codex/install.sh | sh

A Codex CLI inside WSL does not automatically share its settings, saved sign-in or chat history with the Windows app. OpenAI's docs describe syncing them or pointing both at one folder with the CODEX_HOME setting.

Codex Windows issues to know before you start

Watch out

Full access mode turns the sandbox off. OpenAI notes that Codex is then no longer limited to your project folder, so one bad command can reach other files. Only turn it on for a project you have committed to git or backed up.

Watch out

Starting the app as Administrator gives the agent Administrator rights too, because it inherits the app's permission level. Open it normally unless a task truly needs more.

Note

WSL1 is no longer supported. It worked up to Codex 0.114. From 0.115 you need WSL2.

The rest are smaller snags with known fixes, all taken from OpenAI's Windows and sandbox pages:

  • `npm.ps1 cannot be loaded because running scripts is disabled on this system`: PowerShell is blocking script launchers. OpenAI suggests Set-ExecutionPolicy -ExecutionPolicy RemoteSigned.
  • Git not detected for a project stored inside WSL: move the project to your Windows drive and reach it through /mnt/<drive>/....
  • The sandbox setup fails: one sandbox option needs a one-time admin approval. Clicking No on the Windows UAC popup (the "allow this app to make changes" box) is a common cause. Run the setup again and approve it.
  • Error 1385: Windows policy is blocking the sign-in type the sandbox user needs. On a work PC, ask your IT team.
  • A warning that some folders are writable by Everyone: the sandbox cannot fully protect those folders. Keep projects somewhere only your user can write.
  • A dev server stops on its own: with the newest sandbox type, called mxc, child programs end when the main command exits, so a detached development server may not keep running.
  • Cmder missing from the Open dialog: add Cmder to the Start menu, then restart Codex or the PC.

The mxc sandbox is the one OpenAI recommends, and it needs no admin setup, but only on Windows 11 24H2 (build 26100.9278) or 25H2 (build 26200.9278) with Microsoft's newer features rolled out. Older PCs fall back to the admin-approved sandbox. Managed work laptops sometimes block setup even on a supported version, and OpenAI also expects winget to be available.

Using Codex next to Claude Code on one Windows PC

You can keep both agents on one PC. Some people give Codex one kind of job and Claude Code another, or ask one to check the other's work. They install side by side without conflict. Here is where they differ day to day:

TaskCodexClaude Code
Install in PowerShellThe powershell -ExecutionPolicy ByPass command shown earlierirm https://claude.ai/install.ps1 | iex
Project notes fileAGENTS.mdCLAUDE.md
Create the notes file/init/init
Change what it may do alone/permissionsShift+Tab to cycle modes
Pick up an old chatcodex resumeclaude -r

Moving between them is easier than it used to be. Codex has an /import command that brings in your Claude Code settings and chats. Going the other way, Claude Code (version 2.1.277 or later) reads a project's AGENTS.md when the project has no CLAUDE.md, so one notes file can serve both agents. The Claude Code on Windows page covers that side of the install.

One rule matters more than any setting: never let two agents edit the same files at once. Give each its own folder, or a git worktree (a second copy of your project that git keeps linked to the first). Our worktrees guide shows how, and Codex vs Claude Code helps you decide which job suits which agent.

The Codex app is good at running Codex, but it does not show your Claude sessions. VibeCodingDeck is one Windows app around both: Codex in one pane and Claude Code in the next, up to 12 at once, a status light that turns to waiting when an agent needs you, a usage meter for each ChatGPT and Claude login, and a button to hand a stuck job to the other AI. It uses your own subscriptions and costs $29/month or $249/year as of November 2026 (see pricing).

Codex on Windows: what people ask

Does Codex work on Windows without WSL?

+

Yes. As of November 2026 both the Codex app and the Codex CLI run natively in PowerShell with a Windows sandbox. WSL2 is an option, not a requirement.

Where do I download the Codex desktop app for Windows?

+

Codex on Windows is part of the ChatGPT desktop app. Install it from the Microsoft Store or run winget install --id 9PLM9XGG6VKS -s msstore in PowerShell.

Is the Codex app free on Windows?

+

ChatGPT Free and Go plans include Codex in the desktop app for lighter tasks, subject to rollout. The CLI and heavier use start with ChatGPT Plus at $20/month, as of November 2026.

Can I use the Codex CLI and the Codex app at the same time?

+

Yes. They share your ChatGPT account. A CLI installed inside WSL keeps its own settings and history unless you point both at one folder with CODEX_HOME.

Sources

Run up to 12 AI coding agents in one window.

Claude Code, Codex, Gemini, Grok and more, side by side. Windows and Mac. From $29 a month.

Get started

Keep reading