windows.md +207 −23
1# Windows1# Windows
2 2
33The easiest way to use Codex on Windows is to use the [Codex app](https://developers.openai.com/codex/app/windows). You can also [set up the IDE extension](https://developers.openai.com/codex/ide) or [install the CLI](https://developers.openai.com/codex/cli) and run it from PowerShell.Use Codex on Windows with the native [Codex app](https://developers.openai.com/codex/app/windows), the
4[CLI](https://developers.openai.com/codex/cli), or the [IDE extension](https://developers.openai.com/codex/ide).
4 5
56[The Codex app on Windows supports core workflows such as parallel agent threads,
7worktrees, automations, Git functionality, the in-app browser, artifact previews,
8plugins, and skills.
6 9
710Use the Codex app on Windows<div class="mb-8">
11 <CodexCallout
12 href="/codex/app/windows"
13 title="Use the Codex app on Windows"
14 description="Work across projects, run parallel agent threads, and review results in one place with the native Windows app."
15 iconSrc="/images/codex/codex-banner-icon.webp"
16 />
17</div>
8 18
919Work across projects, run parallel agent threads, and review results in one place with the native Windows app.](https://developers.openai.com/codex/app/windows)Depending on the surface and your setup, Codex can run on Windows in three
20practical ways:
10 21
1122When you run Codex natively on Windows, agent mode uses a [Windows sandbox](#windows-sandbox) to block filesystem writes outside the working folder and prevent network access without your explicit approval. [Learn more below](#windows-sandbox).- natively on Windows with the stronger `elevated` sandbox,
1223 - natively on Windows with the fallback `unelevated` sandbox,
1324If you prefer to have Codex use [Windows Subsystem for Linux](https://learn.microsoft.com/en-us/windows/wsl/install) (WSL2), [read the instructions](#windows-subsystem-for-linux) below.- or inside [Windows Subsystem for Linux 2](https://learn.microsoft.com/en-us/windows/wsl/install) (WSL2), which uses the Linux sandbox implementation.
14 25
15## Windows sandbox26## Windows sandbox
16 27
1728Native Windows sandbox support includes two modes that you can configure in `config.toml`:When you run Codex natively on Windows, agent mode uses a Windows sandbox to
29block filesystem writes outside the working folder and prevent network access
30without your explicit approval.
18 31
1932```Native Windows sandbox support includes two modes that you can configure in
33`config.toml`:
34
35```toml
20[windows]36[windows]
2137sandbox = "unelevated" # or "elevated"sandbox = "elevated" # or "unelevated"
22```38```
23 39
2440How `elevated` mode works:`elevated` is the preferred native Windows sandbox. It uses dedicated
41lower-privilege sandbox users, filesystem permission boundaries, firewall
42rules, and local policy changes needed for commands that run in the sandbox.
43
44`unelevated` is the fallback native Windows sandbox. It runs commands with a
45restricted Windows token derived from your current user, applies ACL-based
46filesystem boundaries, and uses environment-level offline controls instead of
47the dedicated offline-user firewall rule. It's weaker than `elevated`, but it
48is still useful when administrator-approved setup is blocked by local or
49enterprise policy.
25 50
2651- Uses a Restricted Token approach with filesystem ACLs to limit which files the sandbox can write to.If both modes are available, use `elevated`. If the default native sandbox
2752- Runs commands as a dedicated Windows Sandbox User.doesn't work in your environment, use `unelevated` as a fallback while you
2853- Limits network access by installing Windows Firewall rules.troubleshoot the setup.
54
55By default, both sandbox modes also use a private desktop for stronger UI
56isolation. Set `windows.sandbox_private_desktop = false` only if you need the
57older `Winsta0\\Default` behavior for compatibility.
29 58
30### Sandbox permissions59### Sandbox permissions
31 60
37 Codex attempt to solve problems without asking for escalated permissions,66 Codex attempt to solve problems without asking for escalated permissions,
38 based on your [approval and security setup](https://developers.openai.com/codex/agent-approvals-security).67 based on your [approval and security setup](https://developers.openai.com/codex/agent-approvals-security).
39 68
69### Windows version matrix
70
71| Windows version | Support level | Notes |
72| -------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
73| Windows 11 | Recommended | Best baseline for Codex on Windows. Use this if you are standardizing an enterprise deployment. |
74| Recent, fully updated Windows 10 | Best effort | Can work, but is less reliable than Windows 11. For Windows 10, Codex depends on modern console support, including ConPTY. In practice, Windows 10 version 1809 or newer is required. |
75| Older Windows 10 builds | Not recommended | More likely to miss required console components such as ConPTY and more likely to fail in enterprise setups. |
76
77Additional environment assumptions:
78
79- `winget` should be available. If it's missing, update Windows or install
80 the Windows Package Manager before setting up Codex.
81- The recommended native sandbox depends on administrator-approved setup.
82- Some enterprise-managed devices block the required setup steps even when the
83 OS version itself is acceptable.
84
40### Grant sandbox read access85### Grant sandbox read access
41 86
42When a command fails because the Windows sandbox can't read a directory, use:87When a command fails because the Windows sandbox can't read a directory, use:
47 92
48The path must be an existing absolute directory. After the command succeeds, later commands that run in the sandbox can read that directory during the current session.93The path must be an existing absolute directory. After the command succeeds, later commands that run in the sandbox can read that directory during the current session.
49 94
95Use the native Windows sandbox by default. The native Windows sandbox offers the best performance and highest speeds while keeping the same security. Choose WSL2 when you
96need a Linux-native environment on Windows, when your workflow already lives in
97WSL2, or when neither native Windows sandbox mode meets your needs.
98
50## Windows Subsystem for Linux99## Windows Subsystem for Linux
51 100
101If you choose WSL2, Codex runs inside the Linux environment instead of using the
102native Windows sandbox. This is useful if you need Linux-native tooling on
103Windows, if your repositories and developer workflow already live in WSL2, or
104if neither native Windows sandbox mode works for your environment.
105
106WSL1 was supported through Codex `0.114`. Starting in Codex `0.115`, the Linux
107sandbox moved to `bubblewrap`, so WSL1 is no longer supported.
108
52### Launch VS Code from inside WSL109### Launch VS Code from inside WSL
53 110
54For step-by-step instructions, see the [official VS Code WSL tutorial](https://code.visualstudio.com/docs/remote/wsl-tutorial).111For step-by-step instructions, see the [official VS Code WSL tutorial](https://code.visualstudio.com/docs/remote/wsl-tutorial).
80 137
81 This prints your distribution name.138 This prints your distribution name.
82 139
83140If you don’t see “WSL: …” in the status bar, press `Ctrl+Shift+P`, pickIf you don't see "WSL: ..." in the status bar, press `Ctrl+Shift+P`, pick
84 `WSL: Reopen Folder in WSL`, and keep your repository under `/home/...` (not141 `WSL: Reopen Folder in WSL`, and keep your repository under `/home/...` (not
85 `C:\`) for best performance.142 `C:\`) for best performance.
86 143
144If the Windows app or project picker does not show your WSL repository, type
145 <code>\\wsl$</code> into the file picker or Explorer, then navigate to your
146 distro's home directory.
147
87### Use Codex CLI with WSL148### Use Codex CLI with WSL
88 149
89Run these commands from an elevated PowerShell or Windows Terminal:150Run these commands from an elevated PowerShell or Windows Terminal:
113 174
114### Working on code inside WSL175### Working on code inside WSL
115 176
116177- Working in Windows-mounted paths like `/mnt/c/…` can be slower than working in Windows-native paths. Keep your repositories under your Linux home directory (like `~/code/my-app`) for faster I/O and fewer symlink and permission issues:- Working in Windows-mounted paths like <code>/mnt/c/...</code> can be slower than working in Windows-native paths. Keep your repositories under your Linux home directory (like <code>~/code/my-app</code>) for faster I/O and fewer symlink and permission issues:
117
118 ```bash178 ```bash
119 mkdir -p ~/code && cd ~/code179 mkdir -p ~/code && cd ~/code
120 git clone https://github.com/your/repo.git180 git clone https://github.com/your/repo.git
121 cd repo181 cd repo
122 ```182 ```
123183- If you need Windows access to files, they’re under `\wsl$\Ubuntu\home<user>` in Explorer.- If you need Windows access to files, they're under <code>\\wsl$\Ubuntu\home\<user></code> in Explorer.
124 184
125## Troubleshooting and FAQ185## Troubleshooting and FAQ
126 186
127187#### Installed extension, but it’s unresponsiveIf you are troubleshooting a managed Windows machine, start with the native
188sandbox mode, Windows version, and any policy error shown by Codex. Most native
189Windows support issues come from sandbox setup, logon rights, or filesystem
190permissions rather than from the editor itself.
191
192My native sandbox setup failed
193
194If Codex cannot complete the `elevated` sandbox setup, the most common causes
195are:
196
197- the Windows UAC or administrator prompt was declined,
198- the machine does not allow local user or group creation,
199- the machine does not allow firewall rule changes,
200- the machine blocks the logon rights needed by the sandbox users,
201- or another enterprise policy blocks part of the setup flow.
202
203What to try:
204
2051. Try the `elevated` sandbox setup again and approve the administrator prompt
206 if your environment allows it.
2072. If your company laptop blocks this, ask your IT team whether the machine
208 allows administrator-approved setup for local user/group creation, firewall
209 configuration, and the required sandbox-user logon rights.
2103. If the default setup still fails, use the `unelevated` sandbox so you can
211 continue working while the issue is investigated.
212
213Codex switched me to the unelevated sandbox
214
215This means Codex could not finish the stronger `elevated` sandbox setup on your
216machine.
217
218- Codex can still run in a sandboxed mode.
219- It still applies ACL-based filesystem boundaries, but it does not use the
220 separate sandbox-user boundary from `elevated` and has weaker network
221 isolation.
222- This is a useful fallback, but not the preferred long-term enterprise
223 configuration.
224
225If you are on a managed enterprise laptop, the best long-term fix is usually to
226get the `elevated` sandbox working with help from your IT team.
227
228I see Windows error 1385
229
230If sandboxed commands fail with error `1385`, Windows is denying the logon type
231the sandbox user needs in order to start the command.
232
233In practice, this usually means Codex created the sandbox users successfully,
234but Windows policy is still preventing those users from launching sandboxed
235commands.
236
237What to do:
238
2391. Ask your IT team whether the device policy grants the required logon rights
240 to the Codex-created sandbox users.
2412. Compare group policy or OU differences if the issue affects only some
242 machines or teams.
2433. If you need to keep working immediately, use the `unelevated` sandbox while
244 the policy issue is investigated.
2454. Send `CODEX_HOME/.sandbox/sandbox.log` along with your Windows version and a
246 short description of the failure.
247
248Codex warns that some folders are writable by Everyone
249
250Codex may warn that some folders are writable by `Everyone`.
251
252If you see this warning, Windows permissions on those folders are too broad for
253the sandbox to fully protect them.
254
255What to do:
256
2571. Review the folders Codex lists in the warning.
2582. Remove `Everyone` write access from those folders if that is appropriate in
259 your environment.
2603. Restart Codex or re-run the sandbox setup after those permissions are
261 corrected.
262
263If you are not sure how to change those permissions, ask your IT team for help.
264
265Sandboxed commands cannot reach the network
266
267Some Codex tasks are intentionally run without outbound network access,
268depending on the permissions mode in use.
269
270If a task fails because it cannot reach the network:
271
2721. Check whether the task was supposed to run with network disabled.
2732. If you expected network access, restart Codex and try again.
2743. If the issue keeps happening, collect the sandbox log so the team can check
275 whether the machine is in a partial or broken sandbox state.
276
277Sandboxing worked before and then stopped
278
279This can happen after:
280
281- moving a repo or workspace,
282- changing machine permissions,
283- changing Windows policies,
284- or other system configuration changes.
285
286What to try:
287
2881. Restart Codex.
2892. Try the `elevated` sandbox setup again.
2903. If that does not fix it, use the `unelevated` sandbox as a temporary
291 fallback.
2924. Collect the sandbox log for review.
293
294I need to send diagnostics to OpenAI
295
296If you still have problems, send:
297
298- `CODEX_HOME/.sandbox/sandbox.log`
299
300It is also helpful to include:
301
302- a short description of what you were trying to do,
303- whether the `elevated` sandbox failed or the `unelevated` sandbox was used,
304- any error message shown in the app,
305- whether you saw `1385` or another Windows or PowerShell error,
306- and whether you are on Windows 11 or Windows 10.
307
308Do not send:
309
310- the contents of `CODEX_HOME/.sandbox-secrets/`
311
312The IDE extension is installed but unresponsive
128 313
129Your system may be missing C++ development tools, which some native dependencies require:314Your system may be missing C++ development tools, which some native dependencies require:
130 315
134 319
135Then fully restart VS Code after installation.320Then fully restart VS Code after installation.
136 321
137322#### If it feels slow on large repositoriesLarge repositories feel slow in WSL
138 323
139324- Make sure you’re not working under `/mnt/c`. Move the repository to WSL (for example, `~/code/…`).- Make sure you're not working under <code>/mnt/c</code>. Move the repository to WSL (for example, <code>~/code/...</code>).
140- Increase memory and CPU for WSL if needed; update WSL to the latest version:325- Increase memory and CPU for WSL if needed; update WSL to the latest version:
141
142 ```powershell326 ```powershell
143 wsl --update327 wsl --update
144 wsl --shutdown328 wsl --shutdown
145 ```329 ```
146 330
147331#### VS Code in WSL can’t find `codex`VS Code in WSL cannot find codex
148 332
149Verify the binary exists and is on PATH inside WSL:333Verify the binary exists and is on PATH inside WSL:
150 334