Drew Newberry
f97270f988
* refactor(docker): rename server image to gateway Rename Dockerfile.server to Dockerfile.gateway and update all image references from openshell/server to openshell/gateway across Helm charts, Kubernetes manifests, mise tasks, build/deploy scripts, CI workflows, and documentation. The underlying Rust binary (navigator-server) is unchanged -- this rename only affects the Docker image name and Dockerfile. * fix: catch remaining server->gateway references in docs and comments
3.6 KiB
Support Matrix
This page lists the platform, software, runtime, and kernel requirements for running OpenShell.
Supported Platforms
OpenShell publishes multi-architecture container images for linux/amd64 and linux/arm64. The CLI is 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 |
| macOS (Docker Desktop) | Intel (amd64) | Supported |
| Windows (WSL 2 + Docker Desktop) | x86_64 | Untested |
Software Prerequisites
The following software must be installed on the host before using the OpenShell CLI:
| Component | Minimum Version | Notes |
|---|---|---|
| Python | 3.12 | Python 3.12 and 3.13 are supported. |
| uv | 0.9 | Used to install the CLI (uv pip install openshell). |
| Docker Desktop or Docker Engine | — | Must be running before any openshell command. No minimum version is enforced. |
Sandbox Runtime Versions
The base sandbox container image ships the following components. These versions apply to sandboxes created with the default image (ghcr.io/nvidia/openshell/sandbox).
| Component | Version |
|---|---|
| Base OS | Debian Bookworm |
| Python | 3.12.13 |
| Node.js | 22.22.1 |
| npm | 11.11.0 |
| uv | 0.10.8 |
| Claude Code | Latest (installed at image build time) |
| OpenCode | 1.2.18 |
| Codex | 0.111.0 |
Container Images
OpenShell uses several container images that are pulled automatically during gateway startup and sandbox creation. All images are published for linux/amd64 and linux/arm64.
| Image | Registry | Reference | Pulled When |
|---|---|---|---|
| Cluster | ghcr.io | ghcr.io/nvidia/openshell/cluster:latest |
openshell gateway start |
| Gateway | ghcr.io | ghcr.io/nvidia/openshell/gateway:latest |
Cluster startup (via Helm chart) |
| Sandbox | ghcr.io | ghcr.io/nvidia/openshell/sandbox:latest |
First sandbox creation (via Helm chart) |
| Community sandboxes | GHCR | ghcr.io/nvidia/openshell-community/sandboxes/{name}:latest |
openshell sandbox create --from <name> |
The cluster image is based on rancher/k3s:v1.35.2-k3s1 and bundles the Helm charts and Kubernetes manifests required to bootstrap the control plane. The server and sandbox images are pulled separately at runtime.
To override the default image references, set the following environment variables:
| Variable | Purpose |
|---|---|
OPENSHELL_CLUSTER_IMAGE |
Override the cluster image reference. |
OPENSHELL_COMMUNITY_REGISTRY |
Override the registry for community sandbox images. |
Kernel Requirements
OpenShell enforces sandbox isolation through two Linux kernel security modules:
| Module | Requirement | Details |
|---|---|---|
| Landlock LSM | Recommended | Enforces filesystem access restrictions at the kernel level. The best_effort compatibility mode uses the highest Landlock ABI the host kernel supports. The hard_requirement mode fails sandbox creation if the required ABI is unavailable. |
| seccomp | Required | Filters dangerous system calls. Available on all modern Linux kernels (3.17+). |
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 table.