app/windows.md +260 −0 added
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<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/>
18
19## Download and update the Codex app
20
21Download the Codex app from the
22[Microsoft Store](https://get.microsoft.com/installer/download/9PLM9XGG6VKS?cid=website_cta_psi).
23
24Then follow the [quickstart](https://developers.openai.com/codex/quickstart?setup=app) to get started.
25
26To update the app, open the Microsoft Store, go to **Downloads**, and click
27**Check for updates**. The Store installs the latest version afterward.
28
29For enterprises, administrators can deploy the app with Microsoft Store app
30distribution through enterprise management tools.
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
51## Customize for your dev setup
52
53<section class="feature-grid">
54
55<div>
56
57### Preferred editor
58
59Choose a default app for **Open**, such as Visual Studio, VS Code, or another
60editor. You can override that choice per project. If you already picked a
61different app from the **Open** menu for a project, that project-specific
62choice takes precedence.
63
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>
79
80### Integrated terminal
81
82You can also choose the default integrated terminal. Depending on what you have
83installed, options include:
84
85- PowerShell
86- Command Prompt
87- Git Bash
88- WSL
89
90This change applies only to new terminal sessions. If you already have an
91integrated terminal open, restart the app or start a new thread before
92expecting the new default terminal to appear.
93
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>
105
106## Windows Subsystem for Linux (WSL)
107
108By default, the Codex app uses the Windows-native agent. That means the agent
109runs commands in PowerShell. The app can still work with projects that live in
110Windows Subsystem for Linux 2 (WSL2) by using the `wsl` CLI when needed.
111
112If you want to add a project from the WSL filesystem, click **Add new project**
113or press <kbd>Ctrl</kbd>+<kbd>O</kbd>, then type `\\wsl$\` into the File
114Explorer window. From there, choose your Linux distribution and the folder you
115want to open.
116
117If you plan to keep using the Windows-native agent, prefer storing projects on
118your Windows filesystem and accessing them from WSL through
119`/mnt/<drive>/...`. This setup is more reliable than opening projects
120directly from the WSL filesystem.
121
122If you want the agent itself to run in WSL2, open **[Settings](codex://settings)**,
123switch the agent from Windows native to WSL, and **restart the app**. The
124change doesn't take effect until you restart. Your projects should remain in
125place after restart.
126
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/>
138
139You configure the integrated terminal independently from the agent. See
140[Customize for your dev setup](#customize-for-your-dev-setup) for the
141terminal options. You can keep the agent in WSL and still use PowerShell in the
142terminal, or use WSL for both, depending on your workflow.
143
144## Useful developer tools
145
146Codex works best when a few common developer tools are already installed:
147
148- **Git**: Powers the review panel in the Codex app and lets you inspect or
149 revert changes.
150- **Node.js**: A common tool that the agent uses to perform tasks more
151 efficiently.
152- **Python**: A common tool that the agent uses to perform tasks more
153 efficiently.
154- **.NET SDK**: Useful when you want to build native Windows apps.
155- **GitHub CLI**: Powers GitHub-specific functionality in the Codex app.
156
157Install them with the default Windows package manager `winget` by pasting this
158into the [integrated terminal](https://developers.openai.com/codex/app/features#integrated-terminal) or
159asking Codex to install them:
160
161```powershell
162winget install --id Git.Git
163winget install --id OpenJS.NodeJS.LTS
164winget install --id Python.Python.3.14
165winget install --id Microsoft.DotNet.SDK.10
166winget install --id GitHub.cli
167```
168
169After installing GitHub CLI, run `gh auth login` to enable GitHub features in
170the app.
171
172If you need a different Python or .NET version, change the package IDs to the
173version you want.
174
175## Troubleshooting and FAQ
176
177### Run commands with elevated permissions
178
179If you need Codex to run commands with elevated permissions, start the Codex app
180itself as an administrator. After installation, open the Start menu, find
181Codex, and choose Run as administrator. The Codex agent inherits that
182permission level.
183
184### PowerShell execution policy blocks commands
185
186If you have never used tools such as Node.js or `npm` in PowerShell before, the
187Codex agent or integrated terminal may hit execution policy errors.
188
189This can also happen if Codex creates PowerShell scripts for you. In that case,
190you may need a less restrictive execution policy before PowerShell will run
191them.
192
193An error may look something like this:
194
195```text
196npm.ps1 cannot be loaded because running scripts is disabled on this system.
197```
198
199A common fix is to set the execution policy to `RemoteSigned`:
200
201```powershell
202Set-ExecutionPolicy -ExecutionPolicy RemoteSigned
203```
204
205For details and other options, check Microsoft's
206[execution policy guide](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_execution_policies)
207before changing the policy.
208
209### Local environment scripts on Windows
210
211If your [local environment](https://developers.openai.com/codex/app/local-environments) uses cross-platform
212commands such as `npm` scripts, you can keep one shared setup script or
213set of actions for every platform.
214
215If you need Windows-specific behavior, create Windows-specific setup scripts or
216Windows-specific actions.
217
218Actions run in the environment used by your integrated terminal. See
219[Customize for your dev setup](#customize-for-your-dev-setup).
220
221Local setup scripts run in the agent environment: WSL if the agent uses WSL,
222and PowerShell otherwise.
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
245### Git features are unavailable
246
247If you don't have Git installed natively on Windows, the app can't use some
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.