|
| 1 | +# openshell-driver-mxc |
| 2 | + |
| 3 | +OpenShell compute driver backed by **Microsoft MXC** (`wxc-exec`) on Windows. |
| 4 | + |
| 5 | +## Design |
| 6 | + |
| 7 | +This driver implements the gateway's `ComputeDriver` gRPC contract as an |
| 8 | +**in-process library** linked into `openshell-gateway`. It drives MXC through |
| 9 | +the state-aware lifecycle (`provision` → `start` → `exec` → `stop` → |
| 10 | +`deprovision`), runs the agent **inside the driver** (exec-in-driver), and |
| 11 | +**self-reports readiness** — there is no in-sandbox supervisor, no host-side |
| 12 | +surrogate, and no `ConnectSupervisor` relay. See |
| 13 | +`docs/reference/mxc-compute-driver-design.mdx` for Shailendra's full |
| 14 | +architectural rationale (decisions D1–D4). |
| 15 | + |
| 16 | +## Capability Matrix (June 15 demo slice) |
| 17 | + |
| 18 | +| Capability | MXC driver | Closing it requires | |
| 19 | +|---|---|---| |
| 20 | +| Filesystem policy (read-write / read-only grants) | ✅ provision-time AppContainer shares | — | |
| 21 | +| Governed egress (CONNECT proxy + OPA + L7) | ❌ | `implement-openshell-mxc-egress-proxy` | |
| 22 | +| Network policy | ❌ `isolation_session` rejects network config | MXC feedback item M1 + egress skill | |
| 23 | +| Process policy (seccomp, uid/gid) | ❌ host-side governance design; OS isolation only | not pursued | |
| 24 | +| Interactive exec/connect/forward | ❌ exec runs in-driver, no client attach | `adapt-openshell-gateway-windows` | |
| 25 | +| Bundled agent image | ❌ no OCI image; relies on Windows host install | — | |
| 26 | +| Restart durability | ❌ in-memory registry; restart orphans live sessions | follow-on | |
| 27 | +| Concurrent sandboxes | ⚠️ isolation_session v1 is single-session | MXC backend feature | |
| 28 | + |
| 29 | +The June 15 demo proof point is **filesystem policy enforcement**: |
| 30 | +- **Positive**: write to the in-policy `share_dir` succeeds; `hello.txt` appears on the host. |
| 31 | +- **Negative**: write outside the policy fails with Windows access-denied; driver emits a |
| 32 | + `DriverPlatformEvent` denial and the exec exits non-zero. |
| 33 | + |
| 34 | +## Configuration (`[openshell.drivers.mxc]`) |
| 35 | + |
| 36 | +```toml |
| 37 | +[openshell.drivers.mxc] |
| 38 | +# Path to wxc-exec.exe (required for live runs) |
| 39 | +wxc_exec_path = "C:\\path\\to\\wxc-exec.exe" |
| 40 | +# MXC configurationId — never use "small" (known OS bug) |
| 41 | +default_configuration_id = "composable" |
| 42 | +# Agent command executed inside the sandbox |
| 43 | +agent_command = ["cmd", "/c", "echo hello > C:\\work\\demo\\hello.txt"] |
| 44 | +# Working directory for the agent (defaults to share_dir) |
| 45 | +agent_cwd = "C:\\work\\demo" |
| 46 | +# Host directory mapped read-write into the sandbox |
| 47 | +share_dir = "C:\\work\\demo" |
| 48 | +# Enable --debug on wxc-exec invocations |
| 49 | +debug = false |
| 50 | +``` |
| 51 | + |
| 52 | +Or via environment / CLI: |
| 53 | +``` |
| 54 | +OPENSHELL_DRIVERS=mxc openshell-gateway ... |
| 55 | +openshell-gateway --drivers mxc ... |
| 56 | +``` |
| 57 | + |
| 58 | +## Prerequisites (live runs) |
| 59 | + |
| 60 | +- Windows 11 Insider build ≥ 26300.8553 |
| 61 | +- `IsoSessionApp.dll` present and registered |
| 62 | +- `wxc-exec.exe` built with `--features isolation_session` |
| 63 | +- Giedrius's policy mapper crate wired as the primary `PolicyMapper` binding |
| 64 | + (until then the `StubPolicyMapper` grants only `share_dir` as read-write) |
| 65 | + |
| 66 | +## PolicyMapper seam |
| 67 | + |
| 68 | +Policy translation (`SandboxPolicy` → MXC `ContainerConfig`) is delegated to |
| 69 | +Giedrius's Rust mapper crate via the `policy::PolicyMapper` trait. Until that |
| 70 | +crate lands, `StubPolicyMapper` applies only the `share_dir` grant and rejects |
| 71 | +everything else. **No live agent runs** until the real mapper is wired. |
| 72 | + |
| 73 | +## Deferred work |
| 74 | + |
| 75 | +- **Interactive exec/connect/forward** → `adapt-openshell-gateway-windows` |
| 76 | +- **Governed egress / network policy** → `implement-openshell-mxc-egress-proxy` |
| 77 | +- **Restart durability** (deprovision orphaned sessions on startup) → follow-on |
| 78 | +- **GPU passthrough** → not pursued in host-side-governance design |
0 commit comments