fix(mxc): allow explicit sandbox-local TCP loopback

- Add pc_allow_loopback without enabling host-loopback or private-network ingress.
- Check effective loopback permission when forwarding, while allowing sandbox creation.
- Update the WebSocket demo configuration and listener readiness checks.
- Add driver and native regression coverage and document the network grants.

Signed-off-by: Akber Raza <akberr@nvidia.com>

Author: araza008

.agents/skills/build-openshell-mxc-windows/SKILL.md

@@ -194,6 +194,14 @@ architecture-appropriate task is therefore safe without real MXC hardware but
 must not be described as wholly skip-safe on supported hardware. Neither task
 is part of `windows:ci`'s ordered contract, so invoke it explicitly.
 
+The native suite also verifies `pc_allow_loopback` with no sandbox network
+rules or host proxy: same-sandbox TCP succeeds while host-loopback and the
+host's private interface remain blocked. Keep this distinct from broader
+`pc_allow_local_network` or governed-egress grants. The WebSocket lifecycle
+example uses `pc_allow_loopback = true`; capabilities alone do not supply it.
+Sandbox creation without the grant is allowed; a dynamic forward without an
+effective loopback grant is rejected before opening a relay listener.
+
 For GB300 Windows ARM64 qualification, do not use the skip-safe developer task
 as release evidence. `windows:test:mxc-gb300:arm64` runs the required
 ProcessContainer subset and fails on any required `SKIP`.

architecture/windows.md

@@ -137,9 +137,16 @@ prevent another sandbox from using the OpenShell proxy, but they do not isolate
 unrelated host-loopback services or authenticate individual processes within
 one sandbox.
 
+ProcessContainer sandbox-local TCP uses a separate, explicit
+`pc_allow_loopback` grant. It permits `127.0.0.1/32` egress while leaving
+private-network ingress and host-loopback denied, independently of governed
+egress or sandbox network rules. Capability names alone do not override MXC's
+deny-default networking. All network compatibility settings default to false.
+
 Two gateway-wide ProcessContainer compatibility settings can deliberately
 broaden this boundary. `pc_network_allow` permits unrestricted outbound TCP, and
-`pc_allow_local_network` enables MXC local-network access. These are operator
+`pc_allow_local_network` enables loopback egress, private-network ingress, and
+host-loopback access. These are operator
 configuration choices, not sandbox policy grants, and they must not be treated
 as policy-governed egress.
 
@@ -178,6 +185,11 @@ multiplexes `forward_open`, `forward_read`, `forward_write`, and
 authenticates each host-side forward. This capability does not add interactive
 shell or general exec support.
 
+The relay needs sandbox-local TCP access to dial its target. Sandbox creation
+does not require that grant. Dynamic forwarding checks the gateway's explicit
+network grants and the sandbox's active proxy state before opening a relay
+listener, rejecting a missing grant with a diagnostic naming `pc_allow_loopback`.
+
 The implementation boundary spans
 `crates/openshell-driver-mxc/src/control_channel.rs`,
 `crates/openshell-driver-mxc/src/relay.rs`, and

crates/openshell-driver-mxc/README.md

@@ -66,9 +66,11 @@ pc_minimal_env = false
 # A sandbox with egress_proxy enabled but no explicit network rules rejects
 # this fallback instead of silently changing governed egress to allow-all.
 pc_network_allow = false
-# processContainer only: include "allowLocalNetwork": true in the MXC
-# network section. This compatibility setting broadens network access and is
-# not required by the BaseContainer qualification profile.
+# processContainer only: sandbox-local 127.0.0.1 TCP, with host-loopback and
+# private-network ingress denied. Independent of egress_proxy/network rules.
+pc_allow_loopback = false
+# processContainer only: loopback egress plus private-network ingress and
+# host-loopback access. Prefer pc_allow_loopback for sandbox-local forwarding.
 pc_allow_local_network = false
 # Pattern C governed egress. Requires backend = "process_container".
 egress_proxy = false
@@ -95,6 +97,24 @@ fallback. If it is combined with `egress_proxy = true`, a sandbox policy
 without explicit network rules is rejected synchronously rather than falling
 through from governed egress to `defaultPolicy = "allow"`.
 
+`pc_allow_loopback = true` permits TCP between processes in the same sandbox
+through an MXC directional `127.0.0.1/32` egress rule. It keeps
+`ingress.default = "deny"` and `ingress.hostLoopback = "deny"`; it does not
+grant private-network or host-loopback access. It requires a native MXC build
+supporting directional CIDR rules and covers IPv4 only. The default is `false`.
+Neither `egress_proxy` nor sandbox `network_policies` is required, and no proxy
+listener, proxy environment, or CA share is created for this setting.
+`pc_capabilities = ["privateNetworkClientServer"]` alone does not override
+deny-default networking. `pc_allow_local_network` is a broader opt-in that
+also enables private-network ingress and host-loopback access.
+
+Sandbox creation does not require a loopback grant. When a dynamic forward is
+requested, the driver checks whether this grant, an active governed-egress
+proxy, or a compatibility network grant supplies loopback access. Otherwise,
+the forward is rejected before opening a relay listener, with a diagnostic
+naming `pc_allow_loopback = true` and instructing the operator to recreate the
+sandbox after changing the gateway configuration.
+
 Supply workload settings for each sandbox. The public config is keyed by driver name; the gateway forwards only the inner `mxc` object to the driver:
 
 ```powershell
@@ -107,7 +127,7 @@ The `command` array is required and preserves Windows argument boundaries. `cwd`
 
 UI capability (Win32k syscalls, clipboard, input injection) is a `SandboxPolicy` concern, not gateway TOML -- see the Capability Matrix above and `docs/reference/policy-schema.mdx`'s `ui` section. Defaults to disabled (Win32k syscall lockdown) when a policy has no explicit `ui:` section; set `allow_graphical_ui: true` for agents that touch user32/gdi32 at startup even without opening a real window (e.g. Node.js-based targets like OpenClaw's gateway -- see `examples/e2e-policies/openclaw-gateway.yaml`).
 
-`egress_proxy_addr` must be a `127.0.0.1:PORT` address. The port acts only as a configuration seed: for a sandbox policy with explicit network rules, the driver reserves a unique ephemeral loopback port. MXC 0.8 denies direct Internet egress and permits `127.0.0.1/32`; the driver points proxy-aware clients at the per-sandbox listener using environment variables. A policy without network rules keeps MXC's default network posture and receives neither a host listener nor proxy environment variables. The current governed-egress policy permits all loopback ports, so governed sandboxes can also reach unrelated host services bound to loopback. Control-channel forwarding does not require the legacy reverse-WebSocket connections to fresh host ports; restricting the generated policy is separate hardening work. Do not treat this path as loopback-service isolation. Live policy replacement or merge updates remain unsupported; delete and recreate the sandbox to apply a different policy.
+`egress_proxy_addr` must be a `127.0.0.1:PORT` address. The port acts only as a configuration seed: for a sandbox policy with explicit network rules, the driver reserves a unique ephemeral loopback port. MXC 0.8 denies direct Internet egress and permits `127.0.0.1/32`; the driver points proxy-aware clients at the per-sandbox listener using environment variables. A policy without network rules receives neither a host listener nor proxy environment variables; its effective network posture follows the explicit ProcessContainer settings above. The current governed-egress policy permits all loopback ports, so governed sandboxes can also reach unrelated host services bound to loopback. Control-channel forwarding does not require the legacy reverse-WebSocket connections to fresh host ports; restricting the generated policy is separate hardening work. Do not treat this path as loopback-service isolation. Live policy replacement or merge updates remain unsupported; delete and recreate the sandbox to apply a different policy.
 
 When `etw_audit` is enabled, each gateway process owns a distinct real-time ETW
 session named from the stable `OpenShell-MXC-ETW` prefix, its process ID, and a

crates/openshell-driver-mxc/examples/e2e-policies/ws-agent.yaml

@@ -8,10 +8,10 @@
 #   - Execute access to mxc-ws-agent.exe / openshell-supervisor-relay.exe and
 #     their runtime DLLs (provided by the AppContainer inheriting access to
 #     system paths and share_dir).
-#   - TCP socket binding on port 22000 (governed by pc_capabilities in the
-#     gateway TOML, not by filesystem policy here).
-#   - Private/loopback client access for openshell-supervisor-relay to dial
-#     the driver's on-demand relay — granted by pc_capabilities in the TOML.
+#   - Sandbox-local TCP on port 22000 so openshell-supervisor-relay can dial
+#     the wrapped target — granted by pc_allow_loopback in the gateway TOML.
+#     Private-network ingress and host-loopback access remain denied. Forwarding
+#     between the gateway and relay uses inherited stdin/stdout handles.
 #   - No writes to the host filesystem.
 #
 # workload directory (passed by run-ws-agent-test.ps1, default C:\work\openshell-mxc-ws)

crates/openshell-driver-mxc/examples/mxc-openclaw-gateway.toml

@@ -22,6 +22,8 @@ version = 2
 wxc_exec_path = "C:\\mxc-kit\\bin\\wxc-exec.exe"
 
 backend           = "process_container"
+# MXC derives effective network capabilities from its directional policy.
+# This capability alone does not permit sandbox-local loopback connections.
 pc_capabilities   = ["privateNetworkClientServer"]
 pc_least_privilege = false
 # UI capability is now a SandboxPolicy concern, not gateway TOML -- see

crates/openshell-driver-mxc/examples/mxc-ws-gateway.toml

@@ -23,7 +23,7 @@
 #
 # Connectivity: entirely on-demand via `openshell forward service
 # --target-port 22000` (ForwardSink::open_dynamic_forward / the control
-# channel's "forward" op) -- there is no static/always-on bridge and no
+# channel's "forward_open" op) -- there is no static/always-on bridge and no
 # port pre-declared in this config beyond pc_relay_target_port's own
 # startup liveness check.
 #
@@ -43,16 +43,16 @@ wxc_exec_path = "C:\\mxc\\wxc-exec.exe"
 # One-shot AppContainer backend: genuinely default-deny at the OS level.
 backend = "process_container"
 
-# AppContainer capability required for the server to bind a TCP socket on
-# 0.0.0.0:22000.  "privateNetworkClientServer" allows the sandbox to act as
-# both a client and a server on private (home/work/loopback) networks.
-pc_capabilities = ["privateNetworkClientServer"]
+# The workload needs sandbox-local TCP, not private/LAN or host-loopback access.
+# AppContainer capabilities alone do not override MXC directional network policy.
+pc_capabilities = []
+pc_allow_loopback = true
 
 # process_container only: keep standard privilege level (not LPA).
 pc_least_privilege = false
 
-# No governed Internet egress is needed. The relay reaches the driver's
-# on-demand private-interface listener through privateNetworkClientServer above.
+# No governed Internet egress is needed. The control channel carries forwarding
+# traffic through inherited handles; the relay dials the target on sandbox loopback.
 egress_proxy      = false
 egress_proxy_addr = ""
 

crates/openshell-driver-mxc/examples/run-ws-agent-test.ps1

@@ -268,7 +268,8 @@ function Register-Cli {
 function Wait-PortOpen([int]$port, [int]$seconds) {
     $deadline = (Get-Date).AddSeconds($seconds)
     while ((Get-Date) -lt $deadline) {
-        if (Get-NetTCPConnection -State Listen -LocalPort $port -ErrorAction SilentlyContinue) {
+        if (@([System.Net.NetworkInformation.IPGlobalProperties]::GetIPGlobalProperties().GetActiveTcpListeners() |
+            Where-Object { $_.Port -eq $port }).Count -gt 0) {
             return $true
         }
         Start-Sleep -Milliseconds 500
@@ -279,7 +280,8 @@ function Wait-PortOpen([int]$port, [int]$seconds) {
 function Wait-PortClosed([int]$port, [int]$seconds) {
     $deadline = (Get-Date).AddSeconds($seconds)
     while ((Get-Date) -lt $deadline) {
-        if (-not (Get-NetTCPConnection -State Listen -LocalPort $port -ErrorAction SilentlyContinue)) {
+        if (@([System.Net.NetworkInformation.IPGlobalProperties]::GetIPGlobalProperties().GetActiveTcpListeners() |
+            Where-Object { $_.Port -eq $port }).Count -eq 0) {
             return $true
         }
         Start-Sleep -Milliseconds 500
@@ -424,12 +426,10 @@ try {
         }
         Ok "wxc-exec: $WxcExecPath"
 
-        # A real run exercises process_container with egress_proxy disabled
-        # (mxc-ws-gateway.toml). The sandbox connects directly to the driver's
-        # route-selected private-interface relay listener through the
-        # privateNetworkClientServer capability; the governed host CONNECT
-        # proxy is not part of this qualification path. Elevation is not
-        # required here; keep logging the elevation state for diagnostics only.
+        # A real run exercises process_container with pc_allow_loopback enabled
+        # and egress_proxy disabled. The sandbox relay dials its local target;
+        # gateway traffic uses inherited handles without a host-network callback.
+        # Keep logging elevation state for diagnostics only.
         $wid   = [Security.Principal.WindowsIdentity]::GetCurrent()
         $wp    = New-Object Security.Principal.WindowsPrincipal($wid)
         $admin = $wp.IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)
@@ -612,6 +612,8 @@ try {
     if (-not $Mock) {
 
         Step "Wait for WebSocket server on port $WsPort"
+        # Host-to-sandbox loopback is denied. Observe the listener without
+        # connecting to it; the echo check below exercises the actual relay path.
         $serverUp = Wait-PortOpen -port $WsPort -seconds 30
         if ($serverUp) {
             Record "server-port-open" $true "port $WsPort is listening"
@@ -624,21 +626,12 @@ try {
             Record "server-port-open" $false $detail
         }
 
-        # Cross-check server-port-open against openshell-supervisor-relay's own
-        # confirmation, from inside the sandbox: it detects target-port
-        # readiness itself (wait_for_port_ready, gated by the "launch"
-        # handshake) and logs it, forwarded into the gateway log the same way
-        # as every other wxc-exec stdout/stderr line. No share_dir file
-        # needed -- this is the same information the marker file used to
-        # carry, just sourced from the spawner's own diagnostic instead.
+        # Cross-check the listener against the relay's acknowledgement of the
+        # driver's target_ready handshake. Readiness does not require the host
+        # to dial the sandbox's listener directly.
         if ($serverUp) {
             Step "Verify spawner's own port-ready confirmation (gateway log)"
-            # The spawner's own polling (wait_for_port_ready, 300ms interval)
-            # runs independently of this script's Wait-PortOpen above -- its
-            # log line can land a couple of seconds after the raw TCP connect
-            # already succeeded (observed up to ~2.3s). Poll for it rather
-            # than checking once immediately, or this races and fails spuriously.
-            $readyPattern = "port $WsPort ready after"
+            $readyPattern = "host confirmed target listener on port $WsPort"
             $readyDeadline = (Get-Date).AddSeconds(15)
             $readyOk = $false
             while ((Get-Date) -lt $readyDeadline -and -not $readyOk) {