app/windows.md Codex Docs, 2026-03-04 18:18 UTC → 2026-04-22 18:29 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![Codex app for Windows showing a project sidebar, active thread, and review pane](/images/codex/windows/codex-windows-light.webp)

10 12 

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

12 14 

13Download the Codex app from the15Download the Codex app from the

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

15 17 

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

17 19 

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

22distribution through enterprise management tools.24distribution through enterprise management tools.

23 25 

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

27the Microsoft Store UI, run:

28 

29```powershell

30winget install Codex -s msstore

31```

32 

33## Native sandbox

34 

35The 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.

36 

37Running Codex in full access mode means Codex is not limited to your project

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

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

40 targeted exceptions, or set your [approval policy to

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

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

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

44 

24## Customize for your dev setup45## Customize for your dev setup

25 46 

26### Preferred editor47### Preferred editor

52 73 

53By default, the Codex app uses the Windows-native agent. That means the agent74By 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 in75runs 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.76Windows Subsystem for Linux 2 (WSL2) by using the `wsl` CLI when needed.

56 77 

57If you want to add a project from the WSL filesystem, click **Add new project**78If 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 File79or press <kbd>Ctrl</kbd>+<kbd>O</kbd>, then type `\\wsl$\` into the File

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

65directly from the WSL filesystem.86directly from the WSL filesystem.

66 87 

67If you want the agent itself to run in WSL, open **[Settings](codex://settings)**,88If 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**. The89switch the agent from Windows native to WSL, and **restart the app**. The

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

70place after restart.91place after restart.

71 92 

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

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

95 

72![Codex app settings showing the agent selector with Windows native and WSL options](/images/codex/windows/wsl-select-light.webp)96![Codex app settings showing the agent selector with Windows native and WSL options](/images/codex/windows/wsl-select-light.webp)

73 97 

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

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

157and PowerShell otherwise.181and PowerShell otherwise.

158 182 

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

184 

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

186`%USERPROFILE%\.codex`.

187 

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

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

190auth, or session history with the Windows app.

191 

192To share them, use one of these approaches:

193 

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

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

196 

197```bash

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

199```

200 

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

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

203 

159### Git features are unavailable204### Git features are unavailable

160 205 

161If you don't have Git installed natively on Windows, the app can't use some206If 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`.207features. Install it with `winget install Git.Git` from PowerShell or `cmd.exe`.

208 

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

210 

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

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

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

214 

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

216 

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

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

219restart Codex or reboot.