About NVIDIA OpenShell

Installation

View as Markdown

Install OpenShell on a local workstation or Kubernetes.

Install OpenShell

Install the CLI, policy prover, and a local gateway with one command:

curl -LsSf https://raw.githubusercontent.com/NVIDIA/OpenShell/main/install.sh | sh

The script picks a package for your platform and starts the gateway. Confirm the CLI can reach it:

openshell status

To install a specific release, set OPENSHELL_VERSION to a release tag. Release artifacts are also on the GitHub Releases page.

Prerelease and Development Builds

Use a prerelease candidate to evaluate an upcoming release, or the rolling development build to test the latest commit on main. These builds may change before the next stable release. The matching documentation is published in the development channel.

Prerelease packages are retained as GitHub Actions artifacts for 90 days and require an authenticated GitHub CLI session. The pre alias installs the latest prerelease:

gh auth login
curl -LsSf https://raw.githubusercontent.com/NVIDIA/OpenShell/main/install.sh | \
  OPENSHELL_VERSION=pre sh

The installer checks prerelease tags from newest to oldest, selects an unexpired artifact from a successful release run for the current platform, and downloads only that artifact. Installed packages keep the candidate’s exact version, such as 0.1.0-pre.3. Prerelease tags do not create entries on the GitHub Releases page. On Linux, prereleases and explicit release tags use Debian or RPM packages even if snap is installed.

The rolling dev release does not require GitHub authentication:

curl -LsSf https://raw.githubusercontent.com/NVIDIA/OpenShell/main/install.sh | \
  OPENSHELL_VERSION=dev sh

For Kubernetes, select the corresponding Helm chart version. Helm chart versions omit the leading v from release tags:

# Pin an exact candidate
helm upgrade --install openshell \
  oci://ghcr.io/nvidia/openshell/helm-chart \
  --version 0.1.0-pre.3
# Rolling development build
helm upgrade --install openshell \
  oci://ghcr.io/nvidia/openshell/helm-chart \
  --version 0.0.0-dev

Prerelease charts use exact <version>-pre.N versions. Development charts are also published as immutable 0.0.0-dev.<commit-sha> versions when you need to pin a specific commit.

Supported Runtimes

The local gateway auto-detects an available runtime. To pin one, set compute_driver in the gateway TOML file. See Sandbox Runtimes.

RuntimeRequirements
DockerDocker Desktop or Docker Engine 28.0 or later.
PodmanLinux with Podman 5.x, cgroups v2, and an active Podman user socket.
MicroVMHost virtualization: Hypervisor.framework on macOS or KVM on Linux.

macOS

The script installs OpenShell with Homebrew and runs the gateway as a Homebrew service at https://localhost:17670.

brew services list
brew services restart openshell

The gateway reads ~/.config/openshell/gateway.toml if it exists, otherwise the Homebrew config at $(brew --prefix)/var/openshell/gateway.toml.

Linux

The script uses the Snap package when snap is available. Otherwise, or when you set OPENSHELL_VERSION to a release tag, it installs a Debian package on Debian and Ubuntu or an RPM package on Fedora and RHEL. Linux packages require glibc 2.28 or newer.

The gateway runs as a systemd user service at https://127.0.0.1:17670 and reads ~/.config/openshell/gateway.toml.

systemctl --user status openshell-gateway
systemctl --user restart openshell-gateway
journalctl --user -u openshell-gateway -f

To keep the gateway running after you log out, enable linger:

sudo loginctl enable-linger $USER

Snap

The snap requires Docker Engine installed from your distribution or Docker’s package repository. The Docker snap is not compatible.

sudo snap install openshell

The snap does not migrate existing Debian, RPM, or Homebrew installs. Remove any existing installation first, then rerun the script with OPENSHELL_ACK_BREAKING_UPGRADE=1.

The gateway runs as a system service at http://127.0.0.1:17670 and reads /var/snap/openshell/common/gateway.toml.

The snap gateway allows unauthenticated access from the local host. Any local user or process can operate it. Do not expose it beyond the local host.

Snap refreshes do not restart the gateway, so active sandboxes keep running. Restart it to pick up a new version:

sudo systemctl restart snap.openshell.gateway

To install a locally built snap, connect its interfaces manually:

sudo snap install ./openshell_*.snap --dangerous
sudo snap connect openshell:log-observe
sudo snap connect openshell:system-observe
sudo snap connect openshell:docker :docker

Kubernetes

Deploy the gateway to a cluster with the OpenShell Helm chart. See Kubernetes Setup.

Validate Gateway Configuration

Check a gateway config file before restarting the service:

openshell-gateway config preflight --path ~/.config/openshell/gateway.toml

Preflight never changes the file. If the gateway reports a legacy schema, follow the schema version 2 migration steps.

Uninstall OpenShell

Homebrew:

brew services stop nvidia/openshell/openshell
brew uninstall nvidia/openshell/openshell
rm -rf "$(brew --prefix)/var/openshell"

Debian and Ubuntu:

systemctl --user disable --now openshell-gateway
sudo apt remove openshell
rm -rf "${XDG_STATE_HOME:-$HOME/.local/state}/openshell"

Fedora and RHEL:

systemctl --user disable --now openshell-gateway
sudo dnf remove openshell-gateway openshell-prover openshell
rm -rf "${XDG_STATE_HOME:-$HOME/.local/state}/openshell"

Snap:

sudo snap remove --purge openshell

Remove any custom config or database set through OPENSHELL_GATEWAY_CONFIG or OPENSHELL_DB_URL separately.

Next Steps