feat(driver-mxc): native Windows MXC compute driver + server wiring by jamieknvidia · Pull Request #2721 · NVIDIA/OpenShell

jamieknvidia · 2026-08-12T18:26:15Z

Summary

Adds openshell-driver-mxc, a native-Windows compute driver backed by Microsoft Execution Containers (MXC / wxc-exec), and wires it into openshell-server behind ComputeDriverKind::Mxc. This lets OpenShell run governed agent sandboxes on Windows with filesystem and network policy enforcement, without touching the Linux container drivers. Builds on the Windows build-enablement foundation merged in #2496.

Related Issue

Part of RFC 0013 — Native Windows Support via MXC (merged in #2071). Stacks on the Windows build-enablement work in #2496. This is PR 1 (the driver) of the multi-PR native-Windows effort.

Changes

New crate openshell-driver-mxc: in-process implementation of the ComputeDriver gRPC contract over MXC / wxc-exec. Backends: process_container (default-deny AppContainer) and isolation_session.
Embedded policy mapper: translates SandboxPolicy → MXC grants (filesystem, network/egress, binary-scoped, network_middlewares) directly in the driver crate.
Server wiring: ComputeDriverKind::Mxc dispatch in openshell-server (Windows-gated), mxc_config_from_context config plumbing, and telemetry / CLI / config-validation arms.
Windows-only dependency: openshell-driver-mxc is pulled in under [target.'cfg(target_os = "windows")'.dependencies], complementary to the conditional Linux-driver exclusion from feat(gateway,cli): windows compilation support #2496.
Real-host test lane: probe-gated real-wxc-exec tests (no mocks) plus e2e policy fixtures.

Testing

Built x86_64-pc-windows-msvc (release, bundled-z3) and validated on a real Windows 11 host (7F203-MXC-001, build 26300.x):

Filesystem enforcement — DEMO PASS (process_container): in-policy write + read-back OK; out-of-policy write denied (PermissionDenied).
Network policy — PASS: disallowed egress → ProvisionFailed: policy (port/protocol/access/binary-scoped grant checks).
MXC crate unit tests: 75 passed / 0 failed / 9 ignored.
windows-msvc.ps1 check x86_64-pc-windows-msvc: PASS.
[] mise run pre-commit passes
Unit tests added/updated
E2E tests added/updated (if applicable)

Checklist

Follows Conventional Commits
Commits are signed off (DCO)
Architecture docs updated (if applicable) — covered by RFC 0013 (docs(rfc): add RFC 0013 native Windows support via MXC #2071)

copy-pr-bot · 2026-08-12T18:26:19Z

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

github-actions · 2026-08-12T18:26:32Z

All contributors have signed the DCO ✍️ ✅
_{Posted by the DCO Assistant Lite bot.}

pkhodade-NV · 2026-08-13T01:46:20Z

I have read the DCO document and I hereby sign the DCO.

drew

gator-agent

PR Review Status

Validation: Project-valid implementation of merged RFC 0013 and the native-Windows foundation in #2496.
Head SHA: 7beadcbaa26e4f08b854b58f2bfef526a02e8609
Base SHA: f24a5aee1390115fbdba7164f158d1491adcda28
Merge base SHA: dd2b4e3bc0688bdd59f90030f7c1d52511d6e354
Patch ID: 86ddd0be6113b95a1aa583c429c0e6360cb7084a
Gator payload: 4
Review mode: initial
Previous reviewed SHA: none
Review budget exhausted: no
Maintainer decision required: no

Blocking findings:

GATOR-7beadcba-01 (Critical): the implicit MXC backend is documented as unable to enforce default-deny filesystem policy.
GATOR-7beadcba-02 (Critical): share_dir silently adds a writable host path outside SandboxPolicy.
GATOR-7beadcba-03 (Critical): governed egress is configured without binding the trimmed policy to an enforcing proxy.
GATOR-7beadcba-04 (Critical): stop/delete can report success while execution or cleanup remains active, then discard cleanup identity.
GATOR-7beadcba-05 (Warning): piped child output is never drained and can deadlock sandbox completion.
GATOR-7beadcba-06 (Warning): joining agent_command loses Windows argv boundaries.
GATOR-7beadcba-07 (Warning): deterministic policy-mapping failures occur after CreateSandbox has already returned success.

Carried findings:

None.

Non-blocking suggestions:

None.

Docs: Missing required Fern documentation for the new user-facing MXC driver setup and [openshell.drivers.mxc] gateway configuration. Please update the relevant page under docs/ and docs/index.yml navigation if needed, or obtain a maintainer-authored explanation that published docs are intentionally unnecessary.

Next state: gator:in-review

drew · 2026-08-13T23:21:17Z

/ok to test 7beadcb

shailendra-nv · 2026-08-20T23:06:40Z

Conflict sync update

Merged current NVIDIA/main (ef296806) into this branch. GitHub now reports the PR as MERGEABLE; the remaining BLOCKED state is from required checks/review policy, not merge conflicts.

Conflict decisions and rationale:

Kept main's external compute-driver endpoint override behavior in the CLI. The endpoint map is now the canonical extension path, so reintroducing a reserved built-in-name rejection would make MXC behave differently from the other registered drivers.
Integrated MXC into main's compiled-driver registry as the Windows mxc factory. Docker, Podman, Kubernetes, and VM remain registered as explicit unsupported Windows factories, which preserves discoverability and produces deterministic platform errors instead of silently omitting known drivers.
Kept main's (runtime, operator_allowlist) server initialization contract while retaining the Windows MXC runtime. The operator allowlist is intentionally absent on native Windows because that Unix enforcement mechanism is not available there.
Preserved both sides of the documentation conflicts: main's current lifecycle/Kubernetes guidance and the MXC one-shot Windows behavior. This avoids losing either the new canonical main-process model or the driver-specific constraints.
Kept MXC StartSandbox explicitly unsupported because MXC currently executes one-shot workloads through CreateSandbox; pretending to support the long-lived lifecycle RPC would expose a capability the backend does not implement.
Updated the mock E2E expectations so filesystem read/write cases require an artifact, while default-deny requires the artifact to be absent. This makes the assertion match the policy outcome instead of treating a successful denial as a failure.

Validation on the exact merged tree (5ab33ac4):

ARM64: strict Rust lint passed; 3183 tests passed; release gateway and CLI built.
x64: 3183 tests passed; unsupported-driver contract 1/1; real MXC/WXC tests 9/9; mock E2E scenarios 4/4; release gateway and CLI built.
Full mise run pre-commit passed on x64, including formatting, Clippy with warnings denied, license, docs/Markdown, Python, protobuf, and TypeScript checks.

araza008 · 2026-08-23T19:56:39Z

I have read the DCO document and I hereby sign the DCO.

Introduces the openshell-driver-mxc crate implementing ComputeDriver backed by Microsoft MXC isolation sessions (Windows only). Wires the new driver into the server's build_compute_runtime dispatch and adds the Mxc variant to ComputeDriverKind. Also adds a local protobuf-src stub (tools/protobuf-src-local) to unblock Windows builds that lack MSYS2/MinGW, and pins the zig Windows x64 toolchain in mise.lock. (cherry picked from commit 4f70122) Signed-off-by: Jamie King <jamiek@nvidia.com>

…ing, demo artifacts) Safety checkpoint of uncommitted work from the background agent run that stalled mid-Step-7. Includes: mxc-driver-recon.md (Step 0.5), policy_map.rs (~876L embedded mapper), A1 policy-threading edits across driver.rs/policy.rs/mxc.rs/compute/mod.rs, and examples/ (demo.yaml + mxc-gateway.toml). Not yet verified to compile end-to-end; to be reorganized into the skill's Step 11 commit sequence. (cherry picked from commit 38e42c0) Signed-off-by: Jamie King <jamiek@nvidia.com>

- Bring futures::StreamExt into scope for the watch-stream `.next()` call in driver::lifecycle_tests so the negative policy proof test compiles. - Bind a local `mapper` and drop the unused/deprecated NetworkBinary in the embedded-mapper network-policy rejection test. Signed-off-by: Jamie King <jamiek@nvidia.com> (cherry picked from commit 039b0ba) Signed-off-by: Jamie King <jamiek@nvidia.com>

The gateway mints `sandbox_token` only when a sandbox-JWT issuer is configured. There is no in-sandbox supervisor on MXC (supervisor-removal design — D1/D4), so no component ever consumes the token; requiring it on the driver side blocks the demo's `--disable-tls` smoke gateway with a spurious `invalid_argument`. Log the absence and proceed instead. Signed-off-by: Jamie King <jamiek@nvidia.com> (cherry picked from commit cea2097) Signed-off-by: Jamie King <jamiek@nvidia.com>

monitor_exec demoted Ready->Error on exit 0 (reason ExecCompleted), so the positive demo (write hello.txt + exit) landed in Error phase. Keep Ready=True (reason AgentCompleted) on success; only non-zero exits go to ExecFailed. Tighten the positive lifecycle test to assert the terminal condition stays Ready=True/AgentCompleted. Verified live via gateway mock round-trip: phase now Provisioning->Ready with no demotion. (cherry picked from commit 54ab030) Signed-off-by: Jamie King <jamiek@nvidia.com>

Add a backend selector to the MXC driver (isolation_session default | process_container). process_container drives a one-shot AppContainer that is genuinely default-deny: a write to any ungranted path is denied by the OS, unlike isolation_session which is grant-only and cannot deny. The lifecycle forks on the flag - isolation_session keeps provision/start/exec, process_container runs a single ephemeral container via run_oneshot. Also: run-demo.ps1 gains -Backend and hardens the CLI register/create calls; docs corrected to state isolation_session does NOT deny out-of-policy writes and that the negative proof requires process_container. Verified end-to-end on a real demo box (gateway -> CLI -> driver -> MXC): in-policy write succeeds, out-of-policy write denied (PermissionDenied), OVERALL: PASS. (cherry picked from commit c6cde38) Signed-off-by: Jamie King <jamiek@nvidia.com>

…one crate Adopt the proto-based mapper (map_to_mxc) as the single source of truth, embedded in openshell-driver-mxc as a Windows-gated `policy_map` module. Rewire EmbeddedPolicyMapper to call it directly on the typed SandboxPolicy, deleting the serde_yaml proto->YAML bridge. Move the CLI to a windows-gated example and the parity tests into the crate; delete openshell-policy-mapper. - gate policy_map + seam Windows-only (MXC is Windows-only) - drop serde_yaml; add dev-deps openshell-policy, clap, anyhow - normalize mapped paths to Windows form in the seam, in one place - docs: add driver-mxc to AGENTS.md table; correct design doc section 17 test lane Signed-off-by: Giedrius Burachas <gburachas@nvidia.com> (cherry picked from commit f22f9c7) Signed-off-by: Jamie King <jamiek@nvidia.com>

… egress Signed-off-by: Giedrius Burachas <gburachas@nvidia.com> (cherry picked from commit 96d6afa) Signed-off-by: Jamie King <jamiek@nvidia.com>

…he policy seam - split_policy: SocketAddr proxy_redirect (replaces bare port), processcontainer containment guard naming MXC M1, version preserved in the trimmed proxy_policy, delegation reported as an info loss item - seam: MappedConfig carries trimmed_policy + proxy_addr; MapCtx.egress selects the split path; coarse path unchanged when egress is disabled - driver: [openshell.drivers.mxc] egress_proxy / egress_proxy_addr config, validated at create (isolation_session rejected until M1); lifecycle threads the redirect into provision and stores the trimmed policy per sandbox, emitting an EgressRedirect platform event - mxc: optional MxcNetwork block (defaultPolicy=block + proxy) in provision and one-shot configs; mock records configs for test assertions - tests: lossless-invariant suite over all example policies (validate + serialize round-trip), split lifecycle proof, M1 rejection; example gains --split --proxy-addr writing mxc-config.json / trimmed-policy.yaml / loss-report.json Signed-off-by: Giedrius Burachas <gburachas@nvidia.com> (cherry picked from commit 34d54ad) Signed-off-by: Jamie King <jamiek@nvidia.com>

Verified against the real wxc-exec 0.6.0-alpha via --dry-run: MXC accepts only the {localhost: N} proxy shape (the form the design doc specifies) and rejects {host, port} with a parse error. Schema 0.6.0-alpha can express only a loopback port, so non-127.0.0.1 redirect addresses are now rejected: split_policy emits an error loss (no proxy block) and the driver refuses egress_proxy_addr values off 127.0.0.1. Per-sandbox attribution must use per-sandbox ports until the schema widens. Signed-off-by: Giedrius Burachas <gburachas@nvidia.com> (cherry picked from commit edde8d5) Signed-off-by: Jamie King <jamiek@nvidia.com>

… variants Empirical contract finding from the real test lane (build 26300.8553, wxc-exec 2026-06-10): the stop and deprovision experimental blocks are unit variants in the wxc-exec schema and must serialize as null; sending {} is rejected with malformed_request (invalid type: map, expected unit), while provision/start accept maps. The production invoker, the real-lane test, the probe script, and the e2e runner all sent {} - the driver could provision and run an agent but never stop or delete an isolation-session sandbox against this build. Pinned by a unit test. Signed-off-by: Giedrius Burachas <gburachas@nvidia.com> (cherry picked from commit 0df39ca) Signed-off-by: Jamie King <jamiek@nvidia.com>

… guard Three-quadrant, table-driven matrix (38 tests): mappable fields assert exact MXC output; every OpenShell field MXC cannot express asserts a loss item with the expected severity (and seam rejection on error); an empty policy asserts the restrictive default-deny posture for every MXC knob OpenShell does not control. The handled_fields_inventory drift guard serializes a fully-populated policy and compares its YAML keys against the mapper-handled field lists, so a new openshell-policy field fails the suite until consciously mapped, delegated, or reported as loss. Re-exports the policy seam types for integration tests; adds serde_yml, base64, serde_json as dev-dependencies. Signed-off-by: Giedrius Burachas <gburachas@nvidia.com> (cherry picked from commit 91807f9) Signed-off-by: Jamie King <jamiek@nvidia.com>

Add MxcComputeConfig.agent_env: each entry is either KEY=VALUE (verbatim) or a bare KEY resolved from the gateway host environment at launch, keeping secrets (e.g. inference API keys) out of the config file. Wire it into the agent process so gateway-launched agents can authenticate to cloud endpoints (process.env was previously hardcoded empty). Unit-tested via resolve_agent_env_passthrough_and_host_lookup. Also add a gateway-driven cloud-inference (T1) test harness: mxc-inference.toml (agent_env + curl agent), inference.yaml policy, and run-inference-test.ps1 which starts the gateway, creates an isolation_session sandbox, runs an authenticated Nemotron call, and bundles redacted results. Documented agent_env in mxc-gateway.toml. Validated end-to-end on the test box (chat HTTP 200 + completion via the gateway). (cherry picked from commit 94d9e82) Signed-off-by: Jamie King <jamiek@nvidia.com>

Replace std::env::{set,remove}_var (unsafe + racy under parallel test execution in edition 2024) with a read-only PATH lookup. Preserves all three behaviors under test and drops the #[allow(unsafe_code)]. (cherry picked from commit ac5766e) Signed-off-by: Jamie King <jamiek@nvidia.com>

The MXC driver crate was authored on GitLab against an earlier proto/core API. Adapt it to the API on GitHub main: - build_capabilities_response no longer takes supports_interactive_session - DriverSandboxSpec.gpu (bool) is now resource_requirements; detect GPU via effective_driver_gpu_count(driver_gpu_requirements(..)) - DriverSandbox gained a `workspace` field - SandboxPolicy gained `network_middlewares`: pass it through the proxy split, emit a loss item on the coarse MXC path, and account for it in the mapper drift-guard test Verified: cargo check + 75 mock-based tests pass (lib 27, examples 10, policy_mapper_matrix 38). Signed-off-by: Jamie King <jamiek@nvidia.com>

Register openshell-driver-mxc as the Windows-only in-process compute backend so compute_driver = "mxc" resolves to a working runtime: - ComputeRuntime::new_mxc, adapted to the current 11-arg from_driver - mxc_policy_sink A1 side channel, staged in create_sandbox before dispatch - mxc_config_from_context loader and the Mxc dispatch arm (Windows constructs; other targets return an explicit "Windows-only" error) - Windows-gated openshell-driver-mxc dependency - Mxc arms for the telemetry, config-file required-fields, and CLI reserved-builtin matches to keep them exhaustive/correct Verified with cargo check --workspace --features openshell-prover/bundled-z3 on x86_64-pc-windows-msvc, stacked on PR NVIDIA#2496. Signed-off-by: Jamie King <jamiek@nvidia.com>

…2496 base Signed-off-by: Jamie King <jamiek@nvidia.com>

- tests/wxc_exec_real.rs: ignored-by-default integration tests against a real wxc-exec. Six --dry-run contract tests run wherever the binary exists (they caught the network.proxy shape mismatch); enforcement tests (processcontainer default-deny positive/negative, isolation session lifecycle round trip with a deprovision drop-guard) probe the backend and SKIP with a recorded reason where it is not live. - examples/probe-mxc-host.ps1: classifies a host (OS build, --probe, per-backend trial) and emits a JSON capability verdict. - examples/run-mxc-e2e.ps1 + e2e-policies/: scenario runner generalizing run-demo.ps1 (fs-rw, fs-readonly, fs-default-deny-empty, network-policy-rejected) with PASS/FAIL/SKIP gating and a stale OPENSHELL_MXC_MOCK_WXC guard in real mode. - tasks/windows.toml: windows:test:mxc-real:x64, windows:e2e:mxc, windows:e2e:mxc:mock. Signed-off-by: Giedrius Burachas <gburachas@nvidia.com> (cherry picked from commit 49afafe) Signed-off-by: Jamie King <jamiek@nvidia.com>

Signed-off-by: Shailendra Singh <shailendras@nvidia.com>

Signed-off-by: Drew Newberry <385+drew@users.noreply.github.com>

jamieknvidia requested review from a team, derekwaynecarr, maxamillion and mrunalp as code owners August 12, 2026 18:26