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

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

```shell
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_INSTALL_METHOD=snap OPENSHELL_ACK_BREAKING_UPGRADE=1`.

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:

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

## 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.