windows.md +222 −20
1# Windows1# Windows
2 2
33Tips for running Codex on WindowsUse 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
56The easiest way to use Codex on Windows is to [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.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
710When you run Codex natively on Windows, the agent mode uses an experimental Windows sandbox to block filesystem writes outside the working folder and prevent network access without your explicit approval. [Learn more below](#windows-experimental-sandbox).[
8 11
912Instead, you can use [Windows Subsystem for Linux](https://learn.microsoft.com/en-us/windows/wsl/install) (WSL2). WSL2 gives you a Linux shell, Unix-style semantics, and tooling that match many tasks that models see in training.Use the Codex app on Windows
13
14Work across projects, run parallel agent threads, and review results in one place with the native Windows app.](https://developers.openai.com/codex/app/windows)
15
16Depending on the surface and your setup, Codex can run on Windows in three
17practical ways:
18
19- natively on Windows with the stronger `elevated` sandbox,
20- natively on Windows with the fallback `unelevated` sandbox,
21- or inside [Windows Subsystem for Linux 2](https://learn.microsoft.com/en-us/windows/wsl/install) (WSL2), which uses the Linux sandbox implementation.
22
23## Windows sandbox
24
25When you run Codex natively on Windows, agent mode uses a Windows sandbox to
26block filesystem writes outside the working folder and prevent network access
27without your explicit approval.
28
29Native Windows sandbox support includes two modes that you can configure in
30`config.toml`:
31
32```toml
33[windows]
34sandbox = "elevated" # or "unelevated"
35```
36
37`elevated` is the preferred native Windows sandbox. It uses dedicated
38lower-privilege sandbox users, filesystem permission boundaries, firewall
39rules, and local policy changes needed for commands that run in the sandbox.
40
41`unelevated` is the fallback native Windows sandbox. It runs commands with a
42restricted Windows token derived from your current user, applies ACL-based
43filesystem boundaries, and uses environment-level offline controls instead of
44the dedicated offline-user firewall rule. It's weaker than `elevated`, but it
45is still useful when administrator-approved setup is blocked by local or
46enterprise policy.
47
48If both modes are available, use `elevated`. If the default native sandbox
49doesn't work in your environment, use `unelevated` as a fallback while you
50troubleshoot the setup.
51
52By default, both sandbox modes also use a private desktop for stronger UI
53isolation. Set `windows.sandbox_private_desktop = false` only if you need the
54older `Winsta0\\Default` behavior for compatibility.
55
56### Sandbox permissions
57
58Running Codex in full access mode means Codex is not limited to your project
59 directory and might perform unintentional destructive actions that can lead to
60 data loss. For safer automation, keep sandbox boundaries in place and use
61 [rules](https://developers.openai.com/codex/rules) for specific exceptions, or set your [approval policy to
62 never](https://developers.openai.com/codex/agent-approvals-security#run-without-approval-prompts) to have
63 Codex attempt to solve problems without asking for escalated permissions,
64 based on your [approval and security setup](https://developers.openai.com/codex/agent-approvals-security).
65
66### Windows version matrix
67
68| Windows version | Support level | Notes |
69| -------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
70| Windows 11 | Recommended | Best baseline for Codex on Windows. Use this if you are standardizing an enterprise deployment. |
71| 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. |
72| Older Windows 10 builds | Not recommended | More likely to miss required console components such as ConPTY and more likely to fail in enterprise setups. |
73
74Additional environment assumptions:
75
76- `winget` should be available. If it's missing, update Windows or install
77 the Windows Package Manager before setting up Codex.
78- The recommended native sandbox depends on administrator-approved setup.
79- Some enterprise-managed devices block the required setup steps even when the
80 OS version itself is acceptable.
81
82### Grant sandbox read access
83
84When a command fails because the Windows sandbox can't read a directory, use:
85
86```text
87/sandbox-add-read-dir C:\absolute\directory\path
88```
89
90The 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.
91
92Use 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
93need a Linux-native environment on Windows, when your workflow already lives in
94WSL2, or when neither native Windows sandbox mode meets your needs.
10 95
11## Windows Subsystem for Linux96## Windows Subsystem for Linux
12 97
98If you choose WSL2, Codex runs inside the Linux environment instead of using the
99native Windows sandbox. This is useful if you need Linux-native tooling on
100Windows, if your repositories and developer workflow already live in WSL2, or
101if neither native Windows sandbox mode works for your environment.
102
103WSL1 was supported through Codex `0.114`. Starting in Codex `0.115`, the Linux
104sandbox moved to `bubblewrap`, so WSL1 is no longer supported.
105
13### Launch VS Code from inside WSL106### Launch VS Code from inside WSL
14 107
15For step-by-step instructions, see the [official VS Code WSL tutorial](https://code.visualstudio.com/docs/remote/wsl-tutorial).108For step-by-step instructions, see the [official VS Code WSL tutorial](https://code.visualstudio.com/docs/remote/wsl-tutorial).
45 `WSL: Reopen Folder in WSL`, and keep your repository under `/home/...` (not138 `WSL: Reopen Folder in WSL`, and keep your repository under `/home/...` (not
46 `C:\`) for best performance.139 `C:\`) for best performance.
47 140
141If the Windows app or project picker does not show your WSL repository, type
142`\wsl$` into the file picker or Explorer, then navigate to your
143 distro's home directory.
144
48### Use Codex CLI with WSL145### Use Codex CLI with WSL
49 146
50Run these commands from an elevated PowerShell or Windows Terminal:147Run these commands from an elevated PowerShell or Windows Terminal:
83 ```180 ```
84- If you need Windows access to files, they’re under `\wsl$\Ubuntu\home<user>` in Explorer.181- If you need Windows access to files, they’re under `\wsl$\Ubuntu\home<user>` in Explorer.
85 182
86183## Windows experimental sandbox## Troubleshooting and FAQ
87 184
88185The Windows sandbox support is experimental. How it works:If you are troubleshooting a managed Windows machine, start with the native
186sandbox mode, Windows version, and any policy error shown by Codex. Most native
187Windows support issues come from sandbox setup, logon rights, or filesystem
188permissions rather than from the editor itself.
89 189
90190- Launches commands inside a restricted token derived from an AppContainer profile.My native sandbox setup failed
91- Grants only specifically requested filesystem capabilities by attaching capability security identifiers to that profile.
92- Disables outbound network access by overriding proxy-related environment variables and inserting stub executables for common network tools.
93 191
94192Its primary limitation is that it can’t prevent file writes, deletions, or creations in any directory where the Everyone SID already has write permissions (for example, world-writable folders). When using the Windows sandbox, Codex scans for folders where Everyone has write access and recommends that you remove that access.If Codex cannot complete the `elevated` sandbox setup, the most common causes
193are:
95 194
96195### Grant sandbox read access- the Windows UAC or administrator prompt was declined,
196- the machine does not allow local user or group creation,
197- the machine does not allow firewall rule changes,
198- the machine blocks the logon rights needed by the sandbox users,
199- or another enterprise policy blocks part of the setup flow.
97 200
98201When a command fails because the Windows sandbox can't read a directory, use:What to try:
99 202
100203```text1. Try the `elevated` sandbox setup again and approve the administrator prompt
101204/sandbox-add-read-dir C:\absolute\directory\path if your environment allows it.
102205```2. If your company laptop blocks this, ask your IT team whether the machine
206 allows administrator-approved setup for local user/group creation, firewall
207 configuration, and the required sandbox-user logon rights.
2083. If the default setup still fails, use the `unelevated` sandbox so you can
209 continue working while the issue is investigated.
103 210
104211The 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.Codex switched me to the unelevated sandbox
212
213This means Codex could not finish the stronger `elevated` sandbox setup on your
214machine.
215
216- Codex can still run in a sandboxed mode.
217- It still applies ACL-based filesystem boundaries, but it does not use the
218 separate sandbox-user boundary from `elevated` and has weaker network
219 isolation.
220- This is a useful fallback, but not the preferred long-term enterprise
221 configuration.
222
223If you are on a managed enterprise laptop, the best long-term fix is usually to
224get the `elevated` sandbox working with help from your IT team.
225
226I see Windows error 1385
227
228If sandboxed commands fail with error `1385`, Windows is denying the logon type
229the sandbox user needs in order to start the command.
230
231In practice, this usually means Codex created the sandbox users successfully,
232but Windows policy is still preventing those users from launching sandboxed
233commands.
234
235What to do:
236
2371. Ask your IT team whether the device policy grants the required logon rights
238 to the Codex-created sandbox users.
2392. Compare group policy or OU differences if the issue affects only some
240 machines or teams.
2413. If you need to keep working immediately, use the `unelevated` sandbox while
242 the policy issue is investigated.
2434. Send `CODEX_HOME/.sandbox/sandbox.log` along with your Windows version and a
244 short description of the failure.
245
246Codex warns that some folders are writable by Everyone
247
248Codex may warn that some folders are writable by `Everyone`.
249
250If you see this warning, Windows permissions on those folders are too broad for
251the sandbox to fully protect them.
252
253What to do:
254
2551. Review the folders Codex lists in the warning.
2562. Remove `Everyone` write access from those folders if that is appropriate in
257 your environment.
2583. Restart Codex or re-run the sandbox setup after those permissions are
259 corrected.
260
261If you are not sure how to change those permissions, ask your IT team for help.
262
263Sandboxed commands cannot reach the network
264
265Some Codex tasks are intentionally run without outbound network access,
266depending on the permissions mode in use.
267
268If a task fails because it cannot reach the network:
269
2701. Check whether the task was supposed to run with network disabled.
2712. If you expected network access, restart Codex and try again.
2723. If the issue keeps happening, collect the sandbox log so the team can check
273 whether the machine is in a partial or broken sandbox state.
274
275Sandboxing worked before and then stopped
276
277This can happen after:
278
279- moving a repo or workspace,
280- changing machine permissions,
281- changing Windows policies,
282- or other system configuration changes.
283
284What to try:
285
2861. Restart Codex.
2872. Try the `elevated` sandbox setup again.
2883. If that does not fix it, use the `unelevated` sandbox as a temporary
289 fallback.
2904. Collect the sandbox log for review.
291
292I need to send diagnostics to OpenAI
293
294If you still have problems, send:
295
296- `CODEX_HOME/.sandbox/sandbox.log`
297
298It is also helpful to include:
299
300- a short description of what you were trying to do,
301- whether the `elevated` sandbox failed or the `unelevated` sandbox was used,
302- any error message shown in the app,
303- whether you saw `1385` or another Windows or PowerShell error,
304- and whether you are on Windows 11 or Windows 10.
305
306Do not send:
105 307
106308### Troubleshooting and FAQ- the contents of `CODEX_HOME/.sandbox-secrets/`
107 309
108310#### Installed extension, but it’s unresponsiveThe IDE extension is installed but unresponsive
109 311
110Your system may be missing C++ development tools, which some native dependencies require:312Your system may be missing C++ development tools, which some native dependencies require:
111 313
115 317
116Then fully restart VS Code after installation.318Then fully restart VS Code after installation.
117 319
118320#### If it feels slow on large repositoriesLarge repositories feel slow in WSL
119 321
120- Make sure you’re not working under `/mnt/c`. Move the repository to WSL (for example, `~/code/…`).322- Make sure you’re not working under `/mnt/c`. Move the repository to WSL (for example, `~/code/…`).
121- Increase memory and CPU for WSL if needed; update WSL to the latest version:323- Increase memory and CPU for WSL if needed; update WSL to the latest version:
125 wsl --shutdown327 wsl --shutdown
126 ```328 ```
127 329
128330#### VS Code in WSL can’t find `codex`VS Code in WSL cannot find codex
129 331
130Verify the binary exists and is on PATH inside WSL:332Verify the binary exists and is on PATH inside WSL:
131 333