OpenShell/docs/about/installation.mdx

---
# 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, choose a sandbox runtime, and connect to a gateway."
keywords: "Generative AI, Cybersecurity, AI Agents, Sandboxing, Installation, Setup, Gateway, Docker, Podman, MicroVM, Kubernetes"
position: 3
---

Install OpenShell on a local workstation, choose the runtime that runs
your sandboxes, and verify the package-managed gateway configuration.

## Install OpenShell

Install OpenShell with a single command:

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

The script detects your operating system and installs the OpenShell CLI, standalone policy prover, and gateway. On Linux, it installs from the Snap Store whenever the `snap` command is available. Otherwise, it uses the native Debian or RPM package. It then starts the local gateway server so you can begin creating sandboxes.

Snap installs use `latest/stable` by default and `latest/edge` when
`OPENSHELL_VERSION=dev`. Other `OPENSHELL_VERSION` values also use the stable
Snap channel because Snap Store channels do not select an exact GitHub release.

You can also download release artifacts directly from the [OpenShell GitHub Releases](https://github.com/NVIDIA/OpenShell/releases) page.

Use `openshell status` to confirm the CLI can reach the gateway.

## Release Cadence

OpenShell publishes stable versions as coordinated release sets. The default
installer selects the newest stable release, and the `latest` documentation
channel follows that release. Use the same version of the gateway, compute and
credential drivers, supervisors, CLI, and SDK clients together.

Between stable releases, numbered prereleases such as `0.1.0-pre.3` provide
evaluation checkpoints. Rolling development builds track successful releases
from `main` and use versions such as `0.0.0-dev.<commit-sha>`. Prerelease and
development builds may change before the next stable release; their matching
documentation is published in the `dev` channel.

## Supported Runtimes

OpenShell supports several sandbox runtimes. Package-managed gateways leave the
runtime unset by default so the gateway can auto-detect an available backend.
Set `compute_driver` in the gateway TOML when you need to pin a specific
runtime.

| Runtime | How It Is Configured | System Requirements |
|---|---|---|
| Podman | The gateway is configured to create rootless Podman containers through the Podman API socket. | Linux with Podman 5.x, cgroups v2, rootless networking, and an active Podman user socket. |
| Docker | The gateway is configured to create containers through Docker Desktop or Docker Engine. | Docker Desktop or Docker Engine 28.0 or later on the gateway host. |
| MicroVM | The gateway is configured to create VM-backed sandboxes. | Host virtualization support. MicroVM uses Hypervisor.framework on macOS, KVM on Linux, and QEMU for GPU-backed sandboxes on Linux. |

For detailed runtime behavior, refer to [Sandbox Runtimes](/reference/sandbox-compute-drivers). For gateway and sandbox operations, refer to [Gateways](/sandboxes/manage-gateways) and [Sandboxes](/sandboxes/manage-sandboxes).

## macOS

On macOS, the install script uses Homebrew. The Homebrew package installs the `openshell` CLI, `openshell-prover`, the gateway binary, and a Homebrew-managed gateway service.

The Homebrew service uses the gateway's built-in `127.0.0.1:17670` listener and generates a local mTLS bundle on install. The installer registers `https://localhost:17670` with the CLI so TLS uses a DNS name covered by the generated certificate. The formula creates a Homebrew prefix config, such as `/opt/homebrew/var/openshell/gateway.toml`, without overriding `bind_address`. Host-networked Docker Desktop and Podman Machine supervisors reuse the primary listener when they can reach host loopback. The gateway reads `~/.config/openshell/gateway.toml` instead when that file exists. Homebrew upgrades migrate exact package-generated schema-v1 prefix configs, including the affected IPv6 variant. They preserve edited prefix configs and all user configs. Follow the [schema version 2 migration steps](/reference/gateway-config#migrate-to-schema-version-2) for an edited v1 file.

The CLI reads the client bundle from `~/.config/openshell/gateways/openshell/mtls/`.

The installer starts the service for you. Use Homebrew service commands when you need to inspect, restart, or stop the gateway service:

```shell
brew services list
brew services restart openshell
```

## Linux

On Linux systems with the `snap` command, the install script uses the OpenShell snap. If Docker is absent, it installs the Docker snap and waits for the Docker daemon before installing OpenShell.

On Fedora and RHEL without `snap`, the install script uses RPM packages. The RPMs install the `openshell` CLI, `openshell-prover`, the `openshell-gateway` daemon, and a systemd user service.

On Debian and Ubuntu without `snap`, the install script uses a Debian package. The Debian package installs the `openshell` CLI, `openshell-prover`, the `openshell-gateway` daemon, VM sandbox support, and a systemd user service.

Linux packages require glibc 2.28 or newer. The installer checks libc before downloading packages and exits with an error on older glibc versions, Alpine, musl-based distributions, or unknown libc environments.

The Linux user service listens on `https://127.0.0.1:17670` and generates a local mTLS bundle before the gateway starts. Debian uses built-in gateway defaults unless you create a config. RPM seeds `~/.config/openshell/gateway.toml` from its packaged Podman template on first start. RPM upgrades migrate only an unchanged package-generated schema-v1 file; they preserve edited files. Follow the [schema version 2 migration steps](/reference/gateway-config#migrate-to-schema-version-2) when upgrading an edited v1 configuration.

The CLI reads the client bundle from `~/.config/openshell/gateways/openshell/mtls/`.

The installer starts the service for you. Use systemd user commands when you need to inspect, restart, or stop the gateway service:

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

To keep the user service running after logout, enable linger:

```shell
sudo loginctl enable-linger $USER
```

## Snap

The OpenShell snap requires a running Docker daemon. Docker can come from the
Docker snap, a distribution package, Docker's package repository, or another
compatible installation method. The install script reuses an existing Docker
daemon. If Docker is absent, it installs the Docker snap and waits for the
daemon before installing OpenShell.

The snap keeps gateway and CLI state in snap-specific directories and does not
import state from a Debian, RPM, Homebrew, or manual installation. If the
installer detects an existing non-snap OpenShell binary, it stops before
installing the snap. Back up anything you need, clean up existing sandboxes and
runtime resources, stop the non-snap gateway, and remove the old installation.
After completing that cleanup, rerun the installer with
`OPENSHELL_ACK_BREAKING_UPGRADE=1`.

Install the OpenShell snap from the Snap Store:

```shell
sudo snap install openshell
```

The install script installs `latest/stable` by default. Set
`OPENSHELL_VERSION=dev` to install from `latest/edge`:

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

The snap defines two apps: the `openshell` CLI and the `openshell.gateway`
system service. Unlike the Debian and RPM user services, snapd runs this service
as root. The gateway therefore generates its certificates in root-owned snap
state, where ordinary users running the CLI cannot read the client certificate.
For this reason, the snap disables TLS and listens only on
`http://127.0.0.1:17670`. Its default configuration permits unauthenticated
local CLI access. Sandbox connections still use gateway-minted credentials.

The gateway stores its database at `$SNAP_COMMON/gateway.db` and its
configuration at `$SNAP_COMMON/gateway.toml`, typically under
`/var/snap/openshell/common/`. Initial snap installation creates the default
configuration only when no configuration already exists.
The install script applies the same default when it installs or refreshes a snap
that has no existing gateway configuration, then restarts the gateway.

Edit `$SNAP_COMMON/gateway.toml` when you need to override gateway settings,
then restart the service. Do not expose the default plaintext gateway beyond
the local host while unauthenticated user access is enabled. Any process or user
on the same host that can connect to the loopback port can operate the gateway.

The snap CLI stores per-user config, data, and state under `$SNAP_USER_COMMON`,
typically `~/snap/openshell/common`. Gateway registrations live under
`$SNAP_USER_COMMON/.config/openshell/gateways/` instead of
`~/.config/openshell/gateways/`.

### Snap store installs

When installing OpenShell from the Snap Store, snapd automatically connects all
required interfaces. The `docker` plug connects to the system `:docker` slot,
which exposes the installed Docker daemon regardless of how Docker was
packaged. The `log-observe` and `system-observe` plugs are also automatically
connected through the OpenShell snap's store assertions.

### Locally built snap packages

To install a locally-built snap, one can install directly from a `.snap` file
with the `--dangerous` flag to acknowledge that it has not been signed by the
Snap Store. Thus, it lacks the store assertions which tell snapd to auto-
connect the privileged interfaces, so they must be connected 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
```

The `log-observe` and `system-observe` plugs are needed for the gateway service
to read logs and inspect system processes. The `docker` plug connects to the
same system `:docker` slot used by Store installations.

### Gateway service

The gateway runs as a snap daemon with `refresh-mode: endure`, meaning snapd
will not restart it during snap refreshes. This prevents the gateway from
killing active sandbox sessions during automatic or direct snap refreshes.
Restart the service manually after a direct `snap refresh` when you need the
updated binary:

```shell
sudo systemctl restart snap.openshell.gateway
```

Rerunning `install.sh` explicitly refreshes the snap and restarts the gateway so
the refreshed binary is active when installation completes. That restart
interrupts active sandbox sessions.

## Kubernetes

Kubernetes deployments use the OpenShell Helm chart. For step-by-step installation, refer to [Kubernetes Setup](/kubernetes/setup). For chart values and packaging details, refer to the [Helm chart README](https://github.com/NVIDIA/OpenShell/blob/main/deploy/helm/openshell/README.md).

## Validate a package-managed gateway configuration

Debian and Ubuntu packages validate the selected gateway configuration before
generating local certificates or starting the service. Snap does the same before
its gateway daemon starts. The validation never changes the file. If startup reports a legacy schema,
malformed TOML, a symlink, or a nonregular configuration path, fix or manually
migrate the operator-owned file instead of deleting it.

Check the selected file before restarting a service:

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

Without `--path`, preflight checks a nonempty `OPENSHELL_GATEWAY_CONFIG` or an
auto-discovered XDG config; no config is also a successful result. It applies
read-only startup validation to the effective selector, registered compute driver,
driver configuration, socket, rate limits, TLS, interceptors, and middleware. If
a selected file omits the selector, preflight validates configured tables for
auto-detectable drivers without running socket or process-based detection probes.
Wrappers can pass daemon arguments after `--` to validate the exact startup
invocation. Debian keeps its bare service invocation and `gateway.env` semantics.
Snap replays its effective daemon arguments through preflight and gives a nonempty
`OPENSHELL_GATEWAY_CONFIG` precedence over `SNAP_COMMON/gateway.toml`.
See [Gateway Configuration](/reference/gateway-config#gateway-config-preflight)
for preflight details and manual schema-v1 migration steps.

## Next Steps

- To prepare an image and launch an agent, refer to [Run Your First Agent](/about/run-an-agent).
- To run the gateway as a container without the installer, refer to [Running the Gateway as a Container](/reference/container-gateway).
- To register, select, and inspect gateways, refer to [Gateways](/sandboxes/manage-gateways).
- To supply API keys or tokens, refer to [Manage Providers](/sandboxes/manage-providers).
- To control what the agent can access, refer to [Policies](/sandboxes/policies).