trending/OpenShell
1
0
Fork 0
mirror of https://github.com/NVIDIA/OpenShell.git synced 2026-10-04 16:39:35 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
pull-request/3401
OpenShell/docs/reference/support-matrix.mdx
T
Akram Ben AissiEvan LezarDrew Newberry
 50230616d5 refactor(runtime): retire Community image dependencies (#3386) 
* feat(sandbox): default to official Alpine sandbox image

default_sandbox_image() now returns docker.io/library/alpine:3.22, a generic
version-qualified official image, so a fresh install no longer depends on the
community sandbox image catalog. All compute drivers (docker, podman,
kubernetes, vm) inherit this fallback.

Part of #3116.

Signed-off-by: Akram
Signed-off-by: Akram <akram.benaissi@gmail.com>

* feat(deploy): default deployment configs to the official Alpine sandbox image

Update the shared gateway default_image, Helm chart values, the standalone
Kubernetes manifest, and the dev gateway task scripts to use
docker.io/library/alpine:3.22 instead of the community base image, consistent
with default_sandbox_image(). GPU e2e image-build base is left unchanged (CUDA
needs a glibc base).

Part of #3116.

Signed-off-by: Akram
Signed-off-by: Akram <akram.benaissi@gmail.com>

* feat(driver): default to numeric non-root identity for USER-less images

With the default sandbox image now Alpine, images that declare no OCI USER
must start instead of being rejected. When the image declares no USER and
the policy requests none, the Podman and Docker drivers now supply a numeric
non-root identity (DEFAULT_SANDBOX_UID/GID = 1000) instead of rejecting,
matching the numeric-identity behavior of the Kubernetes and VM drivers. The
supervisor's resolved-identity path runs the sandbox as a synthesized
non-root account without the account existing in the image. Images that
declare a USER keep the OCI resolution path unchanged.

Part of #3116.

Signed-off-by: Akram <akram.benaissi@gmail.com>
Signed-off-by: Evan Lezar <elezar@nvidia.com>

* test(conformance): use Alpine workload image

Signed-off-by: Evan Lezar <elezar@nvidia.com>

* refactor(policy): drop community image /app path from default policy

The restrictive default policy granted read-only access to /app, a directory
that only existed in the community base image. A generic Alpine default has no
/app, so remove it. Landlock best-effort already ignores absent paths; this
just stops advertising a community-specific layout in the default.

Part of #3116.

Signed-off-by: Akram
Signed-off-by: Akram <akram.benaissi@gmail.com>

* docs(config): document Alpine default images

Signed-off-by: Evan Lezar <elezar@nvidia.com>

* fix(podman): report early sandbox termination

Signed-off-by: Evan Lezar <elezar@nvidia.com>

* fix(podman): initialize rootless workspace ownership

Signed-off-by: Evan Lezar <elezar@nvidia.com>

* fix(sandbox): qualify NVIDIA Ubuntu default

Signed-off-by: Drew Newberry <anewberry@nvidia.com>

* fix(podman): initialize rootful default workspace

Signed-off-by: Drew Newberry <anewberry@nvidia.com>

* feat(sftp): add native sandbox adapter

Signed-off-by: Drew Newberry <anewberry@nvidia.com>

* fix(sftp): gate runtime helper support to Linux

Signed-off-by: Drew Newberry <anewberry@nvidia.com>

* fix(sftp): support standard OpenSSH file operations

Signed-off-by: Drew Newberry <anewberry@nvidia.com>

* fix(sftp): harden rename and special file handling

Signed-off-by: Drew Newberry <anewberry@nvidia.com>

* refactor(runtime): remove community image dependencies

Signed-off-by: Drew Newberry <anewberry@nvidia.com>

* test(e2e): build provider readiness tool fixture

Signed-off-by: Drew Newberry <anewberry@nvidia.com>

* fix(e2e): use a dedicated Noble fixture for Docker tests

Signed-off-by: Evan Lezar <elezar@nvidia.com>

---------

Signed-off-by: Akram
Signed-off-by: Akram <akram.benaissi@gmail.com>
Signed-off-by: Evan Lezar <elezar@nvidia.com>
Signed-off-by: Drew Newberry <anewberry@nvidia.com>
Co-authored-by: Evan Lezar <elezar@nvidia.com>
Co-authored-by: Drew Newberry <anewberry@nvidia.com>
2026-09-22 14:43:51 +02:00

117 lines
7.0 KiB
Plaintext
Raw Permalink Blame History

---
# 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.
## 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+.
## 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.
## Compute Drivers
The gateway can manage sandboxes through several compute drivers.
| Compute Driver | 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 |
| 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 |
|---|---|
| `image.repository` / `image.tag` | Override the gateway image reference. |
| `server.sandboxImage` | Override the default 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. |
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.
On macOS, these kernel modules run inside the Docker Desktop Linux VM, not on the host kernel.
## Agent Compatibility
For the full list of supported agents and their default policy coverage, refer to the [Supported Agents](/about/supported-agents) page.
Reference in New Issue View Git Blame Copy Permalink