---
# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0
title: "Installation"
sidebar-title: "Installation"
description: "Install OpenShell on a local workstation or Kubernetes."
keywords: "Generative AI, Cybersecurity, AI Agents, Sandboxing, Installation, Setup, Gateway, Docker, Podman, MicroVM, Kubernetes"
position: 3
---

Install OpenShell on a local workstation or Kubernetes.

## Install OpenShell

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

```shell
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:

```shell
openshell status
```

To install a specific release, set `OPENSHELL_VERSION` to a release tag. Release artifacts are also on the [GitHub Releases](https://github.com/NVIDIA/OpenShell/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](https://docs.nvidia.com/openshell/dev/index.html).

Prerelease packages are retained as GitHub Actions artifacts for 90 days and require an authenticated [GitHub CLI](https://cli.github.com/) session. The `pre` alias installs the latest prerelease:

```shell
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](https://github.com/NVIDIA/OpenShell/releases/tag/dev) does not require GitHub authentication:

```shell
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:

```shell
# 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](/how-it-works/sandboxes/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`.

```shell
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](#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:

```shell
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.

```shell
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:

```shell
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:

```shell
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 as a system service at `https://127.0.0.1:17670` and reads `/var/snap/openshell/common/gateway.toml`. It requires a client certificate. The install script copies that certificate to the installing user's Snap state and registers the gateway automatically. If you installed with `sudo snap install openshell`, give each trusted user the certificate and register the gateway from that user's account:

```shell
d=~/snap/openshell/common/.local/state/openshell/tls
mkdir -p -m 700 "$d" "$d/client"
sudo install -o "$USER" -m 600 /var/snap/openshell/common/tls/ca.crt "$d/"
sudo install -o "$USER" -m 600 -t "$d/client" \
  /var/snap/openshell/common/tls/client/tls.crt /var/snap/openshell/common/tls/client/tls.key
openshell gateway add https://127.0.0.1:17670 --local --name openshell
openshell status
```

Keep the client key private.

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

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

## Kubernetes

Deploy the gateway to a cluster with the OpenShell Helm chart. See [Kubernetes Setup](/kubernetes/setup).

## Validate Gateway Configuration

Check a gateway config file before restarting the service:

```shell
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](/how-it-works/gateways/configuration#migrate-to-schema-version-2).

## Uninstall OpenShell

Homebrew:

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

Debian and Ubuntu:

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

Fedora and RHEL:

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

Snap:

```shell
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](/about/run-your-first-agent) to prepare an image and launch an agent.
- [Running the Gateway as a Container](/how-it-works/gateways/container-deployment) to skip the installer.
- [Gateways](/how-it-works/gateways/overview) to register, select, and inspect gateways.
- [Providers](/how-it-works/providers/overview) to supply API keys and tokens.
- [Policies](/how-it-works/policies/overview) to control what the agent can access.