Support Matrix | NVIDIA OpenShell

This page lists the host platform, compute driver, software, runtime, and kernel requirements for running OpenShell.

Releases

OpenShell publishes dev, pre-release, and stable builds for different stages of the release cycle. Use a stable release for production deployments.

Release	Publication	Intended use
Dev	Built from every commit to `main` that passes normal CI. The floating `dev` alias points to the newest build.	Testing upcoming functionality. Dev builds enable development features and have not passed release qualification.
Pre-release	Built nightly when `main` has changed and normal CI passes. Versions use the form `X.Y.Z-pre.N`.	Validating the immutable artifact set proposed for the next stable release. Pre-releases use the stable feature set but may not have passed qualification.
Stable	Promoted from a pre-release that passes conformance, upgrade, API compatibility, artifact, and security checks. Versions use the form `X.Y.Z`.	Production use within this support matrix.

Tagged stable releases generally go out every week. OpenShell targets Tuesday publication when there are changes and every blocking qualification check passes. A security release may ship sooner.

Stable APIs and other Stable interfaces remain backward-compatible across patch releases. Patch releases can contain fixes and additive functionality. A breaking change to a Stable interface requires a minor release with notice and migration guidance. Interfaces marked Experimental may change or be removed in a patch release.

OpenShell provides security and critical reliability updates for the latest minor release and the previous minor release, also called N-1. Support applies to the newest patch on each maintained minor line. Update to that patch to receive fixes; OpenShell does not issue fixes for every older patch. Maintenance updates do not backport features.

Refer to RFC 0014 for the complete release and compatibility policy.

Supported Platforms

OpenShell publishes multi-architecture gateway images for linux/amd64 and linux/arm64. The CLI, policy prover, package-managed gateway, and standalone gateway binary are supported on the following host platforms:

Platform	Architecture	Status
Linux (Debian/Ubuntu)	x86_64 (amd64)	Supported
Linux (Debian/Ubuntu)	aarch64 (arm64)	Supported
macOS (Docker Desktop)	Apple Silicon (arm64)	Supported
Windows (WSL 2 + Docker Desktop)	x86_64	Experimental

On Linux, the openshell CLI is a static musl binary and does not require glibc at runtime.

Standalone Gateway Binary

OpenShell publishes standalone openshell-gateway release assets for manual download on these platforms:

Platform	Artifact pattern
Linux x86_64 (amd64)	`openshell-gateway-x86_64-unknown-linux-gnu`
Linux aarch64 (arm64)	`openshell-gateway-aarch64-unknown-linux-gnu`
macOS Apple Silicon	`openshell-gateway-aarch64-apple-darwin`

These artifacts are attached to GitHub releases. Kubernetes deployments should use the Helm chart and the published gateway image.

On Linux, openshell-gateway requires glibc 2.28 or newer. Compatible systems include, for example, Ubuntu 20.04+, RHEL 8+, Rocky Linux 8+, Amazon Linux 2023+, and Fedora 32+.

Sandbox Runtime Binary

openshell-sandbox is the trusted workload-side runtime binary. It runs inside the sandbox boundary, starts and owns the agent process tree, observes executable identity, and sends mediated TCP and DNS operations to the supervisor. It does not hold provider credentials or open upstream connections; those responsibilities remain with the supervisor outside the workload boundary.

OpenShell publishes static musl builds for the Linux architectures supported by the sandbox runtime:

Platform	Artifact pattern
Linux x86_64 (amd64)	`openshell-sandbox-x86_64-unknown-linux-musl.tar.gz`
Linux aarch64 (arm64)	`openshell-sandbox-aarch64-unknown-linux-musl.tar.gz`

The static binary does not depend on the agent image’s libc. Each stable release also publishes openshell-sandbox-checksums-sha256.txt for the standalone archives.

Supported runtimes deliver this binary automatically and separately from the agent image. Docker and Podman stage it into the workload, Kubernetes uses the trusted sandbox runtime image, and the VM runtime embeds it in the guest rootfs. Most users do not invoke the binary directly. Use the standalone archives when integrating a runtime or preparing artifacts for an air-gapped environment, and keep the sandbox binary aligned with the rest of the OpenShell release.

Standalone Policy Prover

OpenShell publishes standalone openshell-prover release assets for manual download on these platforms:

Platform	Artifact pattern
Linux x86_64 (amd64)	`openshell-prover-x86_64-unknown-linux-musl.tar.gz`
Linux aarch64 (arm64)	`openshell-prover-aarch64-unknown-linux-musl.tar.gz`
macOS Apple Silicon	`openshell-prover-aarch64-apple-darwin.tar.gz`

These artifacts are attached to GitHub releases. The Linux binaries are static and do not require glibc. All prover archives include the required solver linkage.

Runtimes

The gateway can manage sandboxes through several runtimes.

Runtime	Status	Notes
Docker	Supported for local development and single-machine gateways.	Requires Docker Desktop or Docker Engine on the gateway host.
Podman	Supported for rootless local and workstation workflows.	Requires a Podman-compatible socket and rootless networking setup.
Kubernetes	Supported through the OpenShell Helm chart.	Requires a Kubernetes cluster supplied by the operator.
MicroVM	Supported for VM-backed sandboxes.	Uses the VM compute driver and libkrun-based runtime.

Software Prerequisites

Install the software for the compute driver you use:

Component	Minimum Version	Notes
Docker Desktop or Docker Engine	28.0	Required for Docker-backed gateways, local image builds, and Docker development workflows.
Podman	5.x	Required for Podman-backed gateways.
Kubernetes	1.29	Required for Helm deployments and Kubernetes sandbox scheduling.
Helm	3.x	Required to install `deploy/helm/openshell`.
kubectl	Compatible with your cluster	Required for Kubernetes operational inspection and secret creation.
Host virtualization	Host dependent	Required for MicroVM-backed gateways. MicroVM uses Hypervisor.framework on macOS and KVM on Linux.

Workload Images

OpenShell accepts 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.

Container Images

Image	Reference	Pulled When
Gateway	`ghcr.io/nvidia/openshell/gateway:latest`	Helm chart install or upgrade, or standalone container deployment
Sandbox runtime	`ghcr.io/nvidia/openshell/sandbox:latest`	A supported runtime stages `openshell-sandbox` into a workload boundary
Default workload	`nvcr.io/nvidia/base/ubuntu:24.04`	First sandbox creation unless preloaded or overridden

The Helm chart in deploy/helm/openshell deploys the gateway workload, service account, service, optional persistent storage, and network policy for Kubernetes. It defaults to a StatefulSet for SQLite-backed installs and can render a Deployment for external database-backed installs.

To override the default image references, use Helm values:

Helm value	Purpose
`global.image.registry` / `global.image.tag` / `global.image.pullPolicy`	Override shared image settings for the gateway, supervisor, and trusted sandbox runtime.
`gateway.image.registry` / `gateway.image.repository` / `gateway.image.tag` / `gateway.image.digest`	Override the gateway image reference.
`supervisor.image.registry` / `supervisor.image.repository` / `supervisor.image.tag` / `supervisor.image.digest`	Override the supervisor image reference.
`sandbox.image.repository` / `sandbox.image.tag` / `sandbox.image.digest`	Override the default workload sandbox image.

Kernel Requirements

The sandbox boundary requires the following Linux kernel facilities, including when it runs inside a container or microVM:

Module	Requirement	Details
Landlock LSM	Required	ABI 3 or newer, introduced in Linux 6.2, with Landlock enabled. The mandatory baseline protects private channel and bootstrap files, including against truncation. A filesystem policy’s `best_effort` setting never disables this baseline.
seccomp	Required	Nested user-notification filters and atomic `SECCOMP_IOCTL_NOTIF_ADDFD` with `SECCOMP_ADDFD_FLAG_SEND`, usable under the runtime’s existing seccomp profile without added capabilities. The sandbox actively probes these operations before admitting the workload.
Task-memory access	Required	The non-dumpable broker must be able to read and write a same-UID, dumpable workload child’s memory through `process_vm_readv` / `process_vm_writev` or `/proc/<pid>/mem`. The sandbox actively probes the production parent-to-child topology before admitting the workload.
seccomp `WAIT_KILLABLE_RECV`	Recommended (Linux 5.19+)	Keeps a notified workload thread in a kill-only wait so the broker can safely write mediated results into workload memory. Without it (kernels < 5.19, for example RHEL 9.x / RHCOS 5.14) the sandbox still starts, in a reduced legacy read-only mode described below.

A kernel version alone does not establish support. A disabled Landlock LSM or a runtime profile that blocks the required seccomp operations causes launch to fail closed. An upstream Linux 6.2 or newer kernel provides the required Landlock ABI; distribution backports must pass the same active qualification. The broker remains non-dumpable during qualification. A runtime may satisfy task-memory access through /proc/<pid>/mem even when its kernel omits the process_vm_readv and process_vm_writev system calls; OpenShell qualifies the same parent-to-executed-child access shape used by mediated workloads.

Legacy read-only mode (kernels before Linux 5.19)

SECCOMP_FILTER_FLAG_WAIT_KILLABLE_RECV was added in Linux 5.19. On older kernels — notably RHEL 9.x and RHCOS, which ship a 5.14 kernel — the sandbox cannot install a kill-only listener, so it falls back to a plain listener and runs in a legacy read-only cancellation mode. The sandbox starts and enforces the full isolation boundary (Landlock, the outer NetworkPolicy fence, DNS and TCP authorization); the only difference is that the broker refuses the mediated operations that write results back into workload memory, failing them closed with EOPNOTSUPP:

getpeername;
accept / accept4 when a non-null peer-address argument is supplied (a null address argument still works);
sendmmsg paths that write per-message lengths back to the caller.

Socket creation, connect, bind, listen, sendto, and sendmsg are unaffected. Outbound-oriented workloads generally run unchanged; server workloads whose accept wrappers request the peer address will see EOPNOTSUPP until the node runs a kernel that provides WAIT_KILLABLE_RECV (Linux 5.19+, or a distribution backport). The selected mode is reported in the sandbox qualification output as seccomp_listener_mode (killable or legacy_read_only).

On macOS, these kernel modules run inside the Docker Desktop Linux VM, not on the host kernel.

Agent Workloads

OpenShell runs agents and tools that you install in a user-owned OCI image. The image must satisfy the selected compute driver’s platform requirements. Refer to Run Your First Agent for the image, provider, and policy workflow.