mirror of
https://github.com/NVIDIA/OpenShell.git
synced 2026-10-31 07:44:57 +08:00
docs(windows): document the Windows implementation and release branch (#4757)
Supply WINDOWS.md and CI.md#windows-validation for the links introduced by #4758. Apply its reviewed platform guidance, preserve the gateway example, and include the linked ETW attribution limitation. Keep the full-validation examples aligned with architecture-specific MXC E2E tasks and immediate exit-code checks. Closes #4755. Signed-off-by: Shailendra Singh <shailendras@nvidia.com>
This commit is contained in:
Shailendra Singh
@@ -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 local checkout to the latest upstream GitHub `windows` branch.
|
||||
- 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`,
|
||||
@@ -150,13 +157,13 @@ Out of scope:
|
||||
## Recommended Checkout Flow
|
||||
|
||||
From a fork checkout where `upstream` points to the official
|
||||
`NVIDIA/OpenShell` GitHub repository, use:
|
||||
`NVIDIA/OpenShell` GitHub repository, refresh the Windows branch:
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
@@ -181,6 +188,7 @@ The lane targets a Windows host with Visual Studio Build Tools and rustup.
|
||||
| Windows SDK | `where.exe rc.exe` from a Developer PowerShell | Install an SDK containing target libraries and ARM64 tools. |
|
||||
| Rust via rustup | `rustc --version` | Add each target being validated: `x86_64-pc-windows-msvc` and/or `aarch64-pc-windows-msvc`. The wrapper also adds the selected target. |
|
||||
| mise | `mise --version` | Used as a task runner only. |
|
||||
| cargo-nextest | `cargo nextest --version` | Required by `windows:test:x64`, `windows:test:arm64`, and `windows:ci`. Install the pinned tool with `mise install --locked github:nextest-rs/nextest` before using `--skip-tools`, as the Windows workflow does. |
|
||||
| Git | `git --version` | Needed for checkout and sync work. |
|
||||
| PowerShell | `$PSVersionTable.PSVersion` | Windows PowerShell 5.1 works; PowerShell 7 is quieter with mise shell hooks. |
|
||||
|
||||
@@ -195,7 +203,7 @@ from this skill.
|
||||
| `OPENSHELL_MXC_SKIP_ARM64` | `0` | Set to `1` to skip ARM64 when using `all` tasks. |
|
||||
| `OPENSHELL_WINDOWS_BUILD_JOBS` | `CARGO_BUILD_JOBS`, then `4` | Positive Cargo job limit used by the wrapper. |
|
||||
| `CARGO_TARGET_DIR` | `target` under repo root | Override Cargo output location. Use a short absolute path when x64-to-ARM64 builds approach Windows path-length limits. |
|
||||
| `Z3_LIBRARY_PATH_OVERRIDE` | unset | Directory containing an x64 system `libz3.lib`; not valid for ARM64. |
|
||||
| `Z3_LIBRARY_PATH_OVERRIDE` | unset | Directory containing target-compatible system `libz3.lib` and `libz3.dll`, used instead of the prebuilt download. |
|
||||
| `Z3_SYS_Z3_HEADER` | unset | Full `z3.h` path required with a system Z3 library. |
|
||||
| `Z3_SYS_Z3_VERSION` | `5.1.0` | Pinned official prebuilt Z3 release selected by the wrapper. |
|
||||
| `READ_ONLY_GITHUB_TOKEN` | unset | Optional token for the Z3 release lookup; GitHub Actions supplies `github.token`. |
|
||||
@@ -237,15 +245,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"
|
||||
@@ -253,6 +273,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:
|
||||
|
||||
@@ -260,7 +283,7 @@ order:
|
||||
2. ARM64 check, unless `OPENSHELL_MXC_SKIP_ARM64=1`.
|
||||
3. x64 release build.
|
||||
4. ARM64 release build, unless skipped.
|
||||
5. Native x64 workspace tests.
|
||||
5. Native x64 workspace tests through Nextest's `ci` profile with `openshell-server/test-support` enabled.
|
||||
6. Focused unsupported-driver contract tests.
|
||||
7. Artifact reporting.
|
||||
|
||||
@@ -294,9 +317,10 @@ Run `rust:lockfiles:check`, `sdk:ts:ci`, and `go:ci` through the Windows-aware
|
||||
tasks when validating those surfaces. Do not count the Go
|
||||
Windows ARM64 race-detector exclusion or POSIX permission-bit skips as security
|
||||
coverage. SDK test dependencies must remain at their lockfile versions.
|
||||
Its Rust check, Clippy, and test dependencies enter the same MSVC environment
|
||||
for the native host target and use an inherited compiler wrapper when it is
|
||||
available. Linux glibc
|
||||
Its Clippy dependency enters the MSVC environment for the native host target
|
||||
and uses an inherited compiler wrapper when it is available. The separate
|
||||
`rust:check` and `test:rust` tasks use the same wrapper; `pre-commit` runs
|
||||
formatting and lint checks, not those compile and test tasks. Linux glibc
|
||||
installer tests and Linux service/RPM packaging-asset tests skip explicitly;
|
||||
the Linux build-environment shell-helper test also skips; cross-platform checks
|
||||
continue to run. The blocking Windows Clippy pass excludes unsupported
|
||||
@@ -318,8 +342,8 @@ crypto dependency builds.
|
||||
| `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`, `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:x64` | Runs `cargo nextest run --profile ci --workspace` natively on x64 with `openshell-server/test-support` and the selected Z3 features; excludes unsupported Windows packages as top-level workspace targets. The profile disables fail-fast. |
|
||||
| `windows:test:arm64` | Runs the same Nextest CI profile and test-support features natively on ARM64, with 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. |
|
||||
@@ -469,7 +493,7 @@ When reporting `windows:ci`, distinguish these categories:
|
||||
- Passed tests from the full ARM64 workspace test log when run on a native
|
||||
ARM64 host.
|
||||
- The focused unsupported-contract re-run.
|
||||
- Explicit Cargo ignored tests, usually ignored doc examples.
|
||||
- Nextest skipped tests, including ignored real-MXC tests. Nextest does not run doc tests.
|
||||
- Tests hidden by `#[cfg(not(target_os = "windows"))]`; these often appear as
|
||||
`running 0 tests`, not as ignored tests.
|
||||
- Test-name `filtered out` counts from focused `cargo test` invocations.
|
||||
@@ -484,8 +508,8 @@ Useful log files:
|
||||
| `build-aarch64-pc-windows-msvc-check.log` | ARM64 check output. |
|
||||
| `build-x86_64-pc-windows-msvc-release.log` | x64 release build output. |
|
||||
| `build-aarch64-pc-windows-msvc-release.log` | ARM64 release build output. |
|
||||
| `test-x86_64-pc-windows-msvc.log` | Full native x64 workspace test output. |
|
||||
| `test-aarch64-pc-windows-msvc.log` | Full native ARM64 workspace test output. |
|
||||
| `test-x86_64-pc-windows-msvc-precommit.log` | Native x64 workspace Nextest output from `windows:test:x64` or `windows:ci`, with server test support. |
|
||||
| `test-aarch64-pc-windows-msvc-precommit.log` | Native ARM64 workspace Nextest output from `windows:test:arm64`, with server test support. |
|
||||
| `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. |
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
@@ -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` |
|
||||
|
||||
@@ -25,7 +25,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 +50,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 |
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
+22
-5
@@ -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\<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:
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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.
|
||||
|
||||
+44
@@ -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.
|
||||
|
||||
+114
@@ -0,0 +1,114 @@
|
||||
# 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 runtime host also needs the matching Visual C++ runtime.
|
||||
|
||||
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,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,11 +139,11 @@ 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 --detach
|
||||
```
|
||||
|
||||
The command and working directory are required. The working directory contains
|
||||
the generation-scoped bootstrap staging directory. When no generic canonical
|
||||
The command and absolute working directory are required. The working directory
|
||||
contains the generation-scoped bootstrap staging directory. When no generic canonical
|
||||
command is supplied, the driver passes `mxc.command` to the supervisor rather
|
||||
than starting a scratch workload. An explicit generic canonical command retains
|
||||
precedence. Environment belongs in `--env` or `--env-from`, not gateway configuration.
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -54,9 +54,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:
|
||||
|
||||
@@ -993,7 +993,8 @@ or `$XDG_STATE_HOME/openshell/logs` on Unix. Prefer the gateway's configured
|
||||
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.
|
||||
output and the current live ETW attribution limitation. Enabling capture does
|
||||
not establish complete sandbox audit coverage.
|
||||
|
||||
### Docker
|
||||
|
||||
@@ -1237,6 +1238,10 @@ runtime-selected profile.
|
||||
|
||||
### MXC
|
||||
|
||||
Use a build from the [`windows` branch](https://github.com/NVIDIA/OpenShell/tree/windows).
|
||||
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,10 +1251,13 @@ 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
|
||||
|
||||
For the Windows source, build prerequisites, and matching runtime binaries,
|
||||
see the [Windows build guide](https://github.com/NVIDIA/OpenShell/blob/windows/WINDOWS.md#build).
|
||||
|
||||
Copy `wxc-exec.exe` to a regular directory outside an MSIX or `WindowsApps`
|
||||
package directory. Package ACLs can prevent the gateway from starting it.
|
||||
If creation fails with `wxc-exec spawn failed: Access is denied. (os error 5)`,
|
||||
@@ -1312,7 +1320,19 @@ gateway operator. Caller-supplied commands and directories still require
|
||||
|
||||
The MXC driver requires MXC 1.0.0 and emits its stable directional network schema. Remove the retired `default_configuration_id` setting before upgrading; the gateway rejects it. The `isolation_session` backend remains unsupported.
|
||||
|
||||
Supply the workload command and working directory through `sandbox create --driver-config-json`, for example `{"mxc":{"command":["C:\\Windows\\System32\\cmd.exe","/d","/c","echo hello"],"cwd":"C:\\work"}}`. Both are required. Supply workload environment through `sandbox create --env` or `--env-from`; it is not part of gateway configuration.
|
||||
Supply the workload command and absolute working directory through
|
||||
`sandbox create --driver-config-json`. Both are required. From PowerShell,
|
||||
create a detached workload with a policy granting the required Windows paths:
|
||||
|
||||
```shell
|
||||
$config = '{"mxc":{"command":["C:\\Windows\\System32\\cmd.exe","/d","/c","echo hello"],"cwd":"C:\\work"}}'
|
||||
openshell sandbox create --name mxc-demo --detach --policy policy.yaml `
|
||||
--driver-config-json $config
|
||||
```
|
||||
|
||||
Supply workload environment through `sandbox create --env` or `--env-from`;
|
||||
it is not part of gateway configuration. The command runs from host files,
|
||||
not an OCI workload image.
|
||||
|
||||
Configure UI controls in the sandbox policy, not the `mxc` driver JSON:
|
||||
|
||||
@@ -1330,15 +1350,27 @@ 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. It resolves
|
||||
the socket-owning executable from the Windows kernel TCP table, hashes it,
|
||||
and rechecks ownership before policy evaluation. Allowing `cmd.exe` does not
|
||||
authorize a child `curl.exe`; missing, ambiguous, or changed socket ownership
|
||||
denies the request.
|
||||
|
||||
MXC denies direct Internet egress and permits the `127.0.0.1/32` route used by
|
||||
the authenticated transport and proxy. That exception permits direct access
|
||||
to unrelated host-local services outside the proxy. Treat the gateway host
|
||||
as trusted; per-binary network rules govern traffic through the proxy.
|
||||
|
||||
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.
|
||||
|
||||
Main launch and raw exec receive the authenticated proxy and installed CA
|
||||
environment. Exec uses the latest provider environment. The proxy identity
|
||||
uses the canonical workload command when supplied, falling back to the MXC
|
||||
driver command. Expired control credentials close open process and forwarding
|
||||
streams; renewed credentials update the connection deadline.
|
||||
environment. Exec uses the latest provider environment. A canonical workload
|
||||
command takes precedence over the MXC driver command for launch; proxy
|
||||
identity is resolved separately for each connection. Expired control
|
||||
credentials close open process and forwarding streams; renewed credentials
|
||||
update the connection deadline.
|
||||
|
||||
### MicroVM
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -56,7 +56,7 @@ the gateway into durable JSONL output:
|
||||
etw_audit = true
|
||||
```
|
||||
|
||||
```powershell
|
||||
```shell
|
||||
$env:OPENSHELL_OCSF_JSON = "1"
|
||||
# Optional; defaults to %PROGRAMDATA%\OpenShell\logs.
|
||||
$env:OPENSHELL_OCSF_LOG_DIR = "D:\OpenShell\audit"
|
||||
@@ -71,6 +71,15 @@ do not suppress records in this explicitly enabled audit sink.
|
||||
Prefer the `gateway.toml` output above for configured retention and loss metrics;
|
||||
enabling both sinks writes to both independently.
|
||||
|
||||
The ETW consumer requires an administrator account or membership in Windows
|
||||
Performance Log Users. Live sandbox attribution remains unqualified. On the
|
||||
tested ARM64 host, Windows Sandboxing events originate from the shared Appinfo
|
||||
broker, and the consumer cannot correlate them with the executor's PID and
|
||||
process generation, so live audit qualification fails even when the workload
|
||||
completes. Enabling ETW and JSONL output does not guarantee complete per-sandbox
|
||||
events. Use the separate `windows:test:mxc-audit` qualification
|
||||
task on a native Windows development host to check live coverage.
|
||||
|
||||
## Output Location
|
||||
|
||||
When `ocsf_json_enabled=true`, sandbox supervisors emit full OCSF JSON to stderr alongside shorthand output:
|
||||
|
||||
Reference in New Issue
Block a user