From 353e3e774d6034624356420a18e60b9181ad24a3 Mon Sep 17 00:00:00 2001 From: Shailendra Singh Date: Tue, 20 Oct 2026 10:29:01 -0700 Subject: [PATCH] docs(windows): document the Windows implementation and release branch Signed-off-by: Shailendra Singh --- .../build-openshell-mxc-windows/SKILL.md | 23 ++-- .../build-openshell-mxc-windows/reference.md | 5 +- .agents/skills/sync-agent-infra/SKILL.md | 1 + AGENTS.md | 11 +- CI.md | 20 +++- CONTRIBUTING.md | 27 ++++- README.md | 8 +- SECURITY.md | 11 ++ STYLEGUIDE.md | 6 + TESTING.md | 44 +++++++ WINDOWS.md | 113 ++++++++++++++++++ crates/openshell-driver-mxc/README.md | 8 +- docs/CONTRIBUTING.mdx | 7 ++ docs/about/architecture.mdx | 9 ++ docs/about/installation.mdx | 8 ++ docs/about/support-matrix.mdx | 15 +++ docs/how-it-works/gateways/configuration.mdx | 11 +- docs/how-it-works/sandboxes/runtimes.mdx | 8 +- 18 files changed, 311 insertions(+), 24 deletions(-) create mode 100644 WINDOWS.md diff --git a/.agents/skills/build-openshell-mxc-windows/SKILL.md b/.agents/skills/build-openshell-mxc-windows/SKILL.md index adc000b762..7ac11e16c6 100644 --- a/.agents/skills/build-openshell-mxc-windows/SKILL.md +++ b/.agents/skills/build-openshell-mxc-windows/SKILL.md @@ -8,9 +8,16 @@ metadata: # Build OpenShell-MXC for Windows This skill maintains the existing native Windows MSVC build lane in the -OpenShell repository. The Windows lane is already present in `main`; do not -treat this skill as a first-time porting recipe unless the user explicitly asks -for a new fork or a from-scratch bring-up. +OpenShell repository's [`windows` branch](https://github.com/NVIDIA/OpenShell/tree/windows). +That branch owns native Windows implementation and releases. Shared docs may +also appear on `main`; always direct Windows work to `windows` and use explicit +Windows branch links for implementation details. See +[Native Windows support](https://github.com/NVIDIA/OpenShell/blob/windows/WINDOWS.md). + +Before running the tasks below, use a `windows`-based checkout and read the +[skill from that branch](https://github.com/NVIDIA/OpenShell/blob/windows/.agents/skills/build-openshell-mxc-windows/SKILL.md). +The task and runtime descriptions refer to that checkout, not to any older +Windows source snapshot retained on `main`. The lane validates that OpenShell can compile and test on Windows MSVC for the supported deliverables: @@ -107,7 +114,7 @@ did not request. In scope: -- Refreshing a local checkout to the latest upstream GitHub `main`. +- Refreshing a Windows checkout to the latest upstream GitHub `windows`. - Maintaining `tasks/windows.toml` and `tasks/scripts/windows-msvc.ps1`. - Running x64 and ARM64 MSVC checks. - Building x64 and ARM64 release binaries for `openshell-gateway`, `openshell`, @@ -153,10 +160,10 @@ From a fork checkout where `upstream` points to the official `NVIDIA/OpenShell` GitHub repository, use: ```powershell -git fetch upstream main -git switch main -git merge --ff-only upstream/main -git branch --set-upstream-to=upstream/main main +git fetch upstream windows +git switch windows +git merge --ff-only upstream/windows +git branch --set-upstream-to=upstream/windows windows git status --short --branch ``` diff --git a/.agents/skills/build-openshell-mxc-windows/reference.md b/.agents/skills/build-openshell-mxc-windows/reference.md index 179eaef086..3834418a36 100644 --- a/.agents/skills/build-openshell-mxc-windows/reference.md +++ b/.agents/skills/build-openshell-mxc-windows/reference.md @@ -1,7 +1,10 @@ # Reference: Windows MSVC maintenance lane Companion to [SKILL.md](SKILL.md). Use this file for quick lookup while -maintaining the native Windows MSVC and MXC runtime lane. +maintaining the native Windows MSVC and MXC runtime lane on the +[`windows` development and release branch](https://github.com/NVIDIA/OpenShell/tree/windows). +Run the commands below from that branch or a branch based on it, including +when reading this reference on `main`. ## Lane Files diff --git a/.agents/skills/sync-agent-infra/SKILL.md b/.agents/skills/sync-agent-infra/SKILL.md index 8a07921e62..4a9abca6ef 100644 --- a/.agents/skills/sync-agent-infra/SKILL.md +++ b/.agents/skills/sync-agent-infra/SKILL.md @@ -28,6 +28,7 @@ Run after adding, removing, or renaming a skill or crate; changing issue or PR c | TUI behavior | `tui-development` | | Release artifacts or smoke coverage | `test-release-canary` | | CI diagnostics | `watch-github-actions` | +| Native Windows builds, runtime, or release branch guidance | `build-openshell-mxc-windows`; keep Windows implementation links on `windows` even in docs merged to `main` | | Gator supervision | `launch-openshell-gator` | | SBOM workflow | `sbom` | | RFC workflow | `create-rfc` | diff --git a/AGENTS.md b/AGENTS.md index 9f202bf862..2100178999 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -10,6 +10,13 @@ OpenShell is built agent-first. We design systems and use agents to implement th ## Skills +Native Windows implementation and releases belong to the +[`windows` branch](https://github.com/NVIDIA/OpenShell/tree/windows). +See [WINDOWS.md](WINDOWS.md) before Windows work. Base native Windows code +changes on that branch. Shared documentation may merge into `main`; keep links +to Windows-only implementation, tasks, and runtime guidance explicitly pinned +to `windows`, and do not imply that documentation on `main` ships Windows support. + OpenShell has two skill collections: - `skills/` contains public, installable skills for using and operating OpenShell. These skills must work outside a source checkout and use installed CLI help plus published documentation as their sources of truth. @@ -25,7 +32,7 @@ Do not rely on this file for a full inventory. The detailed public and contribut | `crates/openshell-conformance/` | CLI conformance library | Reusable driver-agnostic scenarios and command runner | | `crates/openshell-server/` | Gateway server | Control-plane API, sandbox lifecycle, auth boundary | | `crates/openshell-sandbox/` | Sandbox runtime | Capability-free workload launcher, process identity, and seccomp-mediated I/O | -| `crates/openshell-mxc-boundary/` | Windows sandbox boundary | Windows boundary library and dedicated openshell-windows-sandbox binary for MXC process operations, containment confirmation, and shared-protocol forwarding | +| [`crates/openshell-mxc-boundary/`](https://github.com/NVIDIA/OpenShell/tree/windows/crates/openshell-mxc-boundary) (`windows` branch) | Windows sandbox boundary | Windows boundary library and dedicated openshell-windows-sandbox binary for MXC process operations, containment confirmation, and shared-protocol forwarding | | `crates/openshell-supervisor/` | Supervisor runtime | Gateway session, policy evaluation, credentials, and upstream networking | | `crates/openshell-binary-identity/` | Binary identity | Shared trusted procfs executable identity resolution for isolation backends | | `crates/openshell-isolation-interface/` | Isolation backend interface | RFC 0012 `IsolationBackend` trait and types; the supervisor-facing runtime contract | @@ -50,7 +57,7 @@ Do not rely on this file for a full inventory. The detailed public and contribut | `crates/openshell-driver-docker/` | Docker compute driver | In-process `ComputeDriver` backend for local Docker sandbox containers | | `crates/openshell-driver-podman/` | Podman compute driver | In-process `ComputeDriver` backend for local Podman sandbox containers | | `crates/openshell-driver-vm/` | VM compute driver | Standalone libkrun-backed `ComputeDriver` subprocess (embeds its own rootfs + runtime) | -| `crates/openshell-driver-mxc/` | Microsoft MXC compute driver | In-process Windows ProcessContainer backend that pairs a host isolation-backend supervisor with `openshell-windows-sandbox` inside MXC | +| [`crates/openshell-driver-mxc/`](https://github.com/NVIDIA/OpenShell/tree/windows/crates/openshell-driver-mxc) (`windows` branch) | Microsoft MXC compute driver | In-process Windows ProcessContainer backend that pairs a host isolation-backend supervisor with `openshell-windows-sandbox` inside MXC | | `crates/openshell-prover/` | Policy prover | Policy verification and proof generation | | `crates/openshell-prover-cli/` | Policy prover CLI | Standalone local policy boundary checks | | `crates/openshell-server-macros/` | Server macros | Compile-time helpers for gateway RPC authorization | diff --git a/CI.md b/CI.md index fc9547720f..8f039d34f9 100644 --- a/CI.md +++ b/CI.md @@ -66,11 +66,25 @@ For an intentional minor-train incompatibility, record the Buf finding, linked issue, consumer impact, and migration plan in the PR. Keep the finding visible; do not disable the job or add a broad Buf ignore rule. -Windows PR checks are opt-in: add `test:windows`, then select **Re-run all jobs** +### Windows validation + +Native Windows implementation and releases use the +[`windows` branch](https://github.com/NVIDIA/OpenShell/tree/windows), independently +of the `main` release train described in this document. Shared documentation on +`main` must retain that branch placement. See [WINDOWS.md](WINDOWS.md) for the +native MSVC build and MXC runtime requirements. + +The [Windows MSVC workflow on `windows`](https://github.com/NVIDIA/OpenShell/blob/windows/.github/workflows/windows-msvc.yml) +runs native x64 and ARM64 lanes. Windows PR checks are opt-in: add +`test:windows`, then select **Re-run all jobs** on the current Windows MSVC run. Subsequent mirrored commits run them automatically. Windows checks are not required for merging and do not run in merge queues. -Main and manual runs also build release binaries, with `continue-on-error: true` -so Windows failures do not fail the workflow. +Pushes to `windows` and manual runs on that branch seed the lint/test caches and run dependent +release binary builds. Those jobs use `continue-on-error: true`, so inspect +their individual results rather than treating a green workflow as qualification. +The jobs do not upload or publish the binaries. Native Windows packages are +not supplied through the `main` installer or release train. Real MXC runtime qualification requires a +capable host and the [Windows runtime tests](https://github.com/NVIDIA/OpenShell/blob/windows/TESTING.md#native-windows-validation). ### Advisory compatibility review diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1b0b17c8fd..15402ccffd 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -112,7 +112,7 @@ Contributor and maintainer skills live in `.agents/skills/`. They are marked int | Triage | `triage-issue` | Assess, classify, and route community-filed issues | | Platform | `helm-dev-environment` | Start and manage the local Kubernetes development environment | | Platform | `tui-development` | Development guide for the ratatui-based terminal UI | -| Platform | `build-openshell-mxc-windows` | Maintain and validate the x64 and ARM64 Windows MSVC and MXC runtime lane | +| Platform | `build-openshell-mxc-windows` | Maintain and validate native x64 and ARM64 MSVC builds and MXC runtime on the `windows` branch | | Documentation | `update-docs-from-commits` | Scan recent commits and draft doc updates for user-facing changes | | Maintenance | `sync-agent-infra` | Detect and fix drift across agent-first infrastructure files | | Reference | `sbom` | Generate SBOMs and resolve dependency licenses | @@ -139,6 +139,12 @@ When recording a triage outcome, replace the previous assessment state rather th ## Prerequisites +Native Windows development uses the [`windows` branch](https://github.com/NVIDIA/OpenShell/tree/windows). +Follow [Native Windows support](WINDOWS.md) for checkout, MSVC prerequisites, +runtime requirements, and limitations. Target Windows implementation PRs at +`windows`. Shared documentation can merge into `main`, but Windows-specific +source and task links must continue to point to `windows`. + Install [mise](https://mise.jdx.dev/). This is used to set up the development environment. ```bash @@ -161,7 +167,7 @@ echo '~/.local/bin/mise activate fish | source' >> ~/.config/fish/config.fish echo 'eval "$(~/.local/bin/mise activate zsh)"' >> ~/.zshrc ``` -Project requirements: +Linux/macOS development requirements: - Rust 1.94+ - Python 3.11+ @@ -200,7 +206,7 @@ cargo build -p openshell-prover-cli --features vendored-z3 Local gateway image and E2E builds enable `vendored-z3` so their copied gateway binaries do not need a shared Z3 library in the runtime image. -For x86-64 and ARM64 Windows MSVC builds, use one of these Z3 paths: +For x86-64 and ARM64 Windows MSVC builds from the `windows` branch, use one of these Z3 paths: - Prebuilt Z3 (the default for `windows:*` tasks): `z3-sys` downloads the pinned Z3 5.1.0 GitHub release for the target architecture on the first @@ -223,8 +229,10 @@ cargo build -p openshell-prover --target x86_64-pc-windows-msvc --features prebu ### Windows full build -To build the full set of Windows binaries, including `openshell-gateway.exe` -and `openshell.exe`, use the `windows:build:x64` mise task instead of a +Run these commands in a `windows`-based checkout. To build the full set of +Windows binaries, including `openshell-gateway.exe`, `openshell.exe`, +`openshell-supervisor.exe`, and `openshell-windows-sandbox.exe`, +use the `windows:build:x64` mise task instead of a single-crate `cargo build`. It downloads the pinned prebuilt Z3 release by default. A full build also compiles crates that use `bindgen` (e.g. the MXC driver on Windows), so it requires `libclang.dll`; if LLVM is not on the default search @@ -235,6 +243,12 @@ $env:LIBCLANG_PATH='C:\Program Files\Microsoft Visual Studio\2022\\VC\T mise run --skip-tools windows:build:x64 ``` +For ARM64, use `windows:build:arm64` with ARM64 MSVC components and host-native +LLVM. Keep the matching `libz3.dll` staged by the build beside the executables. +See [Windows validation](https://github.com/NVIDIA/OpenShell/blob/windows/TESTING.md#native-windows-validation) +for native tests and MXC E2E requirements. Docker is not required for the native +Windows build or MXC runtime. + To use a local x64 Z3 release instead of the prebuilt download, set `Z3_LIBRARY_PATH_OVERRIDE` and `Z3_SYS_Z3_HEADER` before running the task: @@ -254,6 +268,9 @@ xcode-select --install ## Getting Started +The gateway and shell shortcuts below describe Linux/macOS development. +For native Windows, use the [Windows build and runtime instructions](WINDOWS.md). + ```bash # One-time trust mise trust diff --git a/README.md b/README.md index 43f887bb95..eb8596cecb 100644 --- a/README.md +++ b/README.md @@ -27,9 +27,14 @@ OpenShell governs what agents can do in two ways: it instruments the kernel to e See [Architecture](https://docs.nvidia.com/openshell/latest/about/architecture) for how the gateway, supervisor, and sandbox fit together. +Native Windows has a separate MXC implementation on the +[`windows` development and release branch](https://github.com/NVIDIA/OpenShell/tree/windows). +See [Native Windows support](WINDOWS.md) for its runtime architecture and current +enforcement limitations; the guarantees above do not establish Windows parity. + ## Quickstart -You need Linux, macOS on Apple Silicon, or Windows with WSL 2 (experimental), plus Docker, Podman, or host virtualization. See the [Support Matrix](https://docs.nvidia.com/openshell/latest/about/support-matrix) for details. +The quickstart below supports Linux and macOS on Apple Silicon, with experimental Linux use inside WSL 2. It requires Docker, Podman, or host virtualization. For native Windows x64 or ARM64, follow [Native Windows support](WINDOWS.md) and build from the [`windows` branch](https://github.com/NVIDIA/OpenShell/tree/windows). Native Windows uses MXC and does not use the installer below. See the [Support Matrix](https://docs.nvidia.com/openshell/latest/about/support-matrix) for details. ```shell curl -LsSf https://raw.githubusercontent.com/NVIDIA/OpenShell/main/install.sh | sh @@ -48,6 +53,7 @@ The installer sets up the CLI and a local gateway. The default sandbox image is - [Extensibility](https://docs.nvidia.com/openshell/latest/extensibility/overview): middleware, interceptors, and compute drivers. - [Tutorials](https://docs.nvidia.com/openshell/latest/tutorials/first-network-policy): step-by-step policy and agent walkthroughs. - [Prerelease and development builds](https://docs.nvidia.com/openshell/latest/about/installation#prerelease-and-development-builds): try an upcoming release or the latest commit on `main`. +- [Native Windows support](WINDOWS.md): build, run, and validate the MXC implementation maintained and released from `windows`, even when this documentation is read on `main`. ### Test the gRPC API with grpcurl diff --git a/SECURITY.md b/SECURITY.md index 76ba2ce72d..6099ed4122 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -20,6 +20,17 @@ To report a potential security vulnerability in any NVIDIA product: While NVIDIA currently does not have a bug bounty program, we do offer acknowledgement when an externally reported security issue is addressed under our coordinated vulnerability disclosure policy. Please visit our [Product Security Incident Response Team (PSIRT)](https://www.nvidia.com/en-us/security/psirt-policies/) policies page for more information. +## Native Windows reports + +Native Windows OpenShell is maintained on the +[`windows` branch](https://github.com/NVIDIA/OpenShell/tree/windows). +Use the same private disclosure process above for Windows findings. Include +the Windows branch commit, OS architecture and build, MXC version and probe +results, and relevant redacted configuration. See +[Native Windows support](WINDOWS.md#runtime-and-current-limits) for known +enforcement limitations; documentation appearing on `main` does not qualify +the Windows runtime for production. + ## NVIDIA Product Security For all security-related concerns, please visit NVIDIA's Product Security portal at https://www.nvidia.com/en-us/security diff --git a/STYLEGUIDE.md b/STYLEGUIDE.md index e7178f4555..0258b091ab 100644 --- a/STYLEGUIDE.md +++ b/STYLEGUIDE.md @@ -25,6 +25,12 @@ mise run lint mise run ci ``` +For native Windows changes, use a `windows`-based checkout and the +[Windows validation commands](https://github.com/NVIDIA/OpenShell/blob/windows/TESTING.md#native-windows-validation) +with the MSVC toolchain. Windows-specific documentation must link to the +[`windows` implementation and release branch](https://github.com/NVIDIA/OpenShell/tree/windows), +including when the document is published on `main`. See [WINDOWS.md](WINDOWS.md). + ## CLI Output Style When printing structured CLI output: diff --git a/TESTING.md b/TESTING.md index 316cbbbfa0..f5232db53b 100644 --- a/TESTING.md +++ b/TESTING.md @@ -2,6 +2,12 @@ ## Running Tests +The general E2E commands below use Linux sandbox runtimes. For native Windows, +use a [`windows` branch](https://github.com/NVIDIA/OpenShell/tree/windows) +checkout and the [native Windows validation](#native-windows-validation) lane. +Windows implementation and releases remain on that branch when this testing +guide is also published on `main`. + ```bash mise run test # Rust + Python unit tests mise run e2e # End-to-end tests (starts a Docker-backed gateway) @@ -72,6 +78,44 @@ task skips them. Run them on an idle machine with ### Native Windows validation +Start with the [Windows build prerequisites](WINDOWS.md#build) in a checkout +based on `windows`. Run the lane matching the native host: + +```powershell +# Native x64 host +mise run --skip-tools windows:lint:x64 +mise run --skip-tools windows:build:x64 +mise run --skip-tools windows:test:x64 +mise run --skip-tools windows:test:unsupported:x64 + +# Native ARM64 host +mise run --skip-tools windows:lint:arm64 +mise run --skip-tools windows:build:arm64 +mise run --skip-tools windows:test:arm64 +mise run --skip-tools windows:test:unsupported:arm64 +``` + +The test tasks use the CI nextest profile and server test support. They reject +a target that does not match the host architecture. `windows:ci` is the x64-host +aggregate, including ARM64 cross-check/build unless explicitly skipped; it +does not establish native ARM64 test coverage. + +For runtime validation, provision a capable MXC host and build its native +release binaries first. On x64, run: + +```powershell +mise run --skip-tools windows:test:mxc-real:x64 +mise run --skip-tools windows:e2e:mxc +``` + +Use `windows:test:mxc-real:arm64` on ARM64. The real-runtime unit tests can +report `SKIP` when the executor or backend is absent; E2E returns nonzero +when required runtime coverage is missing. Report passed, failed, and +skipped/ignored executions separately, including why any probe gated coverage. +Passing E2E does not qualify the [known Windows enforcement gaps](WINDOWS.md#runtime-and-current-limits). +See the [Windows test task definitions](https://github.com/NVIDIA/OpenShell/blob/windows/tasks/windows.toml) +for boundary, loopback, network, and audit suites. + Use `mise run --skip-tools pre-commit` with the existing Rust/MSVC toolchain. Windows now checks tracked Cargo lockfiles through PowerShell rather than skipping them. diff --git a/WINDOWS.md b/WINDOWS.md new file mode 100644 index 0000000000..0048414578 --- /dev/null +++ b/WINDOWS.md @@ -0,0 +1,113 @@ +# Native Windows support + +The [`windows` branch](https://github.com/NVIDIA/OpenShell/tree/windows) 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](https://github.com/NVIDIA/OpenShell/blob/windows/crates/openshell-driver-mxc/README.md) +for the current capabilities and enforcement limits, and its +[boundary library documentation](https://github.com/NVIDIA/OpenShell/blob/windows/crates/openshell-mxc-boundary/README.md) +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: + +```powershell +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](https://github.com/NVIDIA/OpenShell/blob/windows/.agents/skills/build-openshell-mxc-windows/SKILL.md) +lists the full prerequisites and environment overrides. + +Run the build matching your target: + +```powershell +# 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//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. + +```powershell +& "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](https://github.com/NVIDIA/OpenShell/blob/windows/docs/how-it-works/gateways/configuration.mdx#configure-mxc) +and [example gateway TOML](https://github.com/NVIDIA/OpenShell/blob/windows/crates/openshell-driver-mxc/examples/mxc-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](https://github.com/NVIDIA/OpenShell/blob/windows/TESTING.md#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](https://github.com/NVIDIA/OpenShell/blob/windows/CI.md#windows-validation) +describes opt-in PR checks and branch builds. A successful compilation or an +advisory CI run is not a Windows release qualification result. diff --git a/crates/openshell-driver-mxc/README.md b/crates/openshell-driver-mxc/README.md index da460acaa2..d0d7b9e4d4 100644 --- a/crates/openshell-driver-mxc/README.md +++ b/crates/openshell-driver-mxc/README.md @@ -1,5 +1,11 @@ # openshell-driver-mxc +Native Windows implementation and releases stay on the +[`windows` branch](https://github.com/NVIDIA/OpenShell/tree/windows). +Start with the [Windows guide](https://github.com/NVIDIA/OpenShell/blob/windows/WINDOWS.md) +for checkout and build instructions, including when this README is linked +from documentation on `main`. + The Windows-only MXC compute driver runs each workload in a Microsoft MXC ProcessContainer while preserving OpenShell's standard RFC 0012 runtime split: @@ -133,7 +139,7 @@ Supply the workload command and working directory per sandbox: ```powershell $config = '{"mxc":{"command":["C:\\Windows\\System32\\cmd.exe","/d","/c","echo hello"],"cwd":"C:\\work"}}' openshell sandbox create --name mxc-demo --policy policy.yaml ` - --driver-config-json $config --no-tty + --driver-config-json $config --no-tty --detach ``` The command and working directory are required. The working directory contains diff --git a/docs/CONTRIBUTING.mdx b/docs/CONTRIBUTING.mdx index bd3e66350f..232316e67b 100644 --- a/docs/CONTRIBUTING.mdx +++ b/docs/CONTRIBUTING.mdx @@ -8,6 +8,13 @@ This guide covers how to write, edit, and review documentation for NVIDIA OpenSh The published docs live in `docs/`, navigation is defined in `docs/index.yml`, and `fern/` contains the site config, components, and theme assets. +Native Windows implementation and releases remain on the +[`windows` branch](https://github.com/NVIDIA/OpenShell/tree/windows). +Shared documentation can also publish from `main`. Link Windows-only source, +tasks, and runtime instructions explicitly to `blob/windows/` or `tree/windows/` +so those links remain valid from either branch. Do not describe `main` release +artifacts or `install.sh` as the native Windows distribution path. + ## Use the Agent Skills If you use an AI coding agent (Cursor, Claude Code, Codex, etc.), the repo includes skills that automate doc work. Use them before writing from scratch. diff --git a/docs/about/architecture.mdx b/docs/about/architecture.mdx index 5862988396..d50636f6fd 100644 --- a/docs/about/architecture.mdx +++ b/docs/about/architecture.mdx @@ -8,6 +8,15 @@ keywords: "Generative AI, Cybersecurity, AI Agents, Architecture, Gateway, Sandb position: 2 --- +Native Windows has a separate implementation on the +[`windows` development and release branch](https://github.com/NVIDIA/OpenShell/tree/windows). +It pairs a host supervisor with an MXC ProcessContainer boundary. See the +[Windows architecture and limitations](https://github.com/NVIDIA/OpenShell/blob/windows/WINDOWS.md#runtime-and-current-limits) +before applying the guarantees below to that implementation. Exclusive +supervisor-mediated egress and live access revocation are not yet verified +for MXC. These Windows links remain on `windows` when this page is published +from `main`. + ![OpenShell system architecture showing a trusted supervisor separated from a network-isolated sandbox workload. The workload can connect only to the supervisor.](../images/openshell-system-architecture.svg) OpenShell governs what agents can do in two ways: it instruments the kernel to enforce policy on every file access, system call, and network connection at runtime, and it uses formal verification to check what a policy change would allow before it is applied. diff --git a/docs/about/installation.mdx b/docs/about/installation.mdx index 2a2057ddb6..110bef13d6 100644 --- a/docs/about/installation.mdx +++ b/docs/about/installation.mdx @@ -10,6 +10,14 @@ position: 3 Install OpenShell on a local workstation or Kubernetes. +For native Windows x64 or ARM64, use the +[`windows` development and release branch](https://github.com/NVIDIA/OpenShell/tree/windows) +and its [Windows build and runtime guide](https://github.com/NVIDIA/OpenShell/blob/windows/WINDOWS.md). +That implementation uses Microsoft MXC and remains on `windows` even when this +documentation is published from `main`. The installer and release channels +below cover Linux/macOS, including experimental Linux use inside WSL 2; +they do not install native Windows binaries. + ## Install OpenShell Install the CLI, policy prover, and a local gateway with one command: diff --git a/docs/about/support-matrix.mdx b/docs/about/support-matrix.mdx index 25546e0302..0848818b3b 100644 --- a/docs/about/support-matrix.mdx +++ b/docs/about/support-matrix.mdx @@ -10,6 +10,11 @@ This page lists the host platform, compute driver, software, runtime, and kernel ## Releases +Native Windows MXC implementation and releases are maintained separately on +the [`windows` branch](https://github.com/NVIDIA/OpenShell/tree/windows). +The release train below describes `main`; publishing Windows documentation +alongside it does not include native Windows in that release qualification. + OpenShell publishes dev, pre-release, and stable builds for different stages of the release cycle. Use a stable release for production deployments. @@ -54,6 +59,16 @@ OpenShell publishes multi-architecture gateway images for `linux/amd64` and `lin | Linux (Debian/Ubuntu) | aarch64 (arm64) | Supported | | macOS (Docker Desktop) | Apple Silicon (arm64) | Supported | | Windows (WSL 2 + Docker Desktop) | x86_64 | Experimental | +| Native Windows (MXC, `windows` branch) | x86_64 and ARM64 | Development; not production-qualified | + +Native Windows uses MXC ProcessContainer isolation rather than the Linux +runtime under WSL 2. Build from `windows` and follow its +[Windows guide](https://github.com/NVIDIA/OpenShell/blob/windows/WINDOWS.md) +for MSVC prerequisites, MXC host probing, artifacts, and current limitations. +Exclusive supervisor-mediated egress and live access revocation remain +unverified; the loopback exception can expose other host-local services. +The Linux/macOS release assets listed below do not supply the native Windows +runtime pair. On Linux, the `openshell` CLI is a static musl binary and does not require glibc at runtime. diff --git a/docs/how-it-works/gateways/configuration.mdx b/docs/how-it-works/gateways/configuration.mdx index 332588bfa6..9f173775c0 100644 --- a/docs/how-it-works/gateways/configuration.mdx +++ b/docs/how-it-works/gateways/configuration.mdx @@ -1237,6 +1237,13 @@ runtime-selected profile. ### MXC +Native Windows implementation and releases remain on the +[`windows` branch](https://github.com/NVIDIA/OpenShell/tree/windows). +Use a build from that branch for this section, including when reading it in +documentation published from `main`. See the +[Windows guide](https://github.com/NVIDIA/OpenShell/blob/windows/WINDOWS.md) +for build prerequisites and runtime limitations. + The MXC driver is Windows-only and opt-in. It links into the gateway and invokes Microsoft MXC through `wxc-exec.exe`. The driver starts `openshell-supervisor --role=isolation-backend` on the host and `openshell-windows-sandbox.exe` inside each ProcessContainer. The standard authenticated Sandbox Protocol and supervisor session provide lifecycle, exec, forwarding, provider refresh, and network policy. MXC does not support foreground attachment to the main process. Use `--detach` @@ -1246,7 +1253,7 @@ The dedicated `openshell-windows-sandbox.exe` uses a Windows boundary library fo The Windows sandbox initiates its authenticated control connection to a generation-scoped loopback listener in the host isolation backend. This follows the Windows relay's connection direction without changing host firewall rules. TLS identity verification and supervisor bearer authentication remain required. -This development branch temporarily asserts MXC outer-fence guarantees for Windows-branch compatibility testing. These assertions do not establish supervisor-only egress or verified live revocation. Workloads can bypass the proxy to reach other host-local services. Do not use this compatibility path as a production-qualified security boundary; passing E2E does not close these known gaps. +The `windows` branch implementation temporarily asserts MXC outer-fence guarantees for compatibility testing. These assertions do not establish supervisor-only egress or verified live revocation. Workloads can bypass the proxy to reach other host-local services. Do not use this compatibility path as a production-qualified security boundary; passing E2E does not close these known gaps. #### Prepare the Windows host @@ -1330,7 +1337,7 @@ to change UI settings. MXC advertises `openshell.policy.ui.v1` in its existing extension capabilities. The gateway rejects explicit UI policy, including `ui: {}`, when the selected driver does not advertise that capability. -The driver assigns distinct Sandbox Protocol and proxy listeners plus fresh credentials to every generation. The host proxy rejects missing, invalid, duplicate, or cross-sandbox proxy credentials before forwarding. MXC denies direct Internet egress and permits only the `127.0.0.1/32` route required by the authenticated transport and proxy. That loopback exception does not isolate unrelated host services. The current explicit-proxy path attributes descendant traffic to the admitted main workload binary rather than resolving each Windows socket owner. Treat the gateway host as trusted and avoid policies that rely on different network rights for child executables. +The driver assigns distinct Sandbox Protocol and proxy listeners plus fresh credentials to every generation. The host proxy rejects missing, invalid, duplicate, or cross-sandbox proxy credentials before forwarding. MXC denies direct Internet egress and permits only the `127.0.0.1/32` route required by the authenticated transport and proxy. That loopback exception does not isolate unrelated host services. The explicit proxy resolves and rechecks the socket-owning executable through the Windows kernel TCP table. Authorizing a launcher does not authorize its children; missing, ambiguous, or changed ownership denies the request. Treat the gateway host as trusted. Attached provider credentials use the ordinary live supervisor refresh path. Static values stay in the host supervisor's endpoint-bound resolver and are injected only for matching requests. Dynamic token grants remain request-time operations in the host proxy. diff --git a/docs/how-it-works/sandboxes/runtimes.mdx b/docs/how-it-works/sandboxes/runtimes.mdx index cc76cf98d2..144b4cdd4c 100644 --- a/docs/how-it-works/sandboxes/runtimes.mdx +++ b/docs/how-it-works/sandboxes/runtimes.mdx @@ -21,7 +21,13 @@ the sandbox record and driver-supported persistent storage. | [Podman](#podman-driver) | `podman` | Rootless Linux workstations without a Docker daemon. | | [MicroVM](#microvm-driver) | `vm` | Workloads need a VM boundary instead of a container boundary. | | [Kubernetes](#kubernetes-driver) | `kubernetes` | Shared clusters, remote compute, and GPU scheduling. | -| Windows MXC | `mxc` | Coming soon. | +| [Windows MXC](https://github.com/NVIDIA/OpenShell/blob/windows/WINDOWS.md) | `mxc` | Native Windows development on x64 or ARM64; implementation and releases stay on `windows`. Not production-qualified. | + +For MXC, follow the +[`windows` branch configuration and limitations](https://github.com/NVIDIA/OpenShell/blob/windows/docs/how-it-works/gateways/configuration.mdx#mxc). +Windows uses a host supervisor and a dedicated ProcessContainer boundary, +requires proxy-aware workloads, and does not support foreground main-process +attachment. The Linux runtime configuration below does not set up native Windows. ## Select a Compute Driver