Skip to content

WINDOWS.md

Latest commit

 

History

History
113 lines (88 loc) · 5.35 KB

WINDOWS.md

File metadata and controls

113 lines (88 loc) · 5.35 KB
Raw

Native Windows support

The windows branch is the development and release branch for native Windows OpenShell. The Windows implementation stays on that branch. This guide and other shared documentation can also appear on main; their presence there does not move the Windows implementation or release source to main.

Native Windows uses Microsoft MXC ProcessContainer isolation on x64 and ARM64. It is separate from running Linux OpenShell inside WSL 2. Docker, Podman, Kubernetes, and MicroVM are not native Windows compute backends.

Runtime and current limits

The gateway links the MXC compute driver. It starts a trusted openshell-supervisor.exe on the host and an openshell-windows-sandbox.exe boundary inside each ProcessContainer. The pair uses the authenticated Sandbox Protocol for process operations and forwarding. The host supervisor applies network policy and endpoint-bound provider credentials through an authenticated explicit proxy. Workloads must support that proxy.

MXC maps filesystem and UI policy to native controls. This implementation is under development and is not a production-qualified security boundary:

  • Outer-fence guarantees are temporarily asserted for compatibility testing. Exclusive supervisor-mediated egress and live access revocation are unverified.
  • The loopback exception can expose unrelated host-local services to workloads. Treat the gateway host as trusted.
  • Foreground main-process attachment and ConPTY resize are unavailable. Create command workloads with --detach.
  • Gateway restart recovery for live MXC generations is not supported.

See the Windows branch's MXC driver documentation for the current capabilities and enforcement limits, and its boundary library documentation for the runtime architecture. Passing build or E2E checks does not establish the missing security guarantees.

Get the Windows source

Use a separate checkout so an existing main checkout can remain in place:

git clone --branch windows https://github.com/NVIDIA/OpenShell.git OpenShell-windows
Set-Location OpenShell-windows
mise trust

Base native Windows implementation changes on windows and target that branch for review. Documentation-only changes can also merge into main, while retaining explicit windows branch links for Windows code, tasks, and runtime instructions. The main installer and its dev, prerelease, and stable artifacts are not the native Windows distribution path.

Build

Use Windows with rustup, mise, Visual Studio C++ Build Tools, a Windows SDK, and host-compatible LLVM/libclang. Install the MSVC components for each target you build, including ARM64 tools and Spectre-mitigated libraries for ARM64. The Windows build skill lists the full prerequisites and environment overrides.

Run the build matching your target:

# x64
mise run --skip-tools windows:build:x64

# ARM64
mise run --skip-tools windows:build:arm64

The tasks produce openshell.exe, openshell-gateway.exe, openshell-supervisor.exe, and openshell-windows-sandbox.exe under target/<target-triple>/release/. Keep these binaries from the same build together with the matching libz3.dll staged by the build task. The target triples are x86_64-pc-windows-msvc and aarch64-pc-windows-msvc. CARGO_TARGET_DIR can override the output root.

The build uses pinned prebuilt Z3 by default. Compile and test hosts do not need a working MXC runtime; running native sandboxes does. These tasks do not install an MSI, register a Windows service, or publish a release.

Prepare and run MXC

Use MXC 1.0.0 and a host that passes the native ProcessContainer capability probe. Place wxc-exec.exe outside WindowsApps or an MSIX package directory and configure its absolute path.

& "C:\mxc\wxc-exec.exe" --probe

probes.baseContainerSupportsIngressHostLoopbackAllow must be true. A Windows version number alone does not establish runtime compatibility. Configure compute_driver = "mxc" and use the matching Windows gateway configuration and example gateway TOML. Command-based sandbox creation requires administrator opt-in with allow_driver_config = true, a workload command and working directory, and --detach. Use a sandbox policy to grant the required filesystem and network access.

Validate

Follow native Windows validation for native x64 or ARM64 lint, build, unit tests, and real MXC tests. Cross-building ARM64 on x64 does not run native ARM64 tests. Real MXC tests and E2E require a capable host; record probe-gated skips separately from passes.

The Windows CI guidance describes opt-in PR checks and branch builds. A successful compilation or an advisory CI run is not a Windows release qualification result.