app/windows.md Codex Docs, 2026-03-04 06:20 UTC → 2026-05-12 01:59 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.

5The Windows app supports core workflows such as worktrees, automations, Git

6functionality, the in-app browser, artifact previews, plugins, and skills.

7It runs natively on Windows using PowerShell and the

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

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

4 10 

5ChatGPT Plus, Pro, Business, Edu, and Enterprise plans include Codex. Learn more about [what’s included](https://developers.openai.com/codex/pricing).11<CodexScreenshot

12 alt="Codex app for Windows showing a project sidebar, active thread, and review pane"

13 lightSrc="/images/codex/windows/codex-windows-light.webp"

14 darkSrc="/images/codex/windows/codex-windows-dark.webp"

15 variant="no-wallpaper"

16 maxHeight="320px"

17/>

6 18 

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

8 20 

9## Getting started21Download the Codex app from the

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

10 23 

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

12 25 

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

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

14 28 

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

30distribution through enterprise management tools.

16 31 

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

33the Microsoft Store UI, run:

18 34 

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

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

37```

21 38 

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

23 40 

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.41The 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 42 

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

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

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

46 targeted exceptions, or set your [approval policy to

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

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

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

28 50 

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

30 52 

314. Send your first message53<section class="feature-grid">

32 54 

33 After choosing the project, make sure **Local** is selected to have Codex work on your machine and send your first message to Codex.55<div>

34 56 

35 You can ask Codex anything about the project or your computer in general. Here are some examples:57### Preferred editor

36 58 

37- Tell me about this project59Choose a default app for **Open**, such as Visual Studio, VS Code, or another

38- Build a classic Snake game in this repo.60editor. You can override that choice per project. If you already picked a

39- Find and fix bugs in my codebase with minimal, high-confidence changes.61different app from the **Open** menu for a project, that project-specific

62choice takes precedence.

40 63 

41 If you need more inspiration, check out the [explore section](https://developers.openai.com/codex/explore).64</div>

42 65 

66<CodexScreenshot

67 alt="Codex app settings showing the default Open In app on Windows"

68 lightSrc="/images/codex/windows/open-in-windows-light.webp"

69 darkSrc="/images/codex/windows/open-in-windows-dark.webp"

70 maxHeight={520}

71 maxWidth={784}

72/>

43 73 

44## Work with the Codex app74</section>

45 75 

46[### Multitask across projects76<section class="feature-grid inverse">

47 77 

48Run multiple tasks in parallel and switch quickly between them.](https://developers.openai.com/codex/app/features#multitask-across-projects)[### Built-in Git tools78<div>

49 79 

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 tasks80### Integrated terminal

51 81 

52Isolate changes of multiple Codex threads using built-in Git worktree support.](https://developers.openai.com/codex/app/worktrees)[### Skills support82You can also choose the default integrated terminal. Depending on what you have

83installed, options include:

53 84 

54Give your Codex agent additional capabilities and reuse skills across App, CLI, and IDE Extension.](https://developers.openai.com/codex/app/features#skills-support)[### Automations85- PowerShell

86- Command Prompt

87- Git Bash

88- WSL

55 89 

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 terminal90This change applies only to new terminal sessions. If you already have an

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

92expecting the new default terminal to appear.

57 93 

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 environments94</div>

59 95 

60Define worktree setup scripts and common project actions for easy access.](https://developers.openai.com/codex/app/local-environments)[### Sync with the IDE extension96<CodexScreenshot

97 alt="Codex app settings showing the integrated terminal selection on Windows"

98 lightSrc="/images/codex/windows/integrated-shell-light.webp"

99 darkSrc="/images/codex/windows/integrated-shell-dark.webp"

100 maxHeight={520}

101 maxWidth={788}

102/>

61 103 

62Share Auto Context and active threads across app and IDE sessions.](https://developers.openai.com/codex/app/features#sync-with-the-ide-extension)[### MCP support104</section>

63 105 

64Connect your Codex agent to additional services using MCP.](https://developers.openai.com/codex/app/features#mcp-support)106## Windows Subsystem for Linux (WSL)

65 107 

108By default, the Codex app uses the Windows-native agent. That means the agent

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

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

66 111 

67Need help? Visit the [troubleshooting guide](https://developers.openai.com/codex/app/troubleshooting).112If you want to add a project from the WSL filesystem, click **Add new project**

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

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

115want to open.

116 

117If you plan to keep using the Windows-native agent, prefer storing projects on

118your Windows filesystem and accessing them from WSL through

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

120directly from the WSL filesystem.

121 

122If you want the agent itself to run in WSL2, open **[Settings](codex://settings)**,

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

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

125place after restart.

126 

127WSL1 was supported through Codex `0.114`. Starting in Codex `0.115`, the Linux

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

129 

130<CodexScreenshot

131 alt="Codex app settings showing the agent selector with Windows native and WSL options"

132 lightSrc="/images/codex/windows/wsl-select-light.webp"

133 darkSrc="/images/codex/windows/wsl-select-dark.webp"

134 maxHeight={520}

135 maxWidth={786}

136 class="mb-8"

137/>

138 

139You configure the integrated terminal independently from the agent. See

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

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

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

143 

144## Useful developer tools

145 

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

147 

148- **Git**: Powers the review panel in the Codex app and lets you inspect or

149 revert changes.

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

151 efficiently.

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

153 efficiently.

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

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

156 

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

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

159asking Codex to install them:

160 

161```powershell

162winget install --id Git.Git

163winget install --id OpenJS.NodeJS.LTS

164winget install --id Python.Python.3.14

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

166winget install --id GitHub.cli

167```

168 

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

170the app.

171 

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

173version you want.

174 

175## Troubleshooting and FAQ

176 

177### Run commands with elevated permissions

178 

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

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

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

182permission level.

183 

184### PowerShell execution policy blocks commands

185 

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

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

188 

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

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

191them.

192 

193An error may look something like this:

194 

195```text

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

197```

198 

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

200 

201```powershell

202Set-ExecutionPolicy -ExecutionPolicy RemoteSigned

203```

204 

205For details and other options, check Microsoft's

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

207before changing the policy.

208 

209### Local environment scripts on Windows

210 

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

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

213set of actions for every platform.

214 

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

216Windows-specific actions.

217 

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

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

220 

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

222and PowerShell otherwise.

223 

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

225 

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

227`%USERPROFILE%\.codex`.

228 

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

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

231auth, or session history with the Windows app.

232 

233To share them, use one of these approaches:

234 

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

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

237 

238```bash

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

240```

241 

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

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

244 

245### Git features are unavailable

246 

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

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

249 

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

251 

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

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

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

255 

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

257 

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

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

260restart Codex or reboot.