windows.md Codex Docs, 2026-02-24 00:33 UTC → 2026-03-20 00:35 UTC

1# Windows1# Windows

2 2 

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

4 4 

5When 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).5[![](/images/codex/codex-banner-icon.webp)

6 6 

7Instead, 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.7Use the Codex app on Windows

8 

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)

10 

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

12 

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.

14 

15## Windows sandbox

16 

17Native Windows sandbox support includes two modes that you can configure in `config.toml`:

18 

19```

20[windows]

21sandbox = "unelevated" # or "elevated"

22```

23 

24How `elevated` mode works:

25 

26- Uses a Restricted Token approach with filesystem ACLs to limit which files the sandbox can write to.

27- Runs commands as a dedicated Windows Sandbox User.

28- Limits network access by installing Windows Firewall rules.

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.

30 

31### Sandbox permissions

32 

33Running Codex in full access mode means Codex is not limited to your project

34 directory and might perform unintentional destructive actions that can lead to

35 data loss. For safer automation, keep sandbox boundaries in place and use

36 [rules](https://developers.openai.com/codex/rules) for specific exceptions, or set your [approval policy to

37 never](https://developers.openai.com/codex/agent-approvals-security#run-without-approval-prompts) to have

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

40 

41### Grant sandbox read access

42 

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

44 

45```text

46/sandbox-add-read-dir C:\absolute\directory\path

47```

48 

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.

8 50 

9## Windows Subsystem for Linux51## Windows Subsystem for Linux

10 52 

81 ```123 ```

82- If you need Windows access to files, they’re under `\wsl$\Ubuntu\home<user>` in Explorer.124- If you need Windows access to files, they’re under `\wsl$\Ubuntu\home<user>` in Explorer.

83 125 

84## Windows experimental sandbox126## Troubleshooting and FAQ

85 

86The Windows sandbox support is experimental. How it works:

87 

88- Launches commands inside a restricted token derived from an AppContainer profile.

89- Grants only specifically requested filesystem capabilities by attaching capability security identifiers to that profile.

90- Disables outbound network access by overriding proxy-related environment variables and inserting stub executables for common network tools.

91 

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

93 

94### Grant sandbox read access

95 

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

97 

98```text

99/sandbox-add-read-dir C:\absolute\directory\path

100```

101 

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

103 

104### Troubleshooting and FAQ

105 127 

106#### Installed extension, but it’s unresponsive128#### Installed extension, but it’s unresponsive

107 129