app/windows.md Codex Docs, 2026-02-21 00:33 UTC → 2026-03-31 00:39 UTC

1# Windows

2 

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

4working across projects, running parallel agent threads, and reviewing results.

5It runs natively on Windows using PowerShell and the

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

8 

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

10 

11## Download and update the Codex app

12 

13Download the Codex app from the

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

15 

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

17 

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

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

20 

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

22distribution through enterprise management tools.

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 (WSL)](#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 

43## Customize for your dev setup

44 

45### Preferred editor

46 

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

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

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

50choice takes precedence.

51 

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

53 

54### Integrated terminal

55 

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

57installed, options include:

58 

59- PowerShell

60- Command Prompt

61- Git Bash

62- WSL

63 

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

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

66expecting the new default terminal to appear.

67 

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

69 

70## Windows Subsystem for Linux (WSL)

71 

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

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

74Windows Subsystem for Linux (WSL) by using the `wsl` CLI when needed.

75 

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

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

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

79want to open.

80 

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

82your Windows filesystem and accessing them from WSL through

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

84directly from the WSL filesystem.

85 

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

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

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

89place after restart.

90 

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

92 

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

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

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

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

97 

98## Useful developer tools

99 

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

101 

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

103 revert changes.

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

105 efficiently.

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

107 efficiently.

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

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

110 

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

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

113asking Codex to install them:

114 

115```powershell

116winget install --id Git.Git

117winget install --id OpenJS.NodeJS.LTS

118winget install --id Python.Python.3.14

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

120winget install --id GitHub.cli

121```

122 

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

124the app.

125 

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

127version you want.

128 

129## Troubleshooting and FAQ

130 

131### Run commands with elevated permissions

132 

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

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

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

136permission level.

137 

138### PowerShell execution policy blocks commands

139 

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

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

142 

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

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

145them.

146 

147An error may look something like this:

148 

149```text

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

151```

152 

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

154 

155```powershell

156Set-ExecutionPolicy -ExecutionPolicy RemoteSigned

157```

158 

159For details and other options, check Microsoft's

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

161before changing the policy.

162 

163### Local environment scripts on Windows

164 

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

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

167set of actions for every platform.

168 

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

170Windows-specific actions.

171 

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

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

174 

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

176and PowerShell otherwise.

177 

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

179 

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

181`%USERPROFILE%\.codex`.

182 

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

184directory by default, so it does not automatically share configuration, cached

185auth, or session history with the Windows app.

186 

187To share them, use one of these approaches:

188 

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

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

191 

192```bash

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

194```

195 

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

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

198 

199### Git features are unavailable

200 

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

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

203 

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

205 

206For now, if you want to use the Windows-native agent with a project that is

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

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

209 

210### Cmder is not listed in the open dialog

211 

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

213Windows Start Menu: right-click Cmder and choose **Add to Start**, then restart

214Codex or reboot.