From fa0f2b34c8d2dd38488250e2355278f700d94931 Mon Sep 17 00:00:00 2001 From: Prekshi Vyas Date: Tue, 29 Sep 2026 12:21:05 -0700 Subject: [PATCH 1/2] docs(mxc): document Windows host preparation Signed-off-by: Prekshi Vyas --- crates/openshell-driver-mxc/README.md | 21 ++++++++++++++++++ .../examples/README-ocsf-audit.txt | 11 +++++++++- .../examples/README-openclaw-forward.txt | 11 +++++++++- .../openshell-driver-mxc/examples/README.txt | 13 ++++++++++- docs/reference/gateway-config.mdx | 22 +++++++++++++++++++ 5 files changed, 75 insertions(+), 3 deletions(-) diff --git a/crates/openshell-driver-mxc/README.md b/crates/openshell-driver-mxc/README.md index c4f1bfefdd..cffe75df56 100644 --- a/crates/openshell-driver-mxc/README.md +++ b/crates/openshell-driver-mxc/README.md @@ -168,6 +168,27 @@ 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, obtain `wxc-host-prep.exe` from +the MXC binaries distribution and run this command once in an elevated +PowerShell session: + +```powershell +& "C:\path\to\wxc-host-prep.exe" prepare-system-drive +``` + +This command makes a persistent, host-wide ACL change that gives the +AppContainer well-known SIDs the minimum access needed to inspect the system +drive root. If `wxc-exec.exe` starts but the agent exits with +`wxc-exec stderr: Access is denied.` or exit code 1, confirm that the elevated +host-preparation command completed successfully. + For off-box smoke tests against the in-process mock shim (no `wxc-exec`, no isolation session needed), set `OPENSHELL_MXC_MOCK_WXC=1`. diff --git a/crates/openshell-driver-mxc/examples/README-ocsf-audit.txt b/crates/openshell-driver-mxc/examples/README-ocsf-audit.txt index 51bedd26a7..331012256b 100644 --- a/crates/openshell-driver-mxc/examples/README-ocsf-audit.txt +++ b/crates/openshell-driver-mxc/examples/README-ocsf-audit.txt @@ -21,7 +21,16 @@ 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, 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 + This makes a persistent, host-wide ACL change for the AppContainer + well-known SIDs. If the agent exits with "wxc-exec stderr: Access is + denied." or exit code 1, confirm this command completed successfully. - 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; diff --git a/crates/openshell-driver-mxc/examples/README-openclaw-forward.txt b/crates/openshell-driver-mxc/examples/README-openclaw-forward.txt index c3aa149896..9fd50d4afc 100644 --- a/crates/openshell-driver-mxc/examples/README-openclaw-forward.txt +++ b/crates/openshell-driver-mxc/examples/README-openclaw-forward.txt @@ -40,7 +40,16 @@ 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, 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 + This makes a persistent, host-wide ACL change for the AppContainer + well-known SIDs. If the agent exits with "wxc-exec stderr: Access is + denied." or exit code 1, confirm this command completed successfully. - process_container or isolation_session backend live (whichever -Backend you pass) - Your own OpenClaw install: a node.exe binary + the openclaw npm package diff --git a/crates/openshell-driver-mxc/examples/README.txt b/crates/openshell-driver-mxc/examples/README.txt index 659124f9e5..5052f79c3f 100644 --- a/crates/openshell-driver-mxc/examples/README.txt +++ b/crates/openshell-driver-mxc/examples/README.txt @@ -17,7 +17,18 @@ 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, obtain wxc-host-prep.exe from the + MXC binaries distribution. In an elevated PowerShell session, run this + one-time host setup command: + & "C:\path\to\wxc-host-prep.exe" prepare-system-drive + This makes a persistent, host-wide ACL change for the AppContainer + well-known SIDs. If wxc-exec starts but the agent exits with + "wxc-exec stderr: Access is denied." or exit code 1, confirm this command + completed successfully. - 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. diff --git a/docs/reference/gateway-config.mdx b/docs/reference/gateway-config.mdx index dce1b313a5..5fd951b26d 100644 --- a/docs/reference/gateway-config.mdx +++ b/docs/reference/gateway-config.mdx @@ -933,6 +933,28 @@ 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, obtain `wxc-host-prep.exe` from +the MXC binaries distribution and run this command once in an elevated +PowerShell session: + +```shell +& "C:\path\to\wxc-host-prep.exe" prepare-system-drive +``` + +This command makes a persistent, host-wide ACL change that gives the +AppContainer well-known SIDs the minimum access needed to inspect the system +drive root. If `wxc-exec.exe` starts but the agent exits with +`wxc-exec stderr: Access is denied.` or exit code 1, confirm that the elevated +host-preparation command completed successfully. + ```toml [openshell] version = 1 From 0cea165bbaaf188925dbe95410b453697d65d730 Mon Sep 17 00:00:00 2001 From: Shailendra Singh Date: Tue, 29 Sep 2026 15:06:11 -0700 Subject: [PATCH 2/2] docs(mxc): scope host ACL preparation to the DACL fallback Signed-off-by: Shailendra Singh --- crates/openshell-driver-mxc/README.md | 27 +++++++++++++------ .../examples/README-ocsf-audit.txt | 20 ++++++++++---- .../examples/README-openclaw-forward.txt | 20 ++++++++++---- .../openshell-driver-mxc/examples/README.txt | 22 ++++++++++----- docs/reference/gateway-config.mdx | 27 +++++++++++++------ 5 files changed, 83 insertions(+), 33 deletions(-) diff --git a/crates/openshell-driver-mxc/README.md b/crates/openshell-driver-mxc/README.md index cffe75df56..674892ceae 100644 --- a/crates/openshell-driver-mxc/README.md +++ b/crates/openshell-driver-mxc/README.md @@ -175,19 +175,30 @@ 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, obtain `wxc-host-prep.exe` from -the MXC binaries distribution and run this command once in an elevated -PowerShell session: +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 command makes a persistent, host-wide ACL change that gives the -AppContainer well-known SIDs the minimum access needed to inspect the system -drive root. If `wxc-exec.exe` starts but the agent exits with -`wxc-exec stderr: Access is denied.` or exit code 1, confirm that the elevated -host-preparation command completed successfully. +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`. diff --git a/crates/openshell-driver-mxc/examples/README-ocsf-audit.txt b/crates/openshell-driver-mxc/examples/README-ocsf-audit.txt index 331012256b..c81a047aed 100644 --- a/crates/openshell-driver-mxc/examples/README-ocsf-audit.txt +++ b/crates/openshell-driver-mxc/examples/README-ocsf-audit.txt @@ -25,12 +25,22 @@ PREREQUISITES (on this test box) 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, obtain wxc-host-prep.exe from the - MXC binaries distribution and run this once in elevated PowerShell: + - 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 - This makes a persistent, host-wide ACL change for the AppContainer - well-known SIDs. If the agent exits with "wxc-exec stderr: Access is - denied." or exit code 1, confirm this command completed successfully. + 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; diff --git a/crates/openshell-driver-mxc/examples/README-openclaw-forward.txt b/crates/openshell-driver-mxc/examples/README-openclaw-forward.txt index 9fd50d4afc..810cd2a9b8 100644 --- a/crates/openshell-driver-mxc/examples/README-openclaw-forward.txt +++ b/crates/openshell-driver-mxc/examples/README-openclaw-forward.txt @@ -44,12 +44,22 @@ PREREQUISITES (on this test box) 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, obtain wxc-host-prep.exe from the - MXC binaries distribution and run this once in elevated PowerShell: + - 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 - This makes a persistent, host-wide ACL change for the AppContainer - well-known SIDs. If the agent exits with "wxc-exec stderr: Access is - denied." or exit code 1, confirm this command completed successfully. + 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 diff --git a/crates/openshell-driver-mxc/examples/README.txt b/crates/openshell-driver-mxc/examples/README.txt index 5052f79c3f..6e010dbd00 100644 --- a/crates/openshell-driver-mxc/examples/README.txt +++ b/crates/openshell-driver-mxc/examples/README.txt @@ -21,14 +21,22 @@ Prerequisites 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, obtain wxc-host-prep.exe from the - MXC binaries distribution. In an elevated PowerShell session, run this - one-time host setup command: + - 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 - This makes a persistent, host-wide ACL change for the AppContainer - well-known SIDs. If wxc-exec starts but the agent exits with - "wxc-exec stderr: Access is denied." or exit code 1, confirm this command - completed successfully. + 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. diff --git a/docs/reference/gateway-config.mdx b/docs/reference/gateway-config.mdx index 5fd951b26d..ab1702a896 100644 --- a/docs/reference/gateway-config.mdx +++ b/docs/reference/gateway-config.mdx @@ -941,19 +941,30 @@ 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, obtain `wxc-host-prep.exe` from -the MXC binaries distribution and run this command once in an elevated -PowerShell session: +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 command makes a persistent, host-wide ACL change that gives the -AppContainer well-known SIDs the minimum access needed to inspect the system -drive root. If `wxc-exec.exe` starts but the agent exits with -`wxc-exec stderr: Access is denied.` or exit code 1, confirm that the elevated -host-preparation command completed successfully. +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]