32 32
33 33
34 34
35The native Windows sandbox has two modes:35Codex supports three Windows sandbox implementations:
36 36
37- natively on Windows with the stronger `elevated` sandbox,37- `mxc`: The recommended sandbox on compatible Windows devices where policy permits it. Uses process isolation without administrator-approved setup, additional Windows accounts, changes to host file permissions, or local firewall rules.
38- natively on Windows with the fallback `unelevated` sandbox.38- `elevated`: The preferred legacy fallback when MXC is unavailable or disabled. Requires administrator-approved setup. Commands in the sandbox run without administrator privileges.
39- `unelevated`: A legacy fallback when elevated setup is unavailable and organizational policy permits it. Has weaker network isolation than `elevated` and doesn't support denied read paths.
39 40
40 41
41 42
43 44
44## Configure the Windows sandbox45## Configure the Windows sandbox
45 46
46When you run Codex natively on Windows, agent mode uses a Windows sandbox to47The Windows sandbox enforces the active filesystem and network permissions for
47block filesystem writes outside the working folder and prevent network access48commands and their child processes. The permission profile determines which
48without your explicit approval.49paths are readable or writable and whether network access is allowed. Approval
50policy separately controls when Codex asks to run commands with more access.
51See [sandbox and approvals](https://learn.chatgpt.com/docs/agent-approvals-security).
49 52
50Native Windows sandbox support includes two modes that you can configure in53### Control MXC rollout
51`config.toml`:54
55These settings are available in Codex CLI 0.162.0. In the standalone CLI,
56`features.prefer_mxc` is off by default. The desktop app can enable this
57preference through its rollout configuration.
58
59#### Prefer MXC with legacy fallback
60
61To use MXC when the device and policy support it, add this to `config.toml`:
62
63```toml
64[features]
65prefer_mxc = true
66```
67
68Keep `windows.sandbox` set to your organization's permitted legacy implementation,
69`elevated` or `unelevated`, for fallback.
70
71Codex uses MXC for local Windows commands when the device and policy support it,
72even when `windows.sandbox` selects a legacy implementation. Otherwise, it uses
73the existing legacy selection and setup flow. This includes devices without
74MXC support and policies that set `windows.allow_mxc = false` or forbid local
75binding. `windows.allowed_sandbox_implementations` still constrains fallback;
76permission profiles and other managed requirements continue to apply.
77
78Fallback happens during sandbox selection. Commands that fail after MXC is
79selected aren't retried in a legacy sandbox.
80
81Administrators can distribute this configuration as a default or enforce
82`features.prefer_mxc = true` through `requirements.toml`. Both permit legacy
83fallback. See [managed configuration](https://learn.chatgpt.com/docs/enterprise/managed-configuration)
84for how defaults and requirements differ.
85
86#### Keep MXC disabled
87
88To prevent MXC use in your organization, add this to your managed
89`requirements.toml`:
90
91```toml
92[windows]
93allow_mxc = false
94```
95
96This blocks both automatic MXC selection and explicit `windows.sandbox = "mxc"`.
97Existing legacy sandbox settings and requirements still apply. Configure
98`windows.allow_mxc` in `requirements.toml`, not `config.toml`.
99
100### MXC compatibility
101
102Microsoft Execution Containers (MXC) uses native Windows process isolation
103without creating sandbox accounts, changing host file permissions, or running
104the classic elevated setup. Commands run under the user's Windows identity
105with a policy applied to each command. MXC doesn't require administrator
106elevation for sandbox setup or local Windows Firewall rules.
107MXC accepts readable, writable, and denied paths from the active permission
108profile. Its native network policy controls command network access without
109depending on the legacy sandbox's firewall provisioning.
110
111Before selecting MXC, validate the required capabilities and your workloads on
112the Windows 11 device. A Windows version number alone doesn't establish
113compatibility.
114
115In Codex CLI 0.162.0, you can test MXC for one command without changing the saved
116sandbox selection. From your project directory, run:
117
118```powershell
119codex -c windows.sandbox=mxc sandbox --include-managed-config --permission-profile :workspace -- cmd.exe /d /c echo MXC_OK
120$LASTEXITCODE
121```
122
123Expected output is `MXC_OK` and exit code `0`. This checks command startup with
124the workspace permission profile and managed requirements. Also test permitted
125file access, expected denials, PowerShell, and your network policy before using
126MXC for normal work.
127
128Explicit `windows.sandbox = "mxc"` selection fails if the required native
129capabilities are unavailable; it doesn't fall back to a classic implementation.
130Policies with denied paths also require native deny-path support.
131
132Check these compatibility limits:
133
134- Managed networking requires effective `allow_local_binding = true`. MXC
135 permits connections to and from services on host loopback. Proxy domain rules
136 still apply to proxied traffic, but the proxy's additional private-network
137 destination checks are removed. This doesn't enable networking when it's disabled.
138- Remaining child processes stop when the foreground command exits. Test
139 workflows that rely on detached development servers.
140
141### Configure a legacy fallback
142
143Select the fallback implementation in `config.toml`:
52 144
53```toml145```toml
54[windows]146[windows]
55sandbox = "elevated" # or "unelevated"147sandbox = "elevated" # or "unelevated"
56```148```
57 149
58`elevated` is the preferred native Windows sandbox. It uses dedicated150`elevated` is the preferred legacy fallback. It uses dedicated
59lower-privilege sandbox users, filesystem permission boundaries, firewall151lower-privilege sandbox users, filesystem permission boundaries, firewall
60rules, and local policy changes needed for commands that run in the sandbox.152rules, and local policy changes needed for commands that run in the sandbox.
61 153
62`unelevated` is the fallback native Windows sandbox. It runs commands with a154`unelevated` is a legacy fallback. It runs commands with a
63restricted Windows token derived from your current user, applies ACL-based155restricted Windows token derived from your current user, applies ACL-based
64filesystem boundaries, and uses environment-level offline controls instead of156filesystem boundaries, and uses environment-level offline controls instead of
65the dedicated offline-user firewall rule. It's weaker than `elevated`, but it157the dedicated offline-user firewall rule. It provides weaker network isolation
66is still useful when administrator-approved setup is blocked by local or158than `elevated` and doesn't support denied read paths, but is still useful when
67enterprise policy.159administrator-approved setup is blocked by local or enterprise policy.
68 160
69If both modes are available, use `elevated`. If the default native sandbox161Use MXC when the device and policy support it. Otherwise, prefer `elevated`.
70doesn't work in your environment, use `unelevated` as a fallback while you162Use `unelevated` as a fallback only when your organization's policy permits it.
71troubleshoot the setup.
72 163
73Enterprise administrators can constrain which native sandbox implementations164Enterprise administrators can constrain which classic sandbox implementations
74Codex can use through [`requirements.toml`](https://learn.chatgpt.com/docs/enterprise/managed-configuration#admin-enforced-requirements-requirementstoml):165Codex can use through [`requirements.toml`](https://learn.chatgpt.com/docs/enterprise/managed-configuration#admin-enforced-requirements-requirementstoml):
75 166
76```toml167```toml
78allowed_sandbox_implementations = ["elevated"]169allowed_sandbox_implementations = ["elevated"]
79```170```
80 171
81This example requires the `elevated` sandbox and prevents users from falling172This example permits `elevated` and prevents fallback to `unelevated`. It does
82back to `unelevated`. To permit either implementation, include both values;173not restrict `mxc` when MXC is available. Other managed permission and network
83Codex prefers `elevated` when no mode is selected. See the174requirements still apply. To permit either classic implementation, include
175both values; Codex prefers `elevated` when no mode is selected. See the
84[`requirements.toml` reference](https://learn.chatgpt.com/docs/config-file/config-reference#requirementstoml) for176[`requirements.toml` reference](https://learn.chatgpt.com/docs/config-file/config-reference#requirementstoml) for
85the supported values.177the supported values. To block MXC as well, use the separate
178[`windows.allow_mxc` requirement](#keep-mxc-disabled).
179
180By default, both legacy sandbox modes also use a private desktop for stronger UI
181isolation.
182
183#### Provision the classic elevated sandbox
86 184
87By default, both sandbox modes also use a private desktop for stronger UI185For employees without local administrator rights, IT can install the CLI and
88isolation. Set `windows.sandbox_private_desktop = false` only if you need the186provision the sandbox before the employee starts Codex. From an elevated
89older `Winsta0\\Default` behavior for compatibility.187deployment process, run:
188
189```powershell
190codex sandbox setup --elevated --user 'DOMAIN\alice' --codex-home 'C:\Users\alice\.codex'
191```
192
193Replace the identity and path with the employee's Windows identity and
194`CODEX_HOME`. The command reads that user's configuration, provisions the
195sandbox, and saves `windows.sandbox = "elevated"`. The employee then runs Codex
196from a normal terminal. Using a non-admin terminal doesn't select the
197`unelevated` implementation.
90 198
91### Sandbox permissions199### Sandbox permissions
92 200
111 219
112- `winget` should be available. If it's missing, update Windows or install220- `winget` should be available. If it's missing, update Windows or install
113 the Windows Package Manager before setting up Codex.221 the Windows Package Manager before setting up Codex.
114- The recommended native sandbox depends on administrator-approved setup.222- The classic `elevated` sandbox depends on administrator-approved setup.
115- Some enterprise-managed devices block the required setup steps even when the223- Some enterprise-managed devices block the required setup steps even when the
116 OS version itself is acceptable.224 OS version itself is acceptable.
225- MXC additionally requires the native capabilities described in
226 [MXC compatibility](#mxc-compatibility); this matrix doesn't establish MXC
227 availability on a particular device.
117 228
118### Grant sandbox read access229### Check sandbox read access
119
120When a command fails because the Windows sandbox can't read a directory, use:
121
122```text
123/sandbox-add-read-dir C:\absolute\directory\path
124```
125 230
126The 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.231When a command can't read a directory, check the active permission profile,
232managed requirements, and Windows file permissions. In the CLI, use `/status`
233and `/debug-config` to inspect the active session and configuration. Ask your
234administrator to review a managed restriction rather than disabling the sandbox.
127 235
128 236
129 237
131 239
132Use the native Windows sandbox by default. Choose [WSL](https://learn.chatgpt.com/docs/windows/wsl)240Use the native Windows sandbox by default. Choose [WSL](https://learn.chatgpt.com/docs/windows/wsl)
133when you need Linux-native tooling, your workflow already lives in WSL2, or241when you need Linux-native tooling, your workflow already lives in WSL2, or
134neither native Windows sandbox mode meets your needs.242the available native Windows implementations don't meet your needs.
135 243
136## Troubleshooting and FAQ244## Troubleshooting and FAQ
137 245
138If you are troubleshooting a managed Windows machine, start with the native246If you are troubleshooting a managed Windows machine, start with the native
139sandbox mode, Windows version, and any policy error shown by Codex. Most native247sandbox mode, Windows version, and any policy error shown by Codex. For MXC,
140Windows support issues come from sandbox setup, logon rights, or filesystem248check [compatibility](#mxc-compatibility) and the effective network policy.
141permissions rather than from the editor itself.249Legacy sandbox issues can come from setup, logon rights, or filesystem permissions.
142 250
143 251
144 252
145### My native sandbox setup failed253### My legacy sandbox setup failed
146 254
147 255
148If Codex cannot complete the `elevated` sandbox setup, the most common causes256If Codex cannot complete the `elevated` sandbox setup, the most common causes
1612. If your company laptop blocks this, ask your IT team whether the machine2692. If your company laptop blocks this, ask your IT team whether the machine
162 allows administrator-approved setup for local user/group creation, firewall270 allows administrator-approved setup for local user/group creation, firewall
163 configuration, and the required sandbox-user logon rights.271 configuration, and the required sandbox-user logon rights.
1643. If the default setup still fails, use the `unelevated` sandbox so you can2723. If setup still fails and managed policy permits it, use `unelevated` while
165 continue working while the issue is investigated.273 the issue is investigated.
166 274
167 275
168 276
173### Codex switched me to the unelevated sandbox281### Codex switched me to the unelevated sandbox
174 282
175 283
176This means Codex could not finish the stronger `elevated` sandbox setup on your284The `unelevated` implementation may be selected in configuration or used as a
177machine.285fallback when `elevated` setup isn't available.
178 286
179- Codex can still run in a sandboxed mode.287- Codex can still run in a sandboxed mode.
180- It still applies ACL-based filesystem boundaries, but it does not use the288- It still applies ACL-based filesystem boundaries, but it does not use the
183- This is a useful fallback, but not the preferred long-term enterprise291- This is a useful fallback, but not the preferred long-term enterprise
184 configuration.292 configuration.
185 293
186If you are on a managed enterprise laptop, the best long-term fix is usually to294For a managed enterprise laptop, check [MXC compatibility](#mxc-compatibility)
187get the `elevated` sandbox working with help from your IT team.295first. If MXC is unavailable or disabled, ask your IT team to provision
296`elevated`.
188 297
189 298
190 299
275What to try:384What to try:
276 385
2771. Restart Codex.3861. Restart Codex.
2782. Try the `elevated` sandbox setup again.3872. For MXC, repeat the [compatibility probe](#mxc-compatibility) and check the
2793. If that does not fix it, use the `unelevated` sandbox as a temporary388 effective network policy. For the classic `elevated` implementation, try
280 fallback.389 sandbox setup again.
3903. If a classic sandbox is needed and managed policy permits it, use
391 `unelevated` as a temporary fallback.
2814. Collect the sandbox log for review.3924. Collect the sandbox log for review.
282 393
283 394
296It is also helpful to include:407It is also helpful to include:
297 408
298- a short description of what you were trying to do,409- a short description of what you were trying to do,
299- whether the `elevated` sandbox failed or the `unelevated` sandbox was used,410- the selected implementation: `mxc`, `elevated`, or `unelevated`,
300- any error message shown in the app,411- any error message shown in the app,
301- whether you saw `1385` or another Windows or PowerShell error,412- whether you saw `1385` or another Windows or PowerShell error,
413- your Windows build number,
302- and whether you are on Windows 11 or Windows 10.414- and whether you are on Windows 11 or Windows 10.
303 415
304Do not send:416Do not send:
