windows.md Codex Docs, 2026-02-20 12:16 UTC → 2026-02-24 06:27 UTC

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 [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).5When 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 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.7If 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.

8 

9## Windows sandbox

10 

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

12 

13```

14[windows]

15sandbox = "unelevated" # or "elevated"

16```

17 

18How `elevated` mode works:

19 

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

21- Runs commands as a dedicated Windows Sandbox User.

22- Limits network access by installing Windows Firewall rules.

23 

24### Grant sandbox read access

25 

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

27 

28```text

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

30```

31 

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.

8 33 

9## Windows Subsystem for Linux34## Windows Subsystem for Linux

10 35 

81 ```106 ```

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

83 108 

84## Windows experimental sandbox109## 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 110 

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

107 112