OpenShell/docs/about/support-matrix.mdx

---
# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0
title: "Support Matrix"
description: ""
position: 5
---

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](https://github.com/NVIDIA/OpenShell/blob/main/rfc/0014-release-stability/README.md)
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](https://github.com/NVIDIA/OpenShell/blob/main/deploy/helm/openshell/README.md). | 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](https://docs.kernel.org/security/landlock.html) | 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 &lt; 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](/about/run-your-first-agent) for the image, provider, and policy
workflow.