app/windows.md Codex Docs, 2026-03-05 00:34 UTC → 2026-04-13 00:44 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.

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

6[Windows sandbox](https://developers.openai.com/codex/windows#windows-sandbox), or you can configure it to6[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).7run in [Windows Subsystem for Linux 2 (WSL2)](#windows-subsystem-for-linux-wsl).

8 8 

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

10 10 

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

12 12 

13Download the Codex app from the13Download the Codex app from the

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

15 15 

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

17 17 

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

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

23 23 

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

25the Microsoft Store UI, run:

26 

27```powershell

28winget install Codex -s msstore

29```

30 

31## Native sandbox

32 

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.

34 

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

42 

24## Customize for your dev setup43## Customize for your dev setup

25 44 

26### Preferred editor45### Preferred editor

52 71 

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

56 75 

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

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

65directly from the WSL filesystem.84directly from the WSL filesystem.

66 85 

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

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

70place after restart.89place after restart.

71 90 

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

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

93 

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

73 95 

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

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

157and PowerShell otherwise.179and PowerShell otherwise.

158 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 does not 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 

159### Git features are unavailable202### Git features are unavailable

160 203 

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

163 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 that is

210also accessible 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 

164### Cmder is not listed in the open dialog213### Cmder is not listed in the open dialog

165 214 

166If Cmder is installed but doesn’t show in Codex’s open dialog, add it to the215If Cmder is installed but doesn’t show in Codex’s open dialog, add it to the