app/windows.md Codex Docs, 2026-02-20 12:16 UTC → 2026-05-01 18:29 UTC

1# Windows

2 

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

10 

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

12 

13## Download and update the Codex app

14 

15Download the Codex app from the

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

17 

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

19 

20To update the app, open the Microsoft Store, go to **Downloads**, and click

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

22 

23For enterprises, administrators can deploy the app with Microsoft Store app

24distribution through enterprise management tools.

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 

45## Customize for your dev setup

46 

47### Preferred editor

48 

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

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

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

52choice takes precedence.

53 

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

55 

56### Integrated terminal

57 

58You can also choose the default integrated terminal. Depending on what you have

59installed, options include:

60 

61- PowerShell

62- Command Prompt

63- Git Bash

64- WSL

65 

66This change applies only to new terminal sessions. If you already have an

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

68expecting the new default terminal to appear.

69 

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

71 

72## Windows Subsystem for Linux (WSL)

73 

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

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

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

77 

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

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

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

81want to open.

82 

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

84your Windows filesystem and accessing them from WSL through

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

86directly from the WSL filesystem.

87 

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

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

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

91place after restart.

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 

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

97 

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

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

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

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

102 

103## Useful developer tools

104 

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

106 

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

108 revert changes.

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

110 efficiently.

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

112 efficiently.

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

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

115 

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

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

118asking Codex to install them:

119 

120```powershell

121winget install --id Git.Git

122winget install --id OpenJS.NodeJS.LTS

123winget install --id Python.Python.3.14

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

125winget install --id GitHub.cli

126```

127 

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

129the app.

130 

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

132version you want.

133 

134## Troubleshooting and FAQ

135 

136### Run commands with elevated permissions

137 

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

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

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

141permission level.

142 

143### PowerShell execution policy blocks commands

144 

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

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

147 

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

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

150them.

151 

152An error may look something like this:

153 

154```text

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

156```

157 

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

159 

160```powershell

161Set-ExecutionPolicy -ExecutionPolicy RemoteSigned

162```

163 

164For details and other options, check Microsoft's

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

166before changing the policy.

167 

168### Local environment scripts on Windows

169 

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

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

172set of actions for every platform.

173 

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

175Windows-specific actions.

176 

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

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

179 

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

181and PowerShell otherwise.

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 

204### Git features are unavailable

205 

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

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.