Installation | NVIDIA OpenShell

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.

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.

Runtime	Requirements
Docker	Docker Desktop or Docker Engine 28.0 or later.
Podman	Linux with Podman 5.x, cgroups v2, and an active Podman user socket.
MicroVM	Host 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 installs a Debian package on Debian and Ubuntu or an RPM package on Fedora and RHEL. Set OPENSHELL_INSTALL_METHOD=snap to install the snap package instead; hosts that already have the OpenShell snap keep refreshing it. 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.

Both Debian and RPM load ~/.config/openshell/gateway.env for configuration preflight and gateway startup. Use it to select exact trusted runtime artifacts without creating driver-specific TOML:

OPENSHELL_SANDBOX_RUNTIME_IMAGE=registry.example.com/openshell/sandbox@sha256:<digest>
OPENSHELL_SUPERVISOR_IMAGE=registry.example.com/openshell/supervisor@sha256:<digest>

The environment variables take precedence over image fields in the selected Docker, Podman, or Kubernetes TOML table. Restart the user service after editing the file. Treat these variables as trusted operator configuration; sandbox requests cannot set them, and registry credentials must remain in the container runtime’s credential store or Kubernetes image-pull secrets.

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.

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

sudo snap install openshell

The snap installs the standalone policy prover as openshell.prover. The openshell-prover alias requires Snap Store approval and may not be available. The prover reads local policy files through the home interface and does not connect to the gateway.

The gateway runs at https://127.0.0.1:17670. It reads ~/snap/openshell/common/.config/openshell/gateway.toml when that file exists. Its database defaults to ~/snap/openshell/common/.local/state/openshell/gateway/openshell.db, and its TLS material lives under ~/snap/openshell/common/.local/state/openshell/tls. Register it from the same user account:

snap services openshell.user-gateway
openshell gateway add https://127.0.0.1:17670 --local --name openshell
openshell status

Existing installations upgraded from the former openshell.gateway service retain their state under /var/snap/openshell/common through openshell.system-gateway. Existing HTTPS registrations continue to work because the endpoint and TLS identity do not change.

If this user still has an old HTTP registration, or has not previously been enrolled, wait for the system gateway to be active, copy its client credentials into the user’s snap state, and register its HTTPS endpoint:

snap services openshell.system-gateway
d=~/snap/openshell/common/.local/state/openshell/tls
mkdir -p -m 700 "$d" "$d/client"
sudo install -o "$USER" -g "$(id -gn)" -m 600 \
  /var/snap/openshell/common/tls/ca.crt "$d/"
sudo install -o "$USER" -g "$(id -gn)" -m 600 \
  /var/snap/openshell/common/tls/client/tls.crt "$d/client/"
sudo install -o "$USER" -g "$(id -gn)" -m 600 \
  /var/snap/openshell/common/tls/client/tls.key "$d/client/"
openshell gateway list
old_registration="NAME_FROM_GATEWAY_LIST"
openshell gateway remove "$old_registration"
openshell gateway add https://127.0.0.1:17670 --local --name openshell
openshell status

Set old_registration to the name shown by openshell gateway list, and omit the variable assignment and openshell gateway remove when no registration exists. Older direct snap instructions may have used openshell-gateway, while the install script uses openshell.

Change the snap gateway mode

The user and system gateways have separate configuration, databases, and cryptographic identities. Changing modes does not migrate gateway or sandbox state and interrupts active sandbox sessions. Back up any state you need and delete active sandboxes before changing modes.

First disable both services and move the current user TLS directory to a timestamped backup. The directory can contain CA, server, client, and sandbox JWT private keys, so keep every tls-backup-* directory private:

sudo snap set openshell gateway-mode=disable
state="$HOME/snap/openshell/common/.local/state/openshell"
tls="$state/tls"
if test -e "$tls" || test -L "$tls"; then
  backup="$state/tls-backup-$(date +%s%N)"
  while test -e "$backup" || test -L "$backup"; do
    backup="$state/tls-backup-$(date +%s%N)"
  done
  mv -- "$tls" "$backup"
  printf 'Previous gateway TLS state saved to: %s\n' "$backup"
fi

To use the user gateway, start it and replace the previous CLI registration after it generates new credentials:

sudo snap set openshell gateway-mode=user
systemctl --user is-active snap.openshell.user-gateway.service
openshell gateway list
old_registration="NAME_FROM_GATEWAY_LIST"
openshell gateway remove "$old_registration"
openshell gateway add https://127.0.0.1:17670 --local --name openshell
openshell status

To use the system gateway, start it, wait for it to generate its root-owned credentials, then copy its client bundle and replace the previous CLI registration:

sudo snap set openshell gateway-mode=system
sudo snap services openshell.system-gateway
tls="$HOME/snap/openshell/common/.local/state/openshell/tls"
mkdir -p -m 700 "$tls" "$tls/client"
sudo install -o "$USER" -g "$(id -gn)" -m 600 \
  /var/snap/openshell/common/tls/ca.crt "$tls/"
sudo install -o "$USER" -g "$(id -gn)" -m 600 \
  /var/snap/openshell/common/tls/client/tls.crt "$tls/client/"
sudo install -o "$USER" -g "$(id -gn)" -m 600 \
  /var/snap/openshell/common/tls/client/tls.key "$tls/client/"
openshell gateway list
old_registration="NAME_FROM_GATEWAY_LIST"
openshell gateway remove "$old_registration"
openshell gateway add https://127.0.0.1:17670 --local --name openshell
openshell status

Set old_registration to the name shown by openshell gateway list, and omit the variable assignment and remove command when no registration exists. If a transition is interrupted while both services are disabled, select gateway-mode=user or gateway-mode=system to resume it. Keep the TLS backup until the selected gateway works and can create a sandbox.

To install a locally built snap, connect its interfaces manually. The user gateway may reach systemd’s start limit before Docker is connected, so reset the failed unit and restart it from the affected user session after connecting the interfaces:

sudo snap install ./openshell_*.snap --dangerous
sudo snap connect openshell:log-observe
sudo snap connect openshell:system-observe
sudo snap connect openshell:docker :docker
systemctl --user reset-failed snap.openshell.user-gateway.service
snap start --user openshell.user-gateway

For an installation upgraded from a legacy system gateway, use sudo systemctl reset-failed snap.openshell.system-gateway.service and sudo snap restart openshell.system-gateway instead.

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

Run Your First Agent to prepare an image and launch an agent.
Running the Gateway as a Container to skip the installer.
Gateways to register, select, and inspect gateways.
Providers to supply API keys and tokens.
Policies to control what the agent can access.