docs(mxc): document Windows host preparation (NVBug 6842834)

crates/openshell-driver-mxc/README.md

@@ -168,6 +168,38 @@ The MXC credential handoff is also fixed at sandbox creation. The gateway reject
   `openshell.exe`. Diagnose executable blocks with event 3077 in the
   `Microsoft-Windows-CodeIntegrity/Operational` log.
 
+Place `wxc-exec.exe` in a regular directory outside any installed MSIX or
+`WindowsApps` package directory. A package directory's ACLs can prevent the
+gateway from starting the executable outside its package context, even when
+the same binary runs after it is copied elsewhere. If sandbox creation fails
+with `wxc-exec spawn failed: Access is denied. (os error 5)`, verify that
+`wxc_exec_path` points to the standalone copy.
+
+Before the first live `process_container` run, check the selected isolation
+tier and host-preparation warnings in PowerShell:
+
+```powershell
+& "C:\path\to\wxc-exec.exe" --probe
+```
+
+If the probe selects AppContainer + DACL (`appcontainer-dacl`) and recommends
+`prepare-system-drive`, obtain `wxc-host-prep.exe` from the MXC binaries
+distribution and run this command once in an elevated PowerShell session.
+BaseContainer and AppContainer + BFS do not require this preparation.
+
+```powershell
+& "C:\path\to\wxc-host-prep.exe" prepare-system-drive
+```
+
+This persistent, host-wide change adds non-inheriting ACL entries that give
+the AppContainer well-known SIDs metadata access to the system-drive root. It
+does not grant directory listing or write access, or change descendant ACLs.
+If `wxc-exec.exe` starts but the agent exits with
+`wxc-exec stderr: Access is denied.` or exit code 1, check the probe warnings
+before changing host ACLs; these errors alone do not identify missing host
+preparation. See Microsoft's [MXC host-preparation guide](https://github.com/microsoft/mxc/blob/main/docs/host-prep.md)
+for verification, other host prerequisites, and rollback instructions.
+
 For off-box smoke tests against the in-process mock shim (no `wxc-exec`,
 no isolation session needed), set `OPENSHELL_MXC_MOCK_WXC=1`.
 

crates/openshell-driver-mxc/examples/README-ocsf-audit.txt

@@ -21,7 +21,26 @@ WHAT THIS PROVES / PRODUCES
     [2004] Detection Finding            - MXC setup activity errors (informational)
 
 PREREQUISITES (on this test box)
-  - wxc-exec.exe present (default expected: C:\mxc-kit\bin\wxc-exec.exe)
+  - wxc-exec.exe present (default expected: C:\mxc-kit\bin\wxc-exec.exe).
+    Use a standalone copy in a regular directory, not a copy inside an
+    installed MSIX or WindowsApps package directory. If CreateSandbox reports
+    "wxc-exec spawn failed: Access is denied. (os error 5)", check this path.
+  - Before the first process_container run, check the selected isolation tier
+    and host-preparation warnings in PowerShell:
+      & "C:\path\to\wxc-exec.exe" --probe
+    Only if the probe selects AppContainer + DACL (appcontainer-dacl) and
+    recommends prepare-system-drive, obtain wxc-host-prep.exe from the MXC
+    binaries distribution and run this once in elevated PowerShell:
+      & "C:\path\to\wxc-host-prep.exe" prepare-system-drive
+    BaseContainer and AppContainer + BFS do not require this preparation.
+    The persistent, host-wide ACL change grants the AppContainer well-known
+    SIDs metadata access to the system-drive root only; it does not grant
+    directory listing or write access, or change descendant ACLs.
+    If wxc-exec starts but the agent exits with "wxc-exec stderr: Access is
+    denied." or exit code 1, check the probe warnings before changing host
+    ACLs; these errors alone do not identify missing host preparation.
+    For verification, other host prerequisites, and rollback, see:
+      https://github.com/microsoft/mxc/blob/main/docs/host-prep.md
   - process_container backend live (it was for our earlier runs)
   - Run ELEVATED (Run as administrator) OR from an account in the
     'Performance Log Users' group. Opening the real-time ETW session needs this;

crates/openshell-driver-mxc/examples/README-openclaw-forward.txt

@@ -40,7 +40,26 @@ PREREQUISITES (on this test box)
     ownership. Non-elevated fails both with ERROR_ACCESS_DENIED (0x5), the
     second as "Network proxy error: Failed to set loopback exemption:
     0x00000005". -Backend isolation_session does not hit either path.
-  - wxc-exec.exe present (default expected: C:\mxc-kit\bin\wxc-exec.exe)
+  - wxc-exec.exe present (default expected: C:\mxc-kit\bin\wxc-exec.exe).
+    Use a standalone copy in a regular directory, not a copy inside an
+    installed MSIX or WindowsApps package directory. If CreateSandbox reports
+    "wxc-exec spawn failed: Access is denied. (os error 5)", check this path.
+  - Before the first process_container run, check the selected isolation tier
+    and host-preparation warnings in PowerShell:
+      & "C:\path\to\wxc-exec.exe" --probe
+    Only if the probe selects AppContainer + DACL (appcontainer-dacl) and
+    recommends prepare-system-drive, obtain wxc-host-prep.exe from the MXC
+    binaries distribution and run this once in elevated PowerShell:
+      & "C:\path\to\wxc-host-prep.exe" prepare-system-drive
+    BaseContainer and AppContainer + BFS do not require this preparation.
+    The persistent, host-wide ACL change grants the AppContainer well-known
+    SIDs metadata access to the system-drive root only; it does not grant
+    directory listing or write access, or change descendant ACLs.
+    If wxc-exec starts but the agent exits with "wxc-exec stderr: Access is
+    denied." or exit code 1, check the probe warnings before changing host
+    ACLs; these errors alone do not identify missing host preparation.
+    For verification, other host prerequisites, and rollback, see:
+      https://github.com/microsoft/mxc/blob/main/docs/host-prep.md
   - process_container or isolation_session backend live (whichever -Backend
     you pass)
   - Your own OpenClaw install: a node.exe binary + the openclaw npm package

crates/openshell-driver-mxc/examples/README.txt

@@ -17,7 +17,26 @@ Prerequisites
   - openshell-gateway.exe and openshell.exe beside these files, or explicit
     -GatewayPath and -CliPath arguments.
   - wxc-exec.exe beside these files, on PATH, named by
-    OPENSHELL_WXC_EXEC_PATH, or passed with -WxcExecPath.
+    OPENSHELL_WXC_EXEC_PATH, or passed with -WxcExecPath. Use a standalone
+    copy in a regular directory. Do not use a copy from an installed MSIX or
+    WindowsApps package directory; its package ACLs can make CreateSandbox
+    fail with "wxc-exec spawn failed: Access is denied. (os error 5)".
+  - Before the first process_container run, check the selected isolation tier
+    and host-preparation warnings in PowerShell:
+      & "C:\path\to\wxc-exec.exe" --probe
+    Only if the probe selects AppContainer + DACL (appcontainer-dacl) and
+    recommends prepare-system-drive, obtain wxc-host-prep.exe from the MXC
+    binaries distribution and run this once in elevated PowerShell:
+      & "C:\path\to\wxc-host-prep.exe" prepare-system-drive
+    BaseContainer and AppContainer + BFS do not require this preparation.
+    The persistent, host-wide ACL change grants the AppContainer well-known
+    SIDs metadata access to the system-drive root only; it does not grant
+    directory listing or write access, or change descendant ACLs.
+    If wxc-exec starts but the agent exits with "wxc-exec stderr: Access is
+    denied." or exit code 1, check the probe warnings before changing host
+    ACLs; these errors alone do not identify missing host preparation.
+    For verification, other host prerequisites, and rollback, see:
+      https://github.com/microsoft/mxc/blob/main/docs/host-prep.md
   - Local demo: an Ollama-compatible service on 127.0.0.1:11434 by default.
     Override -OllamaHost, -OllamaPort, and -Model when needed.
   - Cloud demo: NV_API_KEY and outbound HTTPS to integrate.api.nvidia.com.

docs/reference/gateway-config.mdx

@@ -933,6 +933,39 @@ mount setup to bypass that profile.
 
 The MXC driver is Windows-only and opt-in. It links into the gateway, invokes Microsoft MXC through `wxc-exec.exe`, and runs each sandbox's configured command in-driver instead of using the Linux sandbox supervisor.
 
+#### Prepare the Windows host
+
+Copy `wxc-exec.exe` to a regular directory outside any installed MSIX or
+`WindowsApps` package directory. A package directory's ACLs can prevent the
+gateway from starting the executable outside its package context. If sandbox
+creation fails with `wxc-exec spawn failed: Access is denied. (os error 5)`,
+verify that `wxc_exec_path` points to the standalone copy.
+
+Before the first live `process_container` run, check the selected isolation
+tier and host-preparation warnings in PowerShell:
+
+```shell
+& "C:\path\to\wxc-exec.exe" --probe
+```
+
+If the probe selects AppContainer + DACL (`appcontainer-dacl`) and recommends
+`prepare-system-drive`, obtain `wxc-host-prep.exe` from the MXC binaries
+distribution and run this command once in an elevated PowerShell session.
+BaseContainer and AppContainer + BFS do not require this preparation.
+
+```shell
+& "C:\path\to\wxc-host-prep.exe" prepare-system-drive
+```
+
+This persistent, host-wide change adds non-inheriting ACL entries that give
+the AppContainer well-known SIDs metadata access to the system-drive root. It
+does not grant directory listing or write access, or change descendant ACLs.
+If `wxc-exec.exe` starts but the agent exits with
+`wxc-exec stderr: Access is denied.` or exit code 1, check the probe warnings
+before changing host ACLs; these errors alone do not identify missing host
+preparation. See Microsoft's [MXC host-preparation guide](https://github.com/microsoft/mxc/blob/main/docs/host-prep.md)
+for verification, other host prerequisites, and rollback instructions.
+
 ```toml
 [openshell]
 version = 1