windows.md Codex Docs, 2026-03-08 18:10 UTC → 2026-04-16 00:46 UTC

1# Windows1# Windows

2 2 

3The 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.3Use 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 

5[![](/images/codex/codex-banner-icon.webp)6[![](/images/codex/codex-banner-icon.webp)

6 7 

8 9 

9Work across projects, run parallel agent threads, and review results in one place with the native Windows app.](https://developers.openai.com/codex/app/windows)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)

10 11 

11When 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).12Depending on the surface and your setup, Codex can run on Windows in three

13practical ways:

12 14 

13If 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.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 2](https://learn.microsoft.com/en-us/windows/wsl/install) (WSL2), which uses the Linux sandbox implementation.

14 18 

15## Windows sandbox19## Windows sandbox

16 20 

17Native Windows sandbox support includes two modes that you can configure in `config.toml`:21When 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.

18 24 

19```25Native Windows sandbox support includes two modes that you can configure in

26`config.toml`:

27 

28```toml

20[windows]29[windows]

21sandbox = "unelevated" # or "elevated"30sandbox = "elevated" # or "unelevated"

22```31```

23 32 

24How `elevated` mode works:33`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 commands that run in the sandbox.

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's 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.

47 

48By default, both sandbox modes also use a private desktop for stronger UI

49isolation. Set `windows.sandbox_private_desktop = false` only if you need the

50older `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).

25 61 

26- Uses a Restricted Token approach with filesystem ACLs to limit which files the sandbox can write to.62### Windows version matrix

27- Runs commands as a dedicated Windows Sandbox User.63 

28- Limits network access by installing Windows Firewall rules.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 version 1809 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's 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.

29 77 

30### Grant sandbox read access78### Grant sandbox read access

31 79 

37 85 

38The 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.

39 87 

88Use 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

89need a Linux-native environment on Windows, when your workflow already lives in

90WSL2, or when neither native Windows sandbox mode meets your needs.

91 

40## Windows Subsystem for Linux92## Windows Subsystem for Linux

41 93 

94If you choose WSL2, 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 WSL2, or

97if neither native Windows sandbox mode works for your environment.

98 

99WSL1 was supported through Codex `0.114`. Starting in Codex `0.115`, the Linux

100sandbox moved to `bubblewrap`, so WSL1 is no longer supported.

101 

42### Launch VS Code from inside WSL102### Launch VS Code from inside WSL

43 103 

44For step-by-step instructions, see the [official VS Code WSL tutorial](https://code.visualstudio.com/docs/remote/wsl-tutorial).104For step-by-step instructions, see the [official VS Code WSL tutorial](https://code.visualstudio.com/docs/remote/wsl-tutorial).

74 `WSL: Reopen Folder in WSL`, and keep your repository under `/home/...` (not134 `WSL: Reopen Folder in WSL`, and keep your repository under `/home/...` (not

75 `C:\`) for best performance.135 `C:\`) for best performance.

76 136 

137If the Windows app or project picker does not show your WSL repository, type

138`\wsl$` into the file picker or Explorer, then navigate to your

139 distro's home directory.

140 

77### Use Codex CLI with WSL141### Use Codex CLI with WSL

78 142 

79Run these commands from an elevated PowerShell or Windows Terminal:143Run these commands from an elevated PowerShell or Windows Terminal:

114 178 

115## Troubleshooting and FAQ179## Troubleshooting and FAQ

116 180 

117#### Installed extension, but it’s unresponsive181If you are troubleshooting a managed Windows machine, start with the native

182sandbox mode, Windows version, and any policy error shown by Codex. Most native

183Windows support issues come from sandbox setup, logon rights, or filesystem

184permissions rather than from the editor itself.

185 

186My native sandbox setup failed

187 

188If Codex cannot complete the `elevated` sandbox setup, the most common causes

189are:

190 

191- the Windows UAC or administrator prompt was declined,

192- the machine does not allow local user or group creation,

193- the machine does not allow firewall rule changes,

194- the machine blocks the logon rights needed by the sandbox users,

195- or another enterprise policy blocks part of the setup flow.

196 

197What to try:

198 

1991. Try the `elevated` sandbox setup again and approve the administrator prompt

200 if your environment allows it.

2012. If your company laptop blocks this, ask your IT team whether the machine

202 allows administrator-approved setup for local user/group creation, firewall

203 configuration, and the required sandbox-user logon rights.

2043. If the default setup still fails, use the `unelevated` sandbox so you can

205 continue working while the issue is investigated.

206 

207Codex switched me to the unelevated sandbox

208 

209This means Codex could not finish the stronger `elevated` sandbox setup on your

210machine.

211 

212- Codex can still run in a sandboxed mode.

213- It still applies ACL-based filesystem boundaries, but it does not use the

214 separate sandbox-user boundary from `elevated` and has weaker network

215 isolation.

216- This is a useful fallback, but not the preferred long-term enterprise

217 configuration.

218 

219If you are on a managed enterprise laptop, the best long-term fix is usually to

220get the `elevated` sandbox working with help from your IT team.

221 

222I see Windows error 1385

223 

224If sandboxed commands fail with error `1385`, Windows is denying the logon type

225the sandbox user needs in order to start the command.

226 

227In practice, this usually means Codex created the sandbox users successfully,

228but Windows policy is still preventing those users from launching sandboxed

229commands.

230 

231What to do:

232 

2331. Ask your IT team whether the device policy grants the required logon rights

234 to the Codex-created sandbox users.

2352. Compare group policy or OU differences if the issue affects only some

236 machines or teams.

2373. If you need to keep working immediately, use the `unelevated` sandbox while

238 the policy issue is investigated.

2394. Send `CODEX_HOME/.sandbox/sandbox.log` along with your Windows version and a

240 short description of the failure.

241 

242Codex warns that some folders are writable by Everyone

243 

244Codex may warn that some folders are writable by `Everyone`.

245 

246If you see this warning, Windows permissions on those folders are too broad for

247the sandbox to fully protect them.

248 

249What to do:

250 

2511. Review the folders Codex lists in the warning.

2522. Remove `Everyone` write access from those folders if that is appropriate in

253 your environment.

2543. Restart Codex or re-run the sandbox setup after those permissions are

255 corrected.

256 

257If you are not sure how to change those permissions, ask your IT team for help.

258 

259Sandboxed commands cannot reach the network

260 

261Some Codex tasks are intentionally run without outbound network access,

262depending on the permissions mode in use.

263 

264If a task fails because it cannot reach the network:

265 

2661. Check whether the task was supposed to run with network disabled.

2672. If you expected network access, restart Codex and try again.

2683. If the issue keeps happening, collect the sandbox log so the team can check

269 whether the machine is in a partial or broken sandbox state.

270 

271Sandboxing worked before and then stopped

272 

273This can happen after:

274 

275- moving a repo or workspace,

276- changing machine permissions,

277- changing Windows policies,

278- or other system configuration changes.

279 

280What to try:

281 

2821. Restart Codex.

2832. Try the `elevated` sandbox setup again.

2843. If that does not fix it, use the `unelevated` sandbox as a temporary

285 fallback.

2864. Collect the sandbox log for review.

287 

288I need to send diagnostics to OpenAI

289 

290If you still have problems, send:

291 

292- `CODEX_HOME/.sandbox/sandbox.log`

293 

294It is also helpful to include:

295 

296- a short description of what you were trying to do,

297- whether the `elevated` sandbox failed or the `unelevated` sandbox was used,

298- any error message shown in the app,

299- whether you saw `1385` or another Windows or PowerShell error,

300- and whether you are on Windows 11 or Windows 10.

301 

302Do not send:

303 

304- the contents of `CODEX_HOME/.sandbox-secrets/`

305 

306The IDE extension is installed but unresponsive

118 307 

119Your system may be missing C++ development tools, which some native dependencies require:308Your system may be missing C++ development tools, which some native dependencies require:

120 309 

124 313 

125Then fully restart VS Code after installation.314Then fully restart VS Code after installation.

126 315 

127#### If it feels slow on large repositories316Large repositories feel slow in WSL

128 317 

129- Make sure you’re not working under `/mnt/c`. Move the repository to WSL (for example, `~/code/…`).318- Make sure you’re not working under `/mnt/c`. Move the repository to WSL (for example, `~/code/…`).

130- Increase memory and CPU for WSL if needed; update WSL to the latest version:319- Increase memory and CPU for WSL if needed; update WSL to the latest version:

134 wsl --shutdown323 wsl --shutdown

135 ```324 ```

136 325 

137#### VS Code in WSL can’t find `codex`326VS Code in WSL cannot find codex

138 327 

139Verify the binary exists and is on PATH inside WSL:328Verify the binary exists and is on PATH inside WSL:

140 329