app/windows.md Codex Docs, 2026-03-04 18:18 UTC → 2026-05-07 17:08 UTC

1# Windows1# Windows

2 2 

3The [Codex app for Windows](https://apps.microsoft.com/detail/9plm9xgg6vks?hl=en-US&gl=US) gives you one interface for3The [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.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.

5It runs natively on Windows using PowerShell and the7It runs natively on Windows using PowerShell and the

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

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

8 10 

9![Codex app for Windows showing a project sidebar, active thread, and review pane](/images/codex/windows/codex-windows-light.webp)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/>

10 18 

11## Download and update the Codex app19## Download and update the Codex app

12 20 

13Download the Codex app from the21Download the Codex app from the

14[Microsoft Store](https://apps.microsoft.com/detail/9plm9xgg6vks?hl=en-US&gl=US).22[Microsoft Store](https://get.microsoft.com/installer/download/9PLM9XGG6VKS?cid=website_cta_psi).

15 23 

16Then follow the [quickstart](https://developers.openai.com/codex/quickstart?setup=app) to get started.24Then follow the [quickstart](https://developers.openai.com/codex/quickstart?setup=app) to get started.

17 25 

21For enterprises, administrators can deploy the app with Microsoft Store app29For enterprises, administrators can deploy the app with Microsoft Store app

22distribution through enterprise management tools.30distribution through enterprise management tools.

23 31 

32If you prefer a command-line install path, or need an alternative to opening

33the Microsoft Store UI, run:

34 

35```powershell

36winget install Codex -s msstore

37```

38 

39## Native sandbox

40 

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.

42 

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).

50 

24## Customize for your dev setup51## Customize for your dev setup

25 52 

53<section class="feature-grid">

54 

55<div>

56 

26### Preferred editor57### Preferred editor

27 58 

28Choose a default app for **Open**, such as Visual Studio, VS Code, or another59Choose a default app for **Open**, such as Visual Studio, VS Code, or another

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

31choice takes precedence.62choice takes precedence.

32 63 

33![Codex app settings showing the default Open In app on Windows](/images/codex/windows/open-in-windows-light.webp)64</div>

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

73 

74</section>

75 

76<section class="feature-grid inverse">

77 

78<div>

34 79 

35### Integrated terminal80### Integrated terminal

36 81 

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

47expecting the new default terminal to appear.92expecting the new default terminal to appear.

48 93 

49![Codex app settings showing the integrated terminal selection on Windows](/images/codex/windows/integrated-shell-light.webp)94</div>

95 

96<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/>

103 

104</section>

50 105 

51## Windows Subsystem for Linux (WSL)106## Windows Subsystem for Linux (WSL)

52 107 

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

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

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

56 111 

57If you want to add a project from the WSL filesystem, click **Add new project**112If you want to add a project from the WSL filesystem, click **Add new project**

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

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

65directly from the WSL filesystem.120directly from the WSL filesystem.

66 121 

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

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

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

70place after restart.125place after restart.

71 126 

72![Codex app settings showing the agent selector with Windows native and WSL options](/images/codex/windows/wsl-select-light.webp)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/>

73 138 

74You configure the integrated terminal independently from the agent. See139You configure the integrated terminal independently from the agent. See

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

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

157and PowerShell otherwise.222and PowerShell otherwise.

158 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 

159### Git features are unavailable245### Git features are unavailable

160 246 

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

162features. Install it with `winget install Git.Git` from PowerShell or `cmd.exe`.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.