app/windows.md Codex Docs, 2026-03-03 00:35 UTC → 2026-04-17 00:44 UTC

1# Codex app1# Windows

2 2 

3The Codex app is a focused desktop experience for working on Codex threads in parallel, with built-in worktree support, automations, and Git functionality.3The [Codex app for Windows](https://get.microsoft.com/installer/download/9PLM9XGG6VKS?cid=website_cta_psi) gives you one interface for

4working across projects, running parallel agent threads, and reviewing results.

5It runs natively on Windows using PowerShell and the

6[Windows sandbox](https://developers.openai.com/codex/windows#windows-sandbox), or you can configure it to

7run in [Windows Subsystem for Linux 2 (WSL2)](#windows-subsystem-for-linux-wsl).

4 8 

5ChatGPT Plus, Pro, Business, Edu, and Enterprise plans include Codex. Learn more about [what’s included](https://developers.openai.com/codex/pricing).9![Codex app for Windows showing a project sidebar, active thread, and review pane](/images/codex/windows/codex-windows-light.webp)

6 10 

7![Codex app window with a project sidebar, active thread, and review pane](/images/codex/app/app-screenshot-light.webp)11## Download and update the Codex app

8 12 

9## Getting started13Download the Codex app from the

14[Microsoft Store](https://get.microsoft.com/installer/download/9PLM9XGG6VKS?cid=website_cta_psi).

10 15 

11The Codex app is available on macOS (Apple Silicon).16Then follow the [quickstart](https://developers.openai.com/codex/quickstart?setup=app) to get started.

12 17 

131. Download and install the Codex app18To update the app, open the Microsoft Store, go to **Downloads**, and click

19**Check for updates**. The Store installs the latest version afterward.

14 20 

15 The Codex app is currently only available for macOS.21For enterprises, administrators can deploy the app with Microsoft Store app

22distribution through enterprise management tools.

16 23 

17 [Download for macOS](https://persistent.oaistatic.com/codex-app-prod/Codex.dmg)24If you prefer a command-line install path, or need an alternative to opening

25the Microsoft Store UI, run:

18 26 

19 [Get notified for Windows and Linux](https://openai.com/form/codex-app/)27```powershell

202. Open Codex and sign in28winget install Codex -s msstore

29```

21 30 

22 Once you downloaded and installed the Codex app, open it and sign in with your ChatGPT account or an OpenAI API key.31## Native sandbox

23 32 

24 If you sign in with an OpenAI API key, some functionality such as [cloud threads](https://developers.openai.com/codex/prompting#threads) might not be available.33The Codex app on Windows supports a native [Windows sandbox](https://developers.openai.com/codex/windows#windows-sandbox) when the agent runs in PowerShell, and uses Linux sandboxing when you run the agent in [Windows Subsystem for Linux 2 (WSL2)](#windows-subsystem-for-linux-wsl). To apply sandbox protections in either mode, set sandbox permissions to **Default permissions** in the Composer before sending messages to Codex.

253. Select a project

26 34 

27 Choose a project folder that you want Codex to work in.35Running Codex in full access mode means Codex is not limited to your project

36 directory and might perform unintentional destructive actions that can lead to

37 data loss. Keep sandbox boundaries in place and use [rules](https://developers.openai.com/codex/rules) for

38 targeted exceptions, or set your [approval policy to

39 never](https://developers.openai.com/codex/agent-approvals-security#run-without-approval-prompts) to have

40 Codex attempt to solve problems without asking for escalated permissions,

41 based on your [approval and security setup](https://developers.openai.com/codex/agent-approvals-security).

28 42 

29If you used the Codex app, CLI, or IDE Extension before you’ll see past projects that you worked on.43## Customize for your dev setup

30 44 

314. Send your first message45### Preferred editor

32 46 

33 After choosing the project, make sure **Local** is selected to have Codex work on your machine and send your first message to Codex.47Choose a default app for **Open**, such as Visual Studio, VS Code, or another

48editor. You can override that choice per project. If you already picked a

49different app from the **Open** menu for a project, that project-specific

50choice takes precedence.

34 51 

35 You can ask Codex anything about the project or your computer in general. Here are some examples:52![Codex app settings showing the default Open In app on Windows](/images/codex/windows/open-in-windows-light.webp)

36 53 

37- Tell me about this project54### Integrated terminal

38- Build a classic Snake game in this repo.

39- Find and fix bugs in my codebase with minimal, high-confidence changes.

40 55 

41 If you need more inspiration, check out the [explore section](https://developers.openai.com/codex/explore).56You can also choose the default integrated terminal. Depending on what you have

57installed, options include:

42 58 

59- PowerShell

60- Command Prompt

61- Git Bash

62- WSL

43 63 

44## Work with the Codex app64This change applies only to new terminal sessions. If you already have an

65integrated terminal open, restart the app or start a new thread before

66expecting the new default terminal to appear.

45 67 

46[### Multitask across projects68![Codex app settings showing the integrated terminal selection on Windows](/images/codex/windows/integrated-shell-light.webp)

47 69 

48Run multiple tasks in parallel and switch quickly between them.](https://developers.openai.com/codex/app/features#multitask-across-projects)[### Built-in Git tools70## Windows Subsystem for Linux (WSL)

49 71 

50Review diffs, comment inline, stage or revert chunks, and commit without leaving the app.](https://developers.openai.com/codex/app/features#built-in-git-tools)[### Worktrees for parallel tasks72By default, the Codex app uses the Windows-native agent. That means the agent

73runs commands in PowerShell. The app can still work with projects that live in

74Windows Subsystem for Linux 2 (WSL2) by using the `wsl` CLI when needed.

51 75 

52Isolate changes of multiple Codex threads using built-in Git worktree support.](https://developers.openai.com/codex/app/worktrees)[### Skills support76If you want to add a project from the WSL filesystem, click **Add new project**

77or press <kbd>Ctrl</kbd>+<kbd>O</kbd>, then type `\\wsl$\` into the File

78Explorer window. From there, choose your Linux distribution and the folder you

79want to open.

53 80 

54Give your Codex agent additional capabilities and reuse skills across App, CLI, and IDE Extension.](https://developers.openai.com/codex/app/features#skills-support)[### Automations81If you plan to keep using the Windows-native agent, prefer storing projects on

82your Windows filesystem and accessing them from WSL through

83`/mnt/<drive>/...`. This setup is more reliable than opening projects

84directly from the WSL filesystem.

55 85 

56Pair skills with automations to automate recurring tasks in the background. Codex adds findings to the inbox, or automatically archives runs if there’s nothing to report.](https://developers.openai.com/codex/app/automations)[### Built-in terminal86If you want the agent itself to run in WSL2, open **[Settings](codex://settings)**,

87switch the agent from Windows native to WSL, and **restart the app**. The

88change doesn't take effect until you restart. Your projects should remain in

89place after restart.

57 90 

58Open a terminal per thread to test your changes, run dev servers, scripts, and custom commands.](https://developers.openai.com/codex/app/features#integrated-terminal)[### Local environments91WSL1 was supported through Codex `0.114`. Starting in Codex `0.115`, the Linux

92sandbox moved to `bubblewrap`, so WSL1 is no longer supported.

59 93 

60Define worktree setup scripts and common project actions for easy access.](https://developers.openai.com/codex/app/local-environments)[### Sync with the IDE extension94![Codex app settings showing the agent selector with Windows native and WSL options](/images/codex/windows/wsl-select-light.webp)

61 95 

62Share Auto Context and active threads across app and IDE sessions.](https://developers.openai.com/codex/app/features#sync-with-the-ide-extension)[### MCP support96You configure the integrated terminal independently from the agent. See

97[Customize for your dev setup](#customize-for-your-dev-setup) for the

98terminal options. You can keep the agent in WSL and still use PowerShell in the

99terminal, or use WSL for both, depending on your workflow.

63 100 

64Connect your Codex agent to additional services using MCP.](https://developers.openai.com/codex/app/features#mcp-support)101## Useful developer tools

65 102 

103Codex works best when a few common developer tools are already installed:

66 104 

67Need help? Visit the [troubleshooting guide](https://developers.openai.com/codex/app/troubleshooting).105- **Git**: Powers the review panel in the Codex app and lets you inspect or

106 revert changes.

107- **Node.js**: A common tool that the agent uses to perform tasks more

108 efficiently.

109- **Python**: A common tool that the agent uses to perform tasks more

110 efficiently.

111- **.NET SDK**: Useful when you want to build native Windows apps.

112- **GitHub CLI**: Powers GitHub-specific functionality in the Codex app.

113 

114Install them with the default Windows package manager `winget` by pasting this

115into the [integrated terminal](https://developers.openai.com/codex/app/features#integrated-terminal) or

116asking Codex to install them:

117 

118```powershell

119winget install --id Git.Git

120winget install --id OpenJS.NodeJS.LTS

121winget install --id Python.Python.3.14

122winget install --id Microsoft.DotNet.SDK.10

123winget install --id GitHub.cli

124```

125 

126After installing GitHub CLI, run `gh auth login` to enable GitHub features in

127the app.

128 

129If you need a different Python or .NET version, change the package IDs to the

130version you want.

131 

132## Troubleshooting and FAQ

133 

134### Run commands with elevated permissions

135 

136If you need Codex to run commands with elevated permissions, start the Codex app

137itself as an administrator. After installation, open the Start menu, find

138Codex, and choose Run as administrator. The Codex agent inherits that

139permission level.

140 

141### PowerShell execution policy blocks commands

142 

143If you have never used tools such as Node.js or `npm` in PowerShell before, the

144Codex agent or integrated terminal may hit execution policy errors.

145 

146This can also happen if Codex creates PowerShell scripts for you. In that case,

147you may need a less restrictive execution policy before PowerShell will run

148them.

149 

150An error may look something like this:

151 

152```text

153npm.ps1 cannot be loaded because running scripts is disabled on this system.

154```

155 

156A common fix is to set the execution policy to `RemoteSigned`:

157 

158```powershell

159Set-ExecutionPolicy -ExecutionPolicy RemoteSigned

160```

161 

162For details and other options, check Microsoft's

163[execution policy guide](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_execution_policies)

164before changing the policy.

165 

166### Local environment scripts on Windows

167 

168If your [local environment](https://developers.openai.com/codex/app/local-environments) uses cross-platform

169commands such as `npm` scripts, you can keep one shared setup script or

170set of actions for every platform.

171 

172If you need Windows-specific behavior, create Windows-specific setup scripts or

173Windows-specific actions.

174 

175Actions run in the environment used by your integrated terminal. See

176[Customize for your dev setup](#customize-for-your-dev-setup).

177 

178Local setup scripts run in the agent environment: WSL if the agent uses WSL,

179and PowerShell otherwise.

180 

181### Share config, auth, and sessions with WSL

182 

183The Windows app uses the same Codex home directory as native Codex on Windows:

184`%USERPROFILE%\.codex`.

185 

186If you also run the Codex CLI inside WSL, the CLI uses the Linux home

187directory by default, so it doesn't automatically share configuration, cached

188auth, or session history with the Windows app.

189 

190To share them, use one of these approaches:

191 

192- Sync WSL `~/.codex` with `%USERPROFILE%\.codex` on your file system.

193- Point WSL at the Windows Codex home directory by setting `CODEX_HOME`:

194 

195```bash

196export CODEX_HOME=/mnt/c/Users/<windows-user>/.codex

197```

198 

199If you want that setting in every shell, add it to your WSL shell profile, such

200as `~/.bashrc` or `~/.zshrc`.

201 

202### Git features are unavailable

203 

204If you don't have Git installed natively on Windows, the app can't use some

205features. Install it with `winget install Git.Git` from PowerShell or `cmd.exe`.

206 

207### Git isn't detected for projects opened from `\\wsl$`

208 

209For now, if you want to use the Windows-native agent with a project also

210accessible from WSL, the most reliable workaround is to store the project

211on the native Windows drive and access it in WSL through `/mnt/<drive>/...`.

212 

213### `Cmder` isn't listed in the open dialog

214 

215If `Cmder` is installed but doesn't show in Codex's open dialog, add it to the

216Windows Start Menu: right-click `Cmder` and choose **Add to Start**, then

217restart Codex or reboot.