windows.md +205 −13
1# Windows1# Windows
2 2
33The 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.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
56When 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).[
6 7
78If 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.Use the Codex app on Windows
9
10Work across projects, run parallel agent threads, and review results in one place with the native Windows app.](https://developers.openai.com/codex/app/windows)
11
12Depending on the surface and your setup, Codex can run on Windows in three
13practical ways:
14
15- natively on Windows with the stronger `elevated` sandbox,
16- natively on Windows with the fallback `unelevated` sandbox,
17- or inside [Windows Subsystem for Linux](https://learn.microsoft.com/en-us/windows/wsl/install) (WSL), which uses the Linux sandbox implementation.
8 18
9## Windows sandbox19## Windows sandbox
10 20
1121Native 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
22block filesystem writes outside the working folder and prevent network access
23without your explicit approval.
12 24
1325```Native Windows sandbox support includes two modes that you can configure in
26`config.toml`:
27
28```toml
14[windows]29[windows]
1530sandbox = "unelevated" # or "elevated"sandbox = "elevated" # or "unelevated"
16```31```
17 32
1833How `elevated` mode works:`elevated` is the preferred native Windows sandbox. It uses dedicated
34lower-privilege sandbox users, filesystem permission boundaries, firewall
35rules, and local policy changes needed for sandboxed command execution.
36
37`unelevated` is the fallback native Windows sandbox. It runs commands with a
38restricted Windows token derived from your current user, applies ACL-based
39filesystem boundaries, and uses environment-level offline controls instead of
40the dedicated offline-user firewall rule. It is weaker than `elevated`, but it
41is still useful when administrator-approved setup is blocked by local or
42enterprise policy.
43
44If both modes are available, use `elevated`. If the default native sandbox
45doesn't work in your environment, use `unelevated` as a fallback while you
46troubleshoot the setup.
19 47
2048- Uses a Restricted Token approach with filesystem ACLs to limit which files the sandbox can write to.By default, both sandbox modes also use a private desktop for stronger UI
2149- Runs commands as a dedicated Windows Sandbox User.isolation. Set `windows.sandbox_private_desktop = false` only if you need the
2250- Limits network access by installing Windows Firewall rules.older `Winsta0\\Default` behavior for compatibility.
51
52### Sandbox permissions
53
54Running Codex in full access mode means Codex is not limited to your project
55 directory and might perform unintentional destructive actions that can lead to
56 data loss. For safer automation, keep sandbox boundaries in place and use
57 [rules](https://developers.openai.com/codex/rules) for specific exceptions, or set your [approval policy to
58 never](https://developers.openai.com/codex/agent-approvals-security#run-without-approval-prompts) to have
59 Codex attempt to solve problems without asking for escalated permissions,
60 based on your [approval and security setup](https://developers.openai.com/codex/agent-approvals-security).
61
62### Windows version matrix
63
64| Windows version | Support level | Notes |
65| -------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
66| Windows 11 | Recommended | Best baseline for Codex on Windows. Use this if you are standardizing an enterprise deployment. |
67| 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 October 2018 Update or newer is required. |
68| Older Windows 10 builds | Not recommended | More likely to miss required console components such as ConPTY and more likely to fail in enterprise setups. |
69
70Additional environment assumptions:
71
72- `winget` should be available. If it is missing, update Windows or install
73 the Windows Package Manager before setting up Codex.
74- The recommended native sandbox depends on administrator-approved setup.
75- Some enterprise-managed devices block the required setup steps even when the
76 OS version itself is acceptable.
23 77
24### Grant sandbox read access78### Grant sandbox read access
25 79
31 85
32The 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.86The 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.
33 87
88We recommend using the native Windows sandbox by default. The native Windows sandbox will offer the best perfomance and highest speeds while keeping the same security. Choose WSL when you
89need a Linux-native environment on Windows, when your workflow already lives in
90WSL, or when neither native Windows sandbox mode meets your needs.
91
34## Windows Subsystem for Linux92## Windows Subsystem for Linux
35 93
94If you choose WSL, Codex runs inside the Linux environment instead of using the
95native Windows sandbox. This is useful if you need Linux-native tooling on
96Windows, if your repositories and developer workflow already live in WSL, or
97if neither native Windows sandbox mode works for your environment.
98
36### Launch VS Code from inside WSL99### Launch VS Code from inside WSL
37 100
38For step-by-step instructions, see the [official VS Code WSL tutorial](https://code.visualstudio.com/docs/remote/wsl-tutorial).101For step-by-step instructions, see the [official VS Code WSL tutorial](https://code.visualstudio.com/docs/remote/wsl-tutorial).
68 `WSL: Reopen Folder in WSL`, and keep your repository under `/home/...` (not131 `WSL: Reopen Folder in WSL`, and keep your repository under `/home/...` (not
69 `C:\`) for best performance.132 `C:\`) for best performance.
70 133
134If the Windows app or project picker does not show your WSL repository, type
135`\wsl$` into the file picker or Explorer, then navigate to your
136 distro's home directory.
137
71### Use Codex CLI with WSL138### Use Codex CLI with WSL
72 139
73Run these commands from an elevated PowerShell or Windows Terminal:140Run these commands from an elevated PowerShell or Windows Terminal:
108 175
109## Troubleshooting and FAQ176## Troubleshooting and FAQ
110 177
111178#### Installed extension, but it’s unresponsiveIf you are troubleshooting a managed Windows machine, start with the native
179sandbox mode, Windows version, and any policy error shown by Codex. Most native
180Windows support issues come from sandbox setup, logon rights, or filesystem
181permissions rather than from the editor itself.
182
183My native sandbox setup failed
184
185If Codex cannot complete the `elevated` sandbox setup, the most common causes
186are:
187
188- the Windows UAC or administrator prompt was declined,
189- the machine does not allow local user or group creation,
190- the machine does not allow firewall rule changes,
191- the machine blocks the logon rights needed by the sandbox users,
192- or another enterprise policy blocks part of the setup flow.
193
194What to try:
195
1961. Try the `elevated` sandbox setup again and approve the administrator prompt
197 if your environment allows it.
1982. If your company laptop blocks this, ask your IT team whether the machine
199 allows administrator-approved setup for local user/group creation, firewall
200 configuration, and the required sandbox-user logon rights.
2013. If the default setup still fails, use the `unelevated` sandbox so you can
202 continue working while the issue is investigated.
203
204Codex switched me to the unelevated sandbox
205
206This means Codex could not finish the stronger `elevated` sandbox setup on your
207machine.
208
209- Codex can still run in a sandboxed mode.
210- It still applies ACL-based filesystem boundaries, but it does not use the
211 separate sandbox-user boundary from `elevated` and has weaker network
212 isolation.
213- This is a useful fallback, but not the preferred long-term enterprise
214 configuration.
215
216If you are on a managed enterprise laptop, the best long-term fix is usually to
217get the `elevated` sandbox working with help from your IT team.
218
219I see Windows error 1385
220
221If sandboxed commands fail with error `1385`, Windows is denying the logon type
222the sandbox user needs in order to start the command.
223
224In practice, this usually means Codex created the sandbox users successfully,
225but Windows policy is still preventing those users from launching sandboxed
226commands.
227
228What to do:
229
2301. Ask your IT team whether the device policy grants the required logon rights
231 to the Codex-created sandbox users.
2322. Compare group policy or OU differences if the issue affects only some
233 machines or teams.
2343. If you need to keep working immediately, use the `unelevated` sandbox while
235 the policy issue is investigated.
2364. Send `CODEX_HOME/.sandbox/sandbox.log` along with your Windows version and a
237 short description of the failure.
238
239Codex warns that some folders are writable by Everyone
240
241Codex may warn that some folders are writable by `Everyone`.
242
243If you see this warning, Windows permissions on those folders are too broad for
244the sandbox to fully protect them.
245
246What to do:
247
2481. Review the folders Codex lists in the warning.
2492. Remove `Everyone` write access from those folders if that is appropriate in
250 your environment.
2513. Restart Codex or re-run the sandbox setup after those permissions are
252 corrected.
253
254If you are not sure how to change those permissions, ask your IT team for help.
255
256Sandboxed commands cannot reach the network
257
258Some Codex tasks are intentionally run without outbound network access,
259depending on the permissions mode in use.
260
261If a task fails because it cannot reach the network:
262
2631. Check whether the task was supposed to run with network disabled.
2642. If you expected network access, restart Codex and try again.
2653. If the issue keeps happening, collect the sandbox log so the team can check
266 whether the machine is in a partial or broken sandbox state.
267
268Sandboxing worked before and then stopped
269
270This can happen after:
271
272- moving a repo or workspace,
273- changing machine permissions,
274- changing Windows policies,
275- or other system configuration changes.
276
277What to try:
278
2791. Restart Codex.
2802. Try the `elevated` sandbox setup again.
2813. If that does not fix it, use the `unelevated` sandbox as a temporary
282 fallback.
2834. Collect the sandbox log for review.
284
285I need to send diagnostics to OpenAI
286
287If you still have problems, send:
288
289- `CODEX_HOME/.sandbox/sandbox.log`
290
291It is also helpful to include:
292
293- a short description of what you were trying to do,
294- whether the `elevated` sandbox failed or the `unelevated` sandbox was used,
295- any error message shown in the app,
296- whether you saw `1385` or another Windows or PowerShell error,
297- and whether you are on Windows 11 or Windows 10.
298
299Do not send:
300
301- the contents of `CODEX_HOME/.sandbox-secrets/`
302
303The IDE extension is installed but unresponsive
112 304
113Your system may be missing C++ development tools, which some native dependencies require:305Your system may be missing C++ development tools, which some native dependencies require:
114 306
118 310
119Then fully restart VS Code after installation.311Then fully restart VS Code after installation.
120 312
121313#### If it feels slow on large repositoriesLarge repositories feel slow in WSL
122 314
123- Make sure you’re not working under `/mnt/c`. Move the repository to WSL (for example, `~/code/…`).315- Make sure you’re not working under `/mnt/c`. Move the repository to WSL (for example, `~/code/…`).
124- Increase memory and CPU for WSL if needed; update WSL to the latest version:316- Increase memory and CPU for WSL if needed; update WSL to the latest version:
128 wsl --shutdown320 wsl --shutdown
129 ```321 ```
130 322
131323#### VS Code in WSL can’t find `codex`VS Code in WSL cannot find codex
132 324
133Verify the binary exists and is on PATH inside WSL:325Verify the binary exists and is on PATH inside WSL:
134 326