mirror of
https://github.com/NVIDIA/OpenShell.git
synced 2026-10-29 07:23:25 +08:00
docs(windows): route main documentation to the Windows release branch (#4758)
* docs(windows): route main documentation to the Windows release branch Signed-off-by: Shailendra Singh <shailendras@nvidia.com> * docs(windows): include native MXC tests in full validation Signed-off-by: Shailendra Singh <shailendras@nvidia.com> * docs(windows): address documentation review feedback Signed-off-by: Shailendra Singh <shailendras@nvidia.com> * docs(windows): include E2E in full validation Signed-off-by: Shailendra Singh <shailendras@nvidia.com> * docs(windows): stop validation after any failed task Signed-off-by: Shailendra Singh <shailendras@nvidia.com> * docs(windows): simplify quickstart and installation guidance Signed-off-by: Drew Newberry <anewberry@nvidia.com> --------- Signed-off-by: Shailendra Singh <shailendras@nvidia.com> Signed-off-by: Drew Newberry <anewberry@nvidia.com> Co-authored-by: Drew Newberry <anewberry@nvidia.com>
This commit is contained in:
Shailendra Singh
co-authored by
Drew Newberry
Drew Newberry
parent
f5d9223e08
commit
17eda52d45
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: build-openshell-mxc-windows
|
||||
description: Maintain and validate OpenShell's build-only Windows MSVC lane for x64 and ARM64. Use when working on Windows compilation, `windows:*` mise tasks, unsupported Windows compute-driver contracts, or Windows build reports. This skill does not implement Docker, Kubernetes, Podman, VM, MXC driver, policy translation, MSI, service, or supervisor runtime support on Windows.
|
||||
description: Maintain and validate OpenShell's native Windows MSVC and MXC runtime lane for x64 and ARM64. Use when working on Windows compilation, `windows:*` mise tasks, the MXC supervisor/sandbox pairing, unsupported Windows compute-driver contracts, or Windows build reports. This skill does not implement Docker, Kubernetes, Podman, VM, MSI, or service support on Windows.
|
||||
metadata:
|
||||
internal: true
|
||||
---
|
||||
@@ -8,15 +8,24 @@ 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).
|
||||
|
||||
The lane is build-only. It validates that OpenShell can compile and test on
|
||||
Windows MSVC for the supported deliverables:
|
||||
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:
|
||||
|
||||
- `openshell-gateway.exe`
|
||||
- `openshell.exe`
|
||||
- `openshell-supervisor.exe` (host RFC 0012 isolation backend)
|
||||
- `openshell-windows-sandbox.exe` (MXC ProcessContainer boundary)
|
||||
|
||||
It intentionally does not make Windows a Docker, Kubernetes, Podman, or VM
|
||||
runtime host.
|
||||
@@ -33,6 +42,58 @@ SSH access adapter separate from portable session orchestration.
|
||||
Shared Sandbox Protocol audit validation defaults to strict Linux evidence;
|
||||
concrete platform validators must be selected by the implementing backend.
|
||||
|
||||
MXC control connects outward from the boundary to a generation-scoped host
|
||||
loopback listener, matching the Windows relay's connection direction. Keep
|
||||
the reverse connector in the MXC isolation backend and share it across policy
|
||||
discovery and attachment. Shared transport hooks must retain pinned TLS peer
|
||||
verification and supervisor JWT authentication; do not change host firewall
|
||||
rules to repair host-to-AppContainer control connectivity.
|
||||
|
||||
The dedicated Windows sandbox binary links the Windows-only `openshell-mxc-boundary`
|
||||
library for process operations, containment confirmation, and loopback
|
||||
forwarding. The generic sandbox does not link this library and remains a Linux
|
||||
runtime. Do not reintroduce a dedicated supervisor-relay executable or link
|
||||
the compute driver into the sandbox. The supervisor remains a separate host
|
||||
process. Include boundary-library regression tests in native workspace tests;
|
||||
their real process/socket checks are not qualification of MXC enforcement.
|
||||
|
||||
Keep MXC audit schemas and their validators in the Windows boundary library.
|
||||
Register its `MxcRuntimeBackend` under `openshell-mxc` at supervisor composition.
|
||||
Use the private `BackendSetup` / `PreparedBackend` extension for launch decoding,
|
||||
policy discovery, and client construction. Shared startup must not decode the
|
||||
MXC descriptor or allocate its connector. Retain the same reverse-TCP connector
|
||||
in prepared launch state through discovery, attachment, and reconnects.
|
||||
It reuses the shared authenticated Sandbox Protocol, whose default Linux
|
||||
backend remains separate. Shared protocol code
|
||||
must not interpret MXC evidence.
|
||||
|
||||
Keep proxy provisioning in MXC-owned host-launch and one-use bootstrap
|
||||
envelopes. Private Windows backend setup supplies concrete listener options to
|
||||
shared supervisor networking. Do not add proxy hooks to `BoundBoundary`, proxy
|
||||
fields to shared Sandbox Protocol descriptors, or placeholders to other drivers.
|
||||
Proxy startup remains after authenticated attachment and boundary confirmation.
|
||||
|
||||
Do not reintroduce driver-owned proxy startup
|
||||
or gateway create-time credential snapshots. Gateway JSONL audit output
|
||||
is portable and an explicit operator opt-in, independent of the selected driver.
|
||||
Keep platform directory conventions in shared path utilities and ETW capture
|
||||
in the MXC driver. Gateway composition supplies generic connection inputs; the
|
||||
driver resolves its endpoint defaults and TLS server name. Supervisor gateway
|
||||
sessions and main attachment must work without SSH on any host. Gate only the
|
||||
Unix socket adapter, not TCP readiness or authenticated session retries.
|
||||
|
||||
Adopt the shared protocol's authenticated policy discovery and monotonic
|
||||
provider-publication generations. Do not order opaque credential revisions
|
||||
numerically. MXC rejects unsupported provider file delivery before launch or
|
||||
environment replacement; it must not acknowledge files it did not install.
|
||||
|
||||
Preserve main's shared outer-fence evidence contract. At the user's explicit
|
||||
request, MXC temporarily asserts the required guarantees for Windows-branch
|
||||
parity testing. These MXC-only assertions are stubs, not verified enforcement:
|
||||
broad host loopback and unverified live revocation remain known gaps. Keep the
|
||||
TODOs and unverified audit mechanism visible; never report passing E2E as proof
|
||||
that these gaps are closed. A supported PSEC host alone does not close them.
|
||||
|
||||
## Current Repository Shape
|
||||
|
||||
The Windows build lane is implemented by these tracked files:
|
||||
@@ -53,11 +114,11 @@ 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` and
|
||||
`openshell`.
|
||||
- Building x64 and ARM64 release binaries for `openshell-gateway`, `openshell`,
|
||||
`openshell-supervisor`, and `openshell-windows-sandbox`.
|
||||
- Running workspace tests on a native x64 or ARM64 host.
|
||||
- Running focused unsupported-driver contract tests.
|
||||
- Reporting test counts, skipped/gated areas, warnings, artifacts, and logs.
|
||||
@@ -70,12 +131,9 @@ Out of scope:
|
||||
- Kubernetes support on Windows.
|
||||
- Podman, Podman machine, or Podman Desktop support on Windows.
|
||||
- VM, Hyper-V, WSL, libkrun, or VM-backed sandbox execution on Windows.
|
||||
- New MXC compute driver crate.
|
||||
- OpenShell to MXC policy translation.
|
||||
- Windows named-pipe driver IPC.
|
||||
- Windows Credential Manager or DPAPI integration.
|
||||
- MSI, WinGet, Windows service registration, or installer work.
|
||||
- Windows supervisor runtime port.
|
||||
|
||||
## Hard Rules
|
||||
|
||||
@@ -102,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
|
||||
```
|
||||
|
||||
@@ -168,6 +226,16 @@ mise run --skip-tools windows:test:x64
|
||||
mise run --skip-tools windows:test:unsupported:x64
|
||||
```
|
||||
|
||||
The two `windows:test:mxc-real:*` tasks are host-specific and mutually
|
||||
exclusive on a single host (each rejects the other architecture -- see the
|
||||
table below): run `windows:test:mxc-real:x64` on an x64 host, or
|
||||
`windows:test:mxc-real:arm64` on an ARM64 host, as part of validating this
|
||||
subsystem -- run the one matching your host architecture, not both, and not
|
||||
neither. Both are skip-safe (they print a SKIP reason and exit 0 when
|
||||
`wxc-exec` or the matching backend isn't available), so running the
|
||||
arch-appropriate task is always safe even without real MXC hardware. Neither
|
||||
is part of `windows:ci`'s ordered contract, so invoke it explicitly.
|
||||
|
||||
For full validation, detect the Windows host architecture first and choose the
|
||||
native lane dynamically:
|
||||
|
||||
@@ -176,13 +244,27 @@ $arch = [System.Runtime.InteropServices.RuntimeInformation]::OSArchitecture
|
||||
switch ($arch.ToString()) {
|
||||
"X64" {
|
||||
mise run --skip-tools windows:ci
|
||||
if ($LASTEXITCODE -ne 0) { throw "windows:ci failed." }
|
||||
mise run --skip-tools windows:test:mxc-real:x64
|
||||
if ($LASTEXITCODE -ne 0) { throw "windows:test:mxc-real:x64 failed." }
|
||||
mise run --skip-tools windows:e2e:mxc
|
||||
if ($LASTEXITCODE -ne 0) { throw "MXC E2E validation failed or was incomplete." }
|
||||
}
|
||||
"Arm64" {
|
||||
mise run --skip-tools windows:check:arm64
|
||||
if ($LASTEXITCODE -ne 0) { throw "windows:check:arm64 failed." }
|
||||
mise run --skip-tools windows:build:arm64
|
||||
if ($LASTEXITCODE -ne 0) { throw "windows:build:arm64 failed." }
|
||||
mise run --skip-tools windows:test:arm64
|
||||
if ($LASTEXITCODE -ne 0) { throw "windows:test:arm64 failed." }
|
||||
mise run --skip-tools windows:test:unsupported:arm64
|
||||
if ($LASTEXITCODE -ne 0) { throw "windows:test:unsupported:arm64 failed." }
|
||||
mise run --skip-tools windows:test:mxc-real:arm64
|
||||
if ($LASTEXITCODE -ne 0) { throw "windows:test:mxc-real:arm64 failed." }
|
||||
mise run --skip-tools windows:artifacts
|
||||
if ($LASTEXITCODE -ne 0) { throw "windows:artifacts failed." }
|
||||
mise run --skip-tools windows:e2e:mxc
|
||||
if ($LASTEXITCODE -ne 0) { throw "MXC E2E validation failed or was incomplete." }
|
||||
}
|
||||
default {
|
||||
throw "Unsupported Windows host architecture for OpenShell MSVC validation: $arch"
|
||||
@@ -190,6 +272,9 @@ switch ($arch.ToString()) {
|
||||
}
|
||||
```
|
||||
|
||||
Full validation requires an MXC-capable host. E2E exits nonzero when any
|
||||
required runtime scenario fails or skips.
|
||||
|
||||
On x64 hosts, `windows:ci` is the full current CI contract and runs in this
|
||||
order:
|
||||
|
||||
@@ -218,7 +303,7 @@ jobs in the current mirror push run, or push a new mirrored commit. The binaries
|
||||
The ARM64 check/build steps in this x64-host contract are cross-builds. The
|
||||
wrapper discovers and adds host-native LLVM and Ninja to `PATH`, requires the
|
||||
ARM64 compiler and Spectre-mitigated libraries, lets ARM64 crypto crates select
|
||||
`clang-cl`, and downloads the official prebuilt ARM64 Z3 static library.
|
||||
`clang-cl`, and downloads the official prebuilt ARM64 Z3 package.
|
||||
|
||||
On ARM64 hosts, validate the native ARM64 check, build, and test path. The
|
||||
wrapper rejects test targets that do not match the host architecture, so x64
|
||||
@@ -253,12 +338,14 @@ crypto dependency builds.
|
||||
|---|---|
|
||||
| `windows:check:x64` | `cargo check --workspace` for `x86_64-pc-windows-msvc`, excluding unsupported Windows packages as top-level workspace targets. |
|
||||
| `windows:check:arm64` | `cargo check --workspace` for `aarch64-pc-windows-msvc`, with the same top-level exclusions. |
|
||||
| `windows:build:x64` | Release-builds `openshell-gateway.exe` and `openshell.exe` for x64. |
|
||||
| `windows:build:arm64` | Release-builds `openshell-gateway.exe` and `openshell.exe` for ARM64. |
|
||||
| `windows:build:x64` | Release-builds `openshell-gateway.exe`, `openshell.exe`, `openshell-supervisor.exe`, and `openshell-windows-sandbox.exe` for x64. |
|
||||
| `windows:build:arm64` | Release-builds the same four binaries for ARM64. |
|
||||
| `windows:test:x64` | Runs native x64 workspace tests with `--no-fail-fast`, excluding unsupported Windows packages as top-level workspace targets. |
|
||||
| `windows:test:arm64` | Runs native ARM64 workspace tests with `--no-fail-fast` and the same package exclusions. Rejects non-ARM64 hosts. |
|
||||
| `windows:test:unsupported:x64` | Re-runs focused `openshell-gateway` tests for unsupported Windows driver behavior. |
|
||||
| `windows:test:unsupported:arm64` | Re-runs the same focused contracts natively on ARM64. Rejects non-ARM64 hosts. |
|
||||
| `windows:test:mxc-real:x64` | Runs the serial, ignored real-`wxc-exec` integration suite natively on x64 through the MSVC wrapper. Rejects non-x64 hosts. |
|
||||
| `windows:test:mxc-real:arm64` | Runs the same real-`wxc-exec` suite natively on ARM64. Rejects non-ARM64 hosts. |
|
||||
| `windows:artifacts` | Reports size and SHA256 for release artifacts that exist. |
|
||||
| `windows:ci` | Runs the full ordered x64-host Windows CI lane, plus ARM64 check/build when not skipped. |
|
||||
|
||||
@@ -270,6 +357,30 @@ in the gateway build graph, but their Unix-socket standalone binaries do not.
|
||||
|
||||
## Unsupported Driver Contract
|
||||
|
||||
MXC requests and mapper artifacts use the stable 1.0.0 schema. Upgrade the
|
||||
native host executor to the signed MXC 1.0.0 release before running E2E; preserve
|
||||
the old executable for rollback and verify the release checksum, architecture,
|
||||
signature, and `--probe` output. Remove `default_configuration_id` from gateway
|
||||
configurations: it is retired and rejected. Do not restore alpha-version or
|
||||
wildcard compatibility knobs. Standalone network mapping emits numeric CIDRs
|
||||
and TCP ports and reports unrepresentable DNS/L7 semantics as losses; full
|
||||
network governance remains in the host supervisor. IsolationSession remains
|
||||
unsupported by this runtime pair, and its filesystem grants are not enforceable.
|
||||
|
||||
MXC does not support external-resource label admission. Its factory explicitly
|
||||
acknowledges admission as disabled; do not add `resource_admission` to MXC TOML
|
||||
or weaken admission defaults for other drivers. Caller driver JSON still
|
||||
requires `allow_driver_config = true`. This does not waive native isolation,
|
||||
workload policy, authenticated transport, or outer-fence confirmation.
|
||||
|
||||
UI controls remain in `SandboxPolicy`. Advertise `openshell.policy.ui.v1` using
|
||||
existing extension metadata, not a new per-driver boolean. The shared gateway
|
||||
checks effective policy before driver validation and provisioning; drivers
|
||||
without the capability reject explicit UI without implementing UI-specific
|
||||
handling. Keep native UI validation and mapping in MXC. Omitted UI settings deny
|
||||
graphical UI, clipboard access, and input injection. UI changes require
|
||||
recreating the sandbox.
|
||||
|
||||
Windows must continue to reject unsupported compute drivers clearly.
|
||||
|
||||
The gateway's `compute-driver-mxc` feature independently links and registers
|
||||
@@ -303,6 +414,77 @@ validation; GitHub Actions does not re-run it after the full suite.
|
||||
|
||||
## Test Accounting Guidance
|
||||
|
||||
For a separate qualified Windows test host, use
|
||||
`tasks/scripts/test-mxc-remote.ps1 -HostName <host> -UserName <user>`.
|
||||
It builds locally with the existing Windows tasks, detects native remote
|
||||
architecture through Windows system configuration (not an emulated SSH shell),
|
||||
caches uploads by SHA256, and runs the unchanged real E2E harness. Results and
|
||||
host probes return to `target/windows-remote-results`, including nonzero test
|
||||
outcomes. The remote host needs SSH, OpenSSL, and MXC, not a compiler toolchain.
|
||||
Package the matching `libz3.dll` from the target-specific Cargo cache alongside
|
||||
the gateway: Windows prebuilt Z3 uses an import library, not static linkage.
|
||||
The `windows:build:*` tasks now stage the pinned DLL, check PE architecture,
|
||||
reject conflicting cache hashes, and verify the copied hash. Local MXC E2E
|
||||
requires the adjacent DLL and reports a preflight error if it is missing.
|
||||
Use `-Z3DllPath` when discovery is ambiguous. The native Visual C++ runtime
|
||||
must be present on the remote host. Verify DLL architecture and the gateway
|
||||
loader before E2E; do not count missing-DLL crashes as MXC enforcement failures.
|
||||
Verify the SSH host key beforehand. Never send the private SSH key or bundle
|
||||
the harness signing-key directories. `-SkipBuild` is an explicit stale-artifact
|
||||
opt-in, not evidence that artifacts match current sources. See the MXC driver
|
||||
README for the command and remote dependency contract.
|
||||
|
||||
For MXC validation, also run `windows:e2e:mxc`
|
||||
after the native release build. The harness uses .NET port discovery, disposable
|
||||
TOML and CLI registration, and owner-only Ed25519 keys generated by OpenSSL on
|
||||
PATH. Results live under `target/windows-e2e-results`; signing keys stay outside
|
||||
bundles and are deleted unless `-KeepRunning` is explicitly requested.
|
||||
|
||||
E2E has no mock mode and rejects `OPENSHELL_MXC_MOCK_WXC=1`. Unit-test mocks
|
||||
are not E2E coverage. Every selected scenario must pass for a successful exit;
|
||||
any skip reports `INCOMPLETE` and exits non-zero. Do not broaden the temporary
|
||||
MXC network-assertion waiver to other audit or authentication checks. Real
|
||||
runtime scenarios require native ProcessContainer PSEC egress
|
||||
filtering and ingress host-loopback support. `wxc-exec --probe` is authoritative,
|
||||
not the Windows build number. All-skipped real runs are not passes. Separate
|
||||
test-internal `SKIP` messages from Cargo's passed count in the real integration
|
||||
suite, and report a verified unsupported-host rejection independently from
|
||||
positive admission coverage.
|
||||
|
||||
The real `forwarding` E2E scenario uses a native test-only echo agent inside MXC and
|
||||
`openshell forward service` to verify two exact request/reply exchanges through
|
||||
the gateway, supervisor, and boundary. Dynamic ports and a per-workload nonce
|
||||
avoid mistaking unrelated listeners for success. This is managed-ingress
|
||||
coverage, not evidence that direct host ingress is fenced. Use
|
||||
`-Scenario forwarding` on the existing local or remote runner for focused checks.
|
||||
The E2E mise task and remote runner build the `mxc-forwarding-agent` Cargo example
|
||||
using `windows:build:mxc-fixtures` (or its `:x64` / `:arm64` variant). This fixture
|
||||
is not one of the four production deliverables; do not package it in releases.
|
||||
The `service-forwarding` scenario uses its HTTP mode to test named endpoint
|
||||
exposure, two exact GET responses through gateway routing, and HTTP 404 after
|
||||
endpoint deletion. This is distinct from `openshell forward service`; neither
|
||||
scenario tests file upload or exclusive ingress enforcement.
|
||||
|
||||
The real integration HTTPS test runs the same authenticated gateway harness with
|
||||
the opt-in `https-ca` scenario, not an unauthenticated standalone driver. Build
|
||||
native release binaries first, or select them with `OPENSHELL_MXC_TEST_BINARY_DIR`.
|
||||
It requires Internet access to example.com and Windows curl >= 8.3 to explicitly
|
||||
expand the injected CA bundle into `--cacert` (Schannel ignores that environment
|
||||
variable by default). Require both a nonempty response and the OpenShell proxy
|
||||
CA issuer; never replace these assertions with an insecure TLS request. This
|
||||
fixture permits unavailable CRL information using best-effort Schannel revocation
|
||||
for the ephemeral private CA; this is not revocation qualification. This
|
||||
scenario is not part of the default seven offline-capable E2E scenarios.
|
||||
|
||||
The default `host-service` scenario runs the HTTP fixture on host `127.0.0.1`
|
||||
and a dynamic port, then checks two nonce-bound replies from direct curl requests
|
||||
inside MXC. Host-side readiness and request proofs stay outside the workload's
|
||||
writable directory. The service is stopped even after failed runs. Use
|
||||
`-Scenario host-service` for focused checks. No Internet access, LAN address, or
|
||||
firewall modification is required. A failed host health check or workload
|
||||
request fails the test. This verifies direct localhost connectivity; retain
|
||||
the existing shared proxy SSRF controls.
|
||||
|
||||
When reporting `windows:ci`, distinguish these categories:
|
||||
|
||||
- Passed tests from the full x64 workspace test log.
|
||||
@@ -328,6 +510,8 @@ Useful log files:
|
||||
| `test-aarch64-pc-windows-msvc.log` | Full native ARM64 workspace test output. |
|
||||
| `test-x86_64-pc-windows-msvc-unsupported-*.log` | Focused unsupported-driver contract output. |
|
||||
| `test-aarch64-pc-windows-msvc-unsupported-*.log` | Focused native ARM64 contract output. |
|
||||
| `test-x86_64-pc-windows-msvc-mxc-real.log` | Native x64 real-MXC integration output. |
|
||||
| `test-aarch64-pc-windows-msvc-mxc-real.log` | Native ARM64 real-MXC integration output. |
|
||||
|
||||
The first check downloads the pinned official Z3 archive for the target
|
||||
architecture through `z3-sys`. GitHub Actions authenticates the lookup with its
|
||||
@@ -339,6 +523,12 @@ module being available inside the mise-launched Windows PowerShell process.
|
||||
|
||||
## Common Fix Patterns
|
||||
|
||||
Keep supervisor admission fixtures independent of host Linux filesystem paths.
|
||||
Inject deterministic baseline enrichment into startup tests and reuse the
|
||||
production merge routine. Preserve prover runtime-parity assertions when fixing
|
||||
solver timeouts. Mutation-lock stress tests retain their parallel workload and
|
||||
exclusion checks with a larger Windows timer budget.
|
||||
|
||||
When Windows validation fails:
|
||||
|
||||
1. Identify whether the error is from a top-level Windows deliverable, a
|
||||
@@ -357,6 +547,12 @@ skill or design doc.
|
||||
|
||||
## Final Report Checklist
|
||||
|
||||
When syncing from the `windows` branch, consult the selective integration
|
||||
checkpoint in `crates/openshell-driver-mxc/WINDOWS-INTEGRATION.md`. Preserve
|
||||
the host-supervisor/Windows-boundary architecture rather than restoring legacy
|
||||
relay/proxy demo wrappers. The WebSocket, OpenClaw, and inference policy fixtures
|
||||
have parser/mapper tests; do not report them as live runtime scenarios.
|
||||
|
||||
Every substantial Windows build run should report:
|
||||
|
||||
| Item | Required detail |
|
||||
@@ -371,3 +567,25 @@ Every substantial Windows build run should report:
|
||||
| Artifacts | Binary paths, size, and SHA256 when available. |
|
||||
| Skips | Explicitly explain tests not run for a non-native architecture, unsupported driver package exclusions, and Windows cfg-gated tests. |
|
||||
| Follow-ups | Only concrete follow-ups tied to failures or requested scope. |
|
||||
|
||||
## Focused MXC network qualification
|
||||
|
||||
Use `mise run --skip-tools windows:test:mxc-boundary` for boundary unit tests and
|
||||
real Windows kernel socket-owner lookup. `windows:test:mxc-network` requires the
|
||||
native release build and Internet access; it runs the injected-CA HTTPS test and
|
||||
the allow-child/deny-child socket-owner regression through the authenticated
|
||||
harness. `windows:test:mxc-loopback` executes its test inside a real native MXC
|
||||
container with host loopback denied, separately from ordinary unit coverage.
|
||||
Do not enable broad host loopback to turn an unsupported-runtime failure green.
|
||||
The MSVC wrapper selects native test architecture from the machine environment,
|
||||
so an emulated SSH PowerShell does not incorrectly reject ARM64 qualification.
|
||||
Keep Windows kernel calls in the boundary library and retain shared supervisor
|
||||
unsafe-code bans, per-generation proxy authentication, and executable digests.
|
||||
|
||||
Use `windows:test:mxc-audit` to validate the shipped audit gateway config with
|
||||
its real parser, test JSONL coverage classification, and run the live seven-event
|
||||
ETW qualification. Build native release binaries first and set
|
||||
`OPENSHELL_WXC_EXEC_PATH`. The runner requires elevation or Performance Log Users
|
||||
membership and leaves a results bundle under the target directory. Ordinary MXC
|
||||
E2E success does not establish ETW audit coverage. Coverage must use structured
|
||||
JSONL and fail when an expected event is absent or has the wrong OCSF class.
|
||||
|
||||
@@ -1,7 +1,10 @@
|
||||
# Reference: Windows MSVC maintenance lane
|
||||
|
||||
Companion to [SKILL.md](SKILL.md). Use this file for quick lookup while
|
||||
maintaining the existing build-only Windows MSVC 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
|
||||
|
||||
@@ -33,15 +36,35 @@ For host-native full validation, detect architecture first:
|
||||
$arch = [System.Runtime.InteropServices.RuntimeInformation]::OSArchitecture
|
||||
if ($arch -eq [System.Runtime.InteropServices.Architecture]::Arm64) {
|
||||
mise run --skip-tools windows:check:arm64
|
||||
if ($LASTEXITCODE -ne 0) { throw "windows:check:arm64 failed." }
|
||||
mise run --skip-tools windows:build:arm64
|
||||
if ($LASTEXITCODE -ne 0) { throw "windows:build:arm64 failed." }
|
||||
mise run --skip-tools windows:test:arm64
|
||||
if ($LASTEXITCODE -ne 0) { throw "windows:test:arm64 failed." }
|
||||
mise run --skip-tools windows:test:unsupported:arm64
|
||||
if ($LASTEXITCODE -ne 0) { throw "windows:test:unsupported:arm64 failed." }
|
||||
mise run --skip-tools windows:test:mxc-real:arm64
|
||||
if ($LASTEXITCODE -ne 0) { throw "windows:test:mxc-real:arm64 failed." }
|
||||
mise run --skip-tools windows:artifacts
|
||||
if ($LASTEXITCODE -ne 0) { throw "windows:artifacts failed." }
|
||||
mise run --skip-tools windows:e2e:mxc
|
||||
if ($LASTEXITCODE -ne 0) { throw "MXC E2E validation failed or was incomplete." }
|
||||
} else {
|
||||
mise run --skip-tools windows:ci
|
||||
if ($LASTEXITCODE -ne 0) { throw "windows:ci failed." }
|
||||
mise run --skip-tools windows:test:mxc-real:x64
|
||||
if ($LASTEXITCODE -ne 0) { throw "windows:test:mxc-real:x64 failed." }
|
||||
mise run --skip-tools windows:e2e:mxc
|
||||
if ($LASTEXITCODE -ne 0) { throw "MXC E2E validation failed or was incomplete." }
|
||||
}
|
||||
```
|
||||
|
||||
`windows:ci` does not include the real MXC runtime tests or E2E. Run the matching
|
||||
`windows:test:mxc-real:*` task and `windows:e2e:mxc` explicitly.
|
||||
These tasks can report `SKIP` when the executor or backend is unavailable;
|
||||
full validation requires an MXC-capable host. E2E exits nonzero when any
|
||||
required runtime scenario fails or skips.
|
||||
|
||||
The native test tasks reject a target that does not match the host architecture.
|
||||
Do not report x64 compatibility-under-emulation coverage from an ARM64 run.
|
||||
|
||||
@@ -75,7 +98,7 @@ Ninja to `PATH`, while the crypto crates select `clang-cl`. Use a short
|
||||
|
||||
## Unsupported Driver Rules
|
||||
|
||||
Windows is a build target only. These runtimes remain unsupported:
|
||||
These Windows runtimes remain unsupported:
|
||||
|
||||
- Docker
|
||||
- Kubernetes
|
||||
@@ -115,11 +138,10 @@ top-level workspace targets for check/test:
|
||||
```
|
||||
|
||||
The gateway keeps platform configuration and unsupported-operation contracts
|
||||
without depending on the Docker, Kubernetes, Podman, sandbox runtime,
|
||||
standalone supervisor, supervisor process runtime, VM, or VFIO crates. The MXC
|
||||
driver does depend on the cross-platform supervisor network library for its host
|
||||
egress proxy. The Kubernetes Secrets and Vault libraries still compile as
|
||||
gateway dependencies; only their standalone Unix-socket binaries and
|
||||
without depending on the Docker, Kubernetes, Podman, VM, or VFIO runtime crates.
|
||||
The MXC runtime compiles the supervisor, supervisor-process library, and sandbox
|
||||
boundary on Windows. The Kubernetes Secrets and Vault libraries still compile
|
||||
as gateway dependencies; only their standalone Unix-socket binaries and
|
||||
package-level tests are excluded as top-level targets.
|
||||
|
||||
The supervisor and supervisor-process packages now participate as top-level
|
||||
|
||||
@@ -29,6 +29,7 @@ Run after adding, removing, or renaming a skill or crate; changing issue or PR c
|
||||
| Release artifacts or smoke coverage | `test-release-canary` |
|
||||
| Release cadence, tagging, or qualification workflows | `release-captain` |
|
||||
| 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` |
|
||||
|
||||
@@ -51,7 +51,8 @@ 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 AppContainer and isolation-session compute backend |
|
||||
| [`crates/openshell-driver-mxc/`](https://github.com/NVIDIA/OpenShell/tree/windows/crates/openshell-driver-mxc) (`windows` branch) | Microsoft MXC compute driver | Native Windows ProcessContainer backend; see the Windows branch for the maintained implementation |
|
||||
| [`crates/openshell-mxc-boundary/`](https://github.com/NVIDIA/OpenShell/tree/windows/crates/openshell-mxc-boundary) (`windows` branch) | Windows sandbox boundary | Dedicated Windows workload boundary paired with the host supervisor |
|
||||
| `crates/openshell-prover/` | Policy prover | Policy verification and proof generation |
|
||||
| `crates/openshell-prover-cli/` | Policy prover CLI | Standalone local policy boundary checks |
|
||||
| `crates/openshell-supervisor-middleware/` | Middleware runtime | Generic middleware registry, remote service integration, and chain execution |
|
||||
|
||||
@@ -67,11 +67,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
|
||||
|
||||
|
||||
+22
-5
@@ -114,7 +114,7 @@ Contributor and maintainer skills live in `.agents/skills/`. They are marked int
|
||||
| Triage | `apply-triage-action` | Apply, reject, or defer one explicitly selected triage recommendation |
|
||||
| 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 build-only x64 and ARM64 Windows MSVC 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 |
|
||||
| Maintenance | `release-captain` | Run the weekly Monday pre-flight and Tuesday stable release checklist |
|
||||
@@ -142,6 +142,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
|
||||
@@ -164,7 +170,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+
|
||||
@@ -226,7 +232,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
|
||||
@@ -249,8 +255,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
|
||||
@@ -261,6 +269,12 @@ $env:LIBCLANG_PATH='C:\Program Files\Microsoft Visual Studio\2022\<Edition>\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:
|
||||
|
||||
@@ -280,6 +294,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
|
||||
|
||||
@@ -38,6 +38,8 @@ openshell sandbox create --name demo
|
||||
|
||||
The installer sets up the CLI and a local gateway. The default sandbox image is minimal Ubuntu with no agent installed. To run a real agent, follow [Run Your First Agent](https://docs.nvidia.com/openshell/latest/about/run-your-first-agent): it runs OpenCode against a free OpenRouter model and shows how to approve new access as the agent needs it.
|
||||
|
||||
For native Windows support through Microsoft MXC, see the [Windows build and runtime guide](https://github.com/NVIDIA/OpenShell/blob/windows/WINDOWS.md) for setup and current limitations.
|
||||
|
||||
## Explore Further
|
||||
|
||||
- [Sandboxes](https://docs.nvidia.com/openshell/latest/how-it-works/sandboxes/overview): images, runtimes, GPUs, and lifecycle.
|
||||
|
||||
+38
@@ -73,6 +73,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.
|
||||
|
||||
+113
@@ -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/<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.
|
||||
|
||||
```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.
|
||||
@@ -1,5 +1,15 @@
|
||||
# openshell-driver-mxc
|
||||
|
||||
Native Windows implementation and releases are maintained on the
|
||||
[`windows` branch](https://github.com/NVIDIA/OpenShell/tree/windows).
|
||||
For current setup, capabilities, and limitations, use the
|
||||
[Windows driver README](https://github.com/NVIDIA/OpenShell/blob/windows/crates/openshell-driver-mxc/README.md)
|
||||
and [Windows guide](../../WINDOWS.md). The implementation notes below describe
|
||||
the older source snapshot on `main`, not the current Windows release branch.
|
||||
In particular, current Windows uses a separate host supervisor and Windows
|
||||
sandbox boundary; do not use this snapshot's relay, readiness, or configuration
|
||||
instructions to operate a `windows` build.
|
||||
|
||||
OpenShell compute driver backed by **Microsoft MXC** (`wxc-exec`) on Windows.
|
||||
|
||||
## Design
|
||||
|
||||
@@ -12,7 +12,7 @@ Install OpenShell on a local workstation or Kubernetes.
|
||||
|
||||
## Install OpenShell
|
||||
|
||||
Install the CLI, policy prover, and a local gateway with one command:
|
||||
On Linux or macOS, install the CLI, policy prover, and a local gateway with one command:
|
||||
|
||||
```shell
|
||||
curl -LsSf https://raw.githubusercontent.com/NVIDIA/OpenShell/main/install.sh | sh
|
||||
@@ -72,6 +72,21 @@ The local gateway auto-detects an available runtime. To pin one, set `compute_dr
|
||||
| Docker | Docker Desktop or Docker Engine 28.0 or later. |
|
||||
| Podman | Linux with Podman 5.x, cgroups v2, and an active Podman user socket. |
|
||||
| MicroVM | Host virtualization: Hypervisor.framework on macOS or KVM on Linux. |
|
||||
| [Windows MXC](#windows) | Native Windows x64 or ARM64 with MXC 1.0.0 and a host that passes the ProcessContainer capability probe. Development; not production-qualified. |
|
||||
|
||||
## Windows
|
||||
|
||||
Build native Windows x64 or ARM64 binaries from the
|
||||
[`windows` branch](https://github.com/NVIDIA/OpenShell/tree/windows).
|
||||
Follow the [Windows build and runtime guide](https://github.com/NVIDIA/OpenShell/blob/windows/WINDOWS.md)
|
||||
for MSVC prerequisites, MXC host probing, and gateway setup. Select
|
||||
`compute_driver = "mxc"` in the gateway TOML file.
|
||||
|
||||
Native Windows uses Microsoft MXC ProcessContainer isolation. It is under
|
||||
development and is not production-qualified; see the
|
||||
[current runtime limitations](https://github.com/NVIDIA/OpenShell/blob/windows/WINDOWS.md#runtime-and-current-limits).
|
||||
The installer and release channels above do not supply native Windows binaries.
|
||||
Running Linux OpenShell inside WSL 2 is a separate, experimental option.
|
||||
|
||||
## macOS
|
||||
|
||||
|
||||
@@ -55,9 +55,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) | x86_64 and ARM64 | `windows` branch |
|
||||
|
||||
On Linux, the `openshell` CLI is a static musl binary and does not require glibc at runtime.
|
||||
|
||||
### Windows
|
||||
|
||||
Native Windows uses MXC and is separate from WSL 2. Use the
|
||||
[Windows guide](https://github.com/NVIDIA/OpenShell/blob/windows/WINDOWS.md)
|
||||
for builds from `windows`, host requirements, and enforcement limitations.
|
||||
|
||||
## Standalone Gateway Binary
|
||||
|
||||
OpenShell publishes standalone `openshell-gateway` release assets for manual download on these platforms:
|
||||
|
||||
@@ -1047,43 +1047,35 @@ the SPIRE OIDC discovery endpoint or its TLS CA.
|
||||
|
||||
### MXC
|
||||
|
||||
The MXC driver runs Windows workloads through `wxc-exec`. Enable ETW auditing to
|
||||
map Windows Sandboxing provider events into the gateway's OCSF stream.
|
||||
The MXC driver runs native Windows workloads through `wxc-exec`. Use this
|
||||
configuration with a build from the
|
||||
[`windows` branch](https://github.com/NVIDIA/OpenShell/tree/windows). Keep
|
||||
`openshell-supervisor.exe` and `openshell-windows-sandbox.exe` beside the gateway.
|
||||
|
||||
```toml
|
||||
[openshell]
|
||||
version = 2
|
||||
|
||||
[openshell.gateway]
|
||||
bind_address = "127.0.0.1:17670"
|
||||
log_level = "info"
|
||||
bind_address = "127.0.0.1:17670"
|
||||
compute_driver = "mxc"
|
||||
# Required when gateway TLS is enabled.
|
||||
guest_tls_ca = "C:\\OpenShell\\certs\\ca.pem"
|
||||
|
||||
[openshell.drivers.mxc]
|
||||
wxc_exec_path = "C:\\mxc-kit\\bin\\wxc-exec.exe"
|
||||
backend = "process_container"
|
||||
default_configuration_id = "composable"
|
||||
pc_least_privilege = false
|
||||
pc_capabilities = []
|
||||
debug = false
|
||||
etw_audit = true
|
||||
wxc_exec_path = "C:\\mxc\\wxc-exec.exe"
|
||||
backend = "process_container"
|
||||
# Administrator opt-in for per-sandbox commands and working directories.
|
||||
allow_driver_config = true
|
||||
etw_audit = true
|
||||
```
|
||||
|
||||
`etw_audit` defaults to `false`. When enabled, the gateway account must be an
|
||||
administrator or belong to the Windows Performance Log Users group. Workload
|
||||
commands and working directories remain sandbox-scoped and must be supplied in
|
||||
the `mxc` driver configuration when creating a sandbox.
|
||||
`etw_audit` defaults to `false`. Enabling it requires an administrator account
|
||||
or membership in Windows Performance Log Users. See
|
||||
[OCSF JSON Export](/observability/ocsf-json-export) for durable audit output.
|
||||
|
||||
`OPENSHELL_OCSF_JSON=1` enables the gateway's JSONL audit
|
||||
sink independently of the selected compute driver. Set `OPENSHELL_OCSF_LOG_DIR`
|
||||
to override the default `%PROGRAMDATA%\OpenShell\logs` directory on Windows
|
||||
or `$XDG_STATE_HOME/openshell/logs` on Unix. Prefer the gateway's configured
|
||||
`ocsf_log` output for retention controls and loss metrics.
|
||||
|
||||
The driver records executable identity in process audit events and omits raw
|
||||
command arguments because they can contain credentials or personal data. See
|
||||
[OCSF JSON Export](/observability/ocsf-json-export) for durable Windows audit
|
||||
output.
|
||||
Follow the [Windows configuration guide](https://github.com/NVIDIA/OpenShell/blob/windows/docs/how-it-works/gateways/configuration.mdx#mxc)
|
||||
for host prerequisites, TLS setup, sandbox creation, and runtime limitations.
|
||||
|
||||
### Docker
|
||||
|
||||
|
||||
@@ -21,7 +21,7 @@ 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 workloads on x64 or ARM64. |
|
||||
|
||||
## Select a Compute Driver
|
||||
|
||||
|
||||
Reference in New Issue
Block a user