mirror of
https://github.com/NVIDIA/OpenShell.git
synced 2026-10-31 07:44:57 +08:00
docs(windows): align MXC documentation with the implementation (#4646)
Complete the MXC documentation corrections after #4757. Update the Windows test reference, policy and runtime limitations, RFC runtime binary names and socket-owner lookup, and CLI guidance for live network policy updates. Closes #4645. Signed-off-by: Shailendra Singh <shailendras@nvidia.com>
This commit is contained in:
Shailendra Singh
@@ -73,9 +73,11 @@ The wrapper adds missing rustup targets and preserves an inherited
|
||||
the setting. It does not install Visual Studio, Rust, Docker, Kubernetes,
|
||||
Podman, WSL, Hyper-V, or VM tooling.
|
||||
|
||||
On Windows, `mise run pre-commit` routes `rust:check`, `rust:lint`, and
|
||||
`test:rust` through this wrapper for the host-native target. The shared task
|
||||
definitions retain their existing Unix commands. Only tests for Linux glibc
|
||||
On Windows, `mise run pre-commit` routes its `rust:lint` dependency through
|
||||
this wrapper for the host-native target. The separate `rust:check` and
|
||||
`test:rust` tasks also use the wrapper; `pre-commit` itself runs formatting
|
||||
and lint checks. The shared task definitions retain their existing Unix
|
||||
commands. Only tests for Linux glibc
|
||||
installer behavior, Linux build-environment shell helpers, and Linux
|
||||
service/RPM packaging assets skip on Windows. The Windows Clippy command
|
||||
excludes unsupported runtime packages as top-level targets and allows only
|
||||
@@ -91,8 +93,10 @@ For ARM64, verify the Visual Studio instance contains the ARM64 MSVC tools,
|
||||
ARM64 Spectre-mitigated libraries, Clang tools, CMake tools, and a Windows SDK.
|
||||
Clang supplies host-native `libclang.dll` for `bindgen` and `clang-cl.exe` for
|
||||
ARM64 crypto dependencies such as `aws-lc-sys`. Native and
|
||||
x64-to-ARM64 builds use the official prebuilt Z3 5.1.0 static library for the
|
||||
target architecture. An x64-to-ARM64 check/build discovers and adds host-native
|
||||
x64-to-ARM64 builds use the official prebuilt Z3 5.1.0 import library and
|
||||
`libz3.dll` for the target architecture. Release build tasks stage that DLL
|
||||
beside the four executables; copy it with them to the runtime host.
|
||||
An x64-to-ARM64 check/build discovers and adds host-native
|
||||
Ninja to `PATH`, while the crypto crates select `clang-cl`. Use a short
|
||||
`CARGO_TARGET_DIR` if Windows path-length limits are reached.
|
||||
|
||||
@@ -117,9 +121,12 @@ Current focused unsupported-contract tests:
|
||||
|
||||
```text
|
||||
windows_builtin_compute_drivers_report_unsupported
|
||||
default_registry_contains_exactly_the_enabled_compute_drivers
|
||||
```
|
||||
|
||||
Run them with the architecture-specific focused task on the native host.
|
||||
That task also tests gateway library builds with no compute driver, MXC only,
|
||||
the Docker stub only, and MXC plus the Docker stub.
|
||||
|
||||
## Cargo Excludes
|
||||
|
||||
@@ -146,7 +153,7 @@ package-level tests are excluded as top-level targets.
|
||||
|
||||
The supervisor and supervisor-process packages now participate as top-level
|
||||
native check/test targets. Their portable session, attachment, and TCP readiness
|
||||
coverage does not enable a Windows isolation runtime.
|
||||
coverage does not qualify MXC isolation enforcement.
|
||||
|
||||
## Common Errors
|
||||
|
||||
@@ -204,20 +211,29 @@ blocked dependency.
|
||||
|
||||
### Focused tests report many filtered-out tests
|
||||
|
||||
This is expected for `windows:test:unsupported:x64`. Cargo runs one named test
|
||||
and filters the other `openshell-gateway` tests. Report these as filtered, not
|
||||
ignored.
|
||||
This is expected for `windows:test:unsupported:x64`. Each focused Cargo
|
||||
invocation runs one named contract and filters the other `openshell-gateway`
|
||||
tests. The task also runs four selective-feature library suites. Report
|
||||
filtered tests separately from ignored tests.
|
||||
|
||||
## Reporting Counts
|
||||
|
||||
`windows:test:x64`, `windows:test:arm64`, and the workspace test step in
|
||||
`windows:ci` use `cargo nextest run --profile ci --workspace` with
|
||||
`openshell-server/test-support` and the selected Z3 features. The CI profile
|
||||
disables fail-fast. Nextest does not run doc tests. Install the pinned
|
||||
Nextest tool with `mise install --locked github:nextest-rs/nextest` before
|
||||
running these tasks with `--skip-tools`.
|
||||
|
||||
Use the log summaries from:
|
||||
|
||||
| Log | Count source |
|
||||
|---|---|
|
||||
| `test-x86_64-pc-windows-msvc.log` | Full x64 workspace test pass. |
|
||||
| `test-aarch64-pc-windows-msvc.log` | Full native ARM64 workspace test pass. |
|
||||
| `test-x86_64-pc-windows-msvc-precommit.log` | Native x64 workspace Nextest run with server test support. |
|
||||
| `test-aarch64-pc-windows-msvc-precommit.log` | Native ARM64 workspace Nextest run with server test support. |
|
||||
| `test-x86_64-pc-windows-msvc-unsupported-*.log` | Focused unsupported-contract re-runs and filtered counts. |
|
||||
| `test-aarch64-pc-windows-msvc-unsupported-*.log` | Focused native ARM64 re-runs and filtered counts. |
|
||||
| `test-<target>-selective-*.log` | Gateway library tests for each selective compute-driver feature set. |
|
||||
|
||||
Separate:
|
||||
|
||||
|
||||
@@ -150,11 +150,14 @@ Install the software for the compute driver you use:
|
||||
|
||||
## Workload Images
|
||||
|
||||
OpenShell accepts standard Linux OCI images. The built-in default workload is
|
||||
Docker, Podman, Kubernetes, and MicroVM accept standard Linux OCI images. The built-in default workload is
|
||||
`nvcr.io/nvidia/base/ubuntu:24.04` for `linux/amd64` and `linux/arm64`. It is a
|
||||
minimal Ubuntu Noble userspace and does not bundle agent CLIs. Operators can
|
||||
change the default, and users can select an explicit image with `--from`.
|
||||
|
||||
Native Windows MXC runs host commands rather than OCI images. See the
|
||||
[Windows guide](https://github.com/NVIDIA/OpenShell/blob/windows/WINDOWS.md).
|
||||
|
||||
## Container Images
|
||||
|
||||
| Image | Reference | Pulled When |
|
||||
|
||||
@@ -33,6 +33,9 @@ specific time:
|
||||
| `network_policies` | Destinations each binary can reach, and the requests it can send. | Sandbox network proxy. | While the sandbox runs. |
|
||||
| `network_middlewares` | Additional inspection, transformation, or blocking of traffic that network rules allow. | Sandbox network proxy. | While the sandbox runs. |
|
||||
|
||||
For native Windows filesystem enforcement and proxy limitations, see
|
||||
[Windows policy controls](https://github.com/NVIDIA/OpenShell/blob/windows/WINDOWS.md#runtime-and-current-limits).
|
||||
|
||||
Filesystem, Landlock, process, and UI settings are fixed once the sandbox starts.
|
||||
Network rules and middleware can change while it runs, as described in [How
|
||||
Changes Take
|
||||
|
||||
@@ -3,7 +3,7 @@
|
||||
# SPDX-License-Identifier: Apache-2.0
|
||||
title: "Sandbox Runtimes"
|
||||
sidebar-title: "Runtimes"
|
||||
description: "Configure the Docker, Podman, MicroVM, or Kubernetes runtime that runs OpenShell sandboxes."
|
||||
description: "Configure the Docker, Podman, MicroVM, Kubernetes, or experimental Windows MXC runtime that runs OpenShell sandboxes."
|
||||
keywords: "Generative AI, Cybersecurity, AI Agents, Sandboxing, Docker, Podman, MicroVM, Kubernetes, MXC, Reference"
|
||||
position: 4
|
||||
---
|
||||
@@ -37,7 +37,7 @@ compute_driver = "docker"
|
||||
|
||||
Every gateway TOML file must start with the `[openshell]` table and `version = 2`, or `openshell-gateway config preflight` rejects it with `missing_version`. The remaining examples on this page show only the tables they change.
|
||||
|
||||
When `compute_driver` is unset, the gateway auto-detects Kubernetes, then Podman, then Docker. The VM driver is never auto-detected.
|
||||
When `compute_driver` is unset, the gateway auto-detects Kubernetes, then Podman, then Docker. The VM and MXC drivers are never auto-detected.
|
||||
|
||||
Configure driver-specific values, such as images, endpoints, and sizing, under `[openshell.drivers.<name>]`. See the [Gateway Configuration File](/how-it-works/gateways/configuration) reference for every option.
|
||||
|
||||
|
||||
@@ -15,7 +15,7 @@ links:
|
||||
OpenShell runs natively on Windows 11 by using Microsoft Execution Containers
|
||||
(MXC, through `wxc-exec.exe`) as an RFC 0012 isolation backend. The gateway's
|
||||
in-process MXC compute driver provisions a host
|
||||
`openshell-supervisor --role=isolation-backend` and an `openshell-sandbox`
|
||||
`openshell-supervisor --role=isolation-backend` and an `openshell-windows-sandbox`
|
||||
boundary inside each ProcessContainer.
|
||||
|
||||
The authenticated Sandbox Protocol is the only runtime control and forwarding
|
||||
@@ -62,7 +62,7 @@ authenticated paths instead of MXC-only side channels.
|
||||
flowchart TD
|
||||
Gateway[Gateway / in-process MXC driver]
|
||||
Supervisor[openshell-supervisor<br/>role=isolation-backend]
|
||||
Sandbox[openshell-sandbox<br/>inside MXC ProcessContainer]
|
||||
Sandbox[openshell-windows-sandbox<br/>inside MXC ProcessContainer]
|
||||
Workload[Workload process tree]
|
||||
|
||||
Gateway -->|policy + launch authentication| Supervisor
|
||||
@@ -96,6 +96,12 @@ The boundary terminates owned workload processes if no authenticated supervisor
|
||||
recovers within the bounded reconnect deadline. Host auth bundles and runtime
|
||||
descriptors are stored beneath an owner-only Windows DACL.
|
||||
|
||||
The current Windows development implementation temporarily asserts the
|
||||
required no-unmanaged-egress and revocation guarantees for compatibility
|
||||
testing. These assertions are not verified enforcement evidence. Broad host
|
||||
loopback remains outside exclusive proxy mediation, and passing runtime tests
|
||||
does not establish production qualification.
|
||||
|
||||
### Networking and credentials
|
||||
|
||||
MXC denies direct Internet egress and permits the loopback route used by the
|
||||
@@ -109,12 +115,13 @@ children. The supervisor retains private CA keys and provider secrets, applies
|
||||
network policy, and refreshes provider state through the ordinary session.
|
||||
|
||||
The listener rejects missing, duplicate, malformed, and cross-generation proxy
|
||||
authorization before policy evaluation. The initial implementation assigns
|
||||
requests to the admitted main workload binary because Windows socket-owner
|
||||
identity is not yet carried by the explicit-proxy transport. Policies that rely
|
||||
on different network rights for descendant executables are therefore outside
|
||||
the initial enforcement contract. The loopback exception also does not isolate
|
||||
unrelated services bound to `127.0.0.1`; the gateway host remains trusted.
|
||||
authorization before policy evaluation. The Windows backend resolves the
|
||||
socket-owning PID with `GetExtendedTcpTable`, obtains its executable path with
|
||||
`QueryFullProcessImageNameW`, hashes the executable, and rechecks ownership.
|
||||
The proxy denies missing, ambiguous, or changed ownership. Network rules must
|
||||
authorize the child executable opening the connection, not only its launcher.
|
||||
The loopback exception still does not isolate unrelated services bound to
|
||||
`127.0.0.1`; the gateway host remains trusted.
|
||||
|
||||
### Process lifecycle and forwarding
|
||||
|
||||
@@ -129,9 +136,11 @@ resize is deferred; non-terminal exec and byte-stream I/O are supported first.
|
||||
|
||||
### Configuration and packaging
|
||||
|
||||
The Windows release contains `openshell-gateway.exe`, `openshell.exe`,
|
||||
`openshell-supervisor.exe`, and `openshell-sandbox.exe`. The runtime binaries
|
||||
default to siblings of the gateway and may be overridden for development.
|
||||
The Windows source build produces `openshell-gateway.exe`, `openshell.exe`,
|
||||
`openshell-supervisor.exe`, and `openshell-windows-sandbox.exe`, and stages the
|
||||
matching `libz3.dll` beside them. The Windows workflow does not publish these
|
||||
artifacts. The runtime binaries default to siblings of the gateway and may be
|
||||
overridden for development.
|
||||
Gateway TLS uses the gateway-owned guest certificate bundle.
|
||||
|
||||
The MXC driver configuration contains only host/runtime settings. Workload
|
||||
@@ -208,8 +217,6 @@ diverge by platform.
|
||||
|
||||
## Open questions
|
||||
|
||||
- Which Windows API should provide race-resistant socket-owner executable
|
||||
identity for per-descendant binary network policy?
|
||||
- Should MXC restart recovery persist enough generation metadata to reconnect,
|
||||
or should startup always terminate and recreate orphaned ProcessContainers?
|
||||
- What ConPTY surface is required before Windows interactive exec is considered
|
||||
|
||||
@@ -26,7 +26,7 @@ This is your primary fallback. Use it freely -- the CLI's help output is authori
|
||||
## Prerequisites
|
||||
|
||||
- `openshell` is on the PATH. Follow the published [installation guide](https://docs.nvidia.com/openshell/latest/about/installation.md) when it is not installed.
|
||||
- A reachable OpenShell gateway backed by Docker, Podman, Kubernetes, or the experimental VM driver
|
||||
- A reachable OpenShell gateway backed by Docker, Podman, Kubernetes, VM, or the experimental native Windows MXC driver
|
||||
- Docker is running only when using BYOC local builds or a Docker-backed gateway
|
||||
- For Kubernetes deployments: `kubectl` and Helm access to the target cluster
|
||||
|
||||
@@ -94,6 +94,12 @@ attachment and delete its sandbox after the service exits.
|
||||
|
||||
When supplying `--name`, use a portable DNS-1123 label: at most 63 lowercase alphanumeric or `-` characters, beginning and ending with an alphanumeric character. The Kubernetes driver rejects uppercase letters, underscores, dots, and other names that cannot become Kubernetes resource labels.
|
||||
|
||||
For native Windows MXC, supply the Windows command and absolute working
|
||||
directory through `--driver-config-json` and use `--detach`. The gateway
|
||||
administrator must enable caller driver configuration. Foreground attachment
|
||||
is rejected before provisioning; `--no-tty` alone does not request detachment.
|
||||
See [MXC configuration and limitations](https://docs.nvidia.com/openshell/latest/how-it-works/gateways/configuration#mxc).
|
||||
|
||||
Provider attachment is explicit. Name each provider with `--provider`; the
|
||||
trailing command does not select or attach one. If the named provider does not
|
||||
exist but a profile with that ID is available, the CLI can create it from local
|
||||
@@ -635,7 +641,7 @@ Edit `current-policy.yaml` to allow the blocked actions. **For policy content au
|
||||
- Binary matching patterns
|
||||
- Ordered `network_middlewares`, host selection, HTTP request/response and WebSocket bindings, and `fail_open` or `fail_closed` behavior
|
||||
|
||||
`network_policies` and `network_middlewares` can be modified at runtime when the selected compute driver supports live policy updates. Use `--wait` to verify that the active runtime loaded the revision; do not infer enforcement from the gateway accepting the update. MXC rejects live policy replacement and merge updates; delete and recreate an MXC sandbox instead. If `filesystem_policy`, `landlock`, or `process` need changes, the sandbox must be recreated. Built-in middleware such as `openshell/regex` needs no gateway registration. An operator-run middleware must already be registered under `[[openshell.supervisor.middleware]]`; changing that static registration requires a gateway restart.
|
||||
`network_policies` and `network_middlewares` can be modified at runtime through the shared supervisor. Use `--wait` to verify that the active runtime loaded the revision; do not infer enforcement from the gateway accepting the update. On MXC, network rules govern explicit-proxy traffic; direct host-loopback access and native live-revocation qualification remain documented limitations. If `filesystem_policy`, `landlock`, `process`, or `ui` need changes, the sandbox must be recreated. Built-in middleware such as `openshell/regex` needs no gateway registration. An operator-run middleware must already be registered under `[[openshell.supervisor.middleware]]`; changing that static registration requires a gateway restart.
|
||||
|
||||
Middleware can inspect HTTP requests, HTTP responses, or client WebSocket text
|
||||
messages when the implementation advertises the matching binding. The built-in
|
||||
|
||||
Reference in New Issue
Block a user