windows.md Codex Docs, 2026-03-20 00:35 UTC → 2026-05-02 00:48 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).

5 

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

4 9 

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

6 11 

8 13 

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)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)

10 15 

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

17practical ways:

12 18 

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

14 22 

15## Windows sandbox23## Windows sandbox

16 24 

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

18 28 

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

30`config.toml`:

31 

32```toml

20[windows]33[windows]

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

22```35```

23 36 

24How `elevated` mode works: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.

25 47 

26- Uses a Restricted Token approach with filesystem ACLs to limit which files the sandbox can write to.48If both modes are available, use `elevated`. If the default native sandbox

27- Runs commands as a dedicated Windows Sandbox User.49doesn't work in your environment, use `unelevated` as a fallback while you

28- Limits network access by installing Windows Firewall rules.50troubleshoot the setup.

29- Uses a private desktop by default for stronger UI isolation. Set `windows.sandbox_private_desktop = false` only if you need the older `Winsta0\\Default` behavior for compatibility.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.

30 55 

31### Sandbox permissions56### Sandbox permissions

32 57 

38 Codex attempt to solve problems without asking for escalated permissions,63 Codex attempt to solve problems without asking for escalated permissions,

39 based on your [approval and security setup](https://developers.openai.com/codex/agent-approvals-security).64 based on your [approval and security setup](https://developers.openai.com/codex/agent-approvals-security).

40 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 

41### Grant sandbox read access82### Grant sandbox read access

42 83 

43When a command fails because the Windows sandbox can't read a directory, use:84When a command fails because the Windows sandbox can't read a directory, use:

48 89 

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

50 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.

95 

51## Windows Subsystem for Linux96## Windows Subsystem for Linux

52 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 

53### Launch VS Code from inside WSL106### Launch VS Code from inside WSL

54 107 

55For 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).

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

86 `C:\`) for best performance.139 `C:\`) for best performance.

87 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 

88### Use Codex CLI with WSL145### Use Codex CLI with WSL

89 146 

90Run these commands from an elevated PowerShell or Windows Terminal:147Run these commands from an elevated PowerShell or Windows Terminal:

125 182 

126## Troubleshooting and FAQ183## Troubleshooting and FAQ

127 184 

128#### Installed extension, but it’s unresponsive185If 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.

189 

190My native sandbox setup failed

191 

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

193are:

194 

195- 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.

200 

201What to try:

202 

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

204 if your environment allows it.

2052. 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.

210 

211Codex 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:

307 

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

309 

310The IDE extension is installed but unresponsive

129 311 

130Your 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:

131 313 

135 317 

136Then fully restart VS Code after installation.318Then fully restart VS Code after installation.

137 319 

138#### If it feels slow on large repositories320Large repositories feel slow in WSL

139 321 

140- 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/…`).

141- 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:

145 wsl --shutdown327 wsl --shutdown

146 ```328 ```

147 329 

148#### VS Code in WSL can’t find `codex`330VS Code in WSL cannot find codex

149 331 

150Verify the binary exists and is on PATH inside WSL:332Verify the binary exists and is on PATH inside WSL:

151 333