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

## 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 and gateway with your native package manager. It then starts the local gateway server so you can begin creating sandboxes.

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

The `openshell` package on PyPI provides the Python SDK only. It does not install the `openshell` CLI. Add the SDK to a Python project with:

```shell
uv add openshell
```

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

## Supported Compute Drivers

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

| Compute Driver | 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 driver behavior, refer to [Sandbox Compute Drivers](/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, 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`. Docker Desktop and Podman Machine reuse the primary listener for sandbox callbacks when they can reach it. 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 Fedora and RHEL, the install script uses RPM packages. The RPM installs the `openshell` CLI, the `openshell-gateway` daemon, and a systemd user service.

On Debian and Ubuntu, the install script uses a Debian package. The Debian package installs the `openshell` CLI, 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

Install the OpenShell snap from the Snap Store:

```shell
sudo snap install openshell
```

The snap defines two apps: the `openshell` CLI and the `openshell.gateway`
systemd service. The gateway listens on `https://127.0.0.1:17670` and
stores its database at `$SNAP_COMMON/gateway.db` (typically
`/var/snap/openshell/common/gateway.db`). Create `$SNAP_COMMON/gateway.toml`
when you need to override gateway settings.

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 from the Snap Store, snapd automatically connects the `home`,
`network`, and `network-bind` plugs. The `docker` plug still
requires manual connection:

```shell
sudo snap connect openshell:docker docker:docker-daemon
```

The snap declares `default-provider: docker` on the Docker plug so snapd will
offer to install the Docker snap, but the connection itself must be made
manually.

### Locally built snap packages

When installing a locally built `.snap` file, no plugs are connected by default:

```shell
sudo snap install ./openshell_*.snap --dangerous
sudo snap connect openshell:home
sudo snap connect openshell:network
sudo snap connect openshell:network-bind
sudo snap connect openshell:docker docker:docker-daemon
sudo snap connect openshell:log-observe
sudo snap connect openshell:system-observe
```

The `log-observe` and `system-observe` plugs are needed for the gateway service
to read logs and inspect system processes. The `docker` plug requires the
`docker:docker-daemon` slot from the Docker snap and does not work with
system-installed Docker.

### 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 mid-refresh. Restart the service manually after
a snap refresh when you need the updated binary:

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

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

## Next Steps

- To create your first sandbox, refer to the [Quickstart](/get-started/quickstart).
- To run the gateway as a container without the installer, refer to [Running the Gateway as a Container](/about/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).

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