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.

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

## Supported Compute Drivers

OpenShell supports several local compute drivers. The installer chooses a default driver for your platform, and the gateway reads the driver choice from its startup configuration. Sandbox commands use the same CLI workflow after the gateway is running.

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

## Manually running the Gateway

Use a manual gateway when the package-managed installer is not a fit, such as on immutable or image-based Linux systems. This path keeps the binaries and gateway state in your home directory and leaves lifecycle management to your shell, a systemd user unit, or another supervisor.

Download the CLI and gateway release artifacts. Choose targets that match your host:

| Host | `CLI_TARGET` | `GATEWAY_TARGET` |
|---|---|---|
| Linux x86_64 | `x86_64-unknown-linux-musl` | `x86_64-unknown-linux-gnu` |
| Linux Arm64 | `aarch64-unknown-linux-musl` | `aarch64-unknown-linux-gnu` |
| macOS Apple Silicon | `aarch64-apple-darwin` | `aarch64-apple-darwin` |

```shell
VERSION="v0.0.0"
CLI_TARGET=x86_64-unknown-linux-musl
GATEWAY_TARGET=x86_64-unknown-linux-gnu
BASE_URL="https://github.com/NVIDIA/OpenShell/releases/download/${VERSION}"

mkdir -p "$HOME/.local/bin"
curl -LsSf "${BASE_URL}/openshell-${CLI_TARGET}.tar.gz" | tar -xz -C "$HOME/.local/bin" openshell
curl -LsSf "${BASE_URL}/openshell-gateway-${GATEWAY_TARGET}.tar.gz" | tar -xz -C "$HOME/.local/bin" openshell-gateway
chmod 755 "$HOME/.local/bin/openshell" "$HOME/.local/bin/openshell-gateway"
export PATH="$HOME/.local/bin:$PATH"
```

Set `VERSION` to a release tag from [OpenShell GitHub Releases](https://github.com/NVIDIA/OpenShell/releases). For production installs, download and verify the release checksum files before installing the artifacts.

Generate a local mTLS bundle and start a Docker-backed gateway on loopback:

```shell
export OPENSHELL_STATE_DIR="${XDG_STATE_HOME:-$HOME/.local/state}/openshell"
export OPENSHELL_TLS_DIR="${OPENSHELL_STATE_DIR}/tls"
export OPENSHELL_SERVER_PORT=17670

mkdir -p "${OPENSHELL_STATE_DIR}/gateway"
openshell-gateway generate-certs \
  --output-dir "${OPENSHELL_TLS_DIR}" \
  --server-san host.openshell.internal

export OPENSHELL_BIND_ADDRESS=127.0.0.1
export OPENSHELL_TLS_CERT="${OPENSHELL_TLS_DIR}/server/tls.crt"
export OPENSHELL_TLS_KEY="${OPENSHELL_TLS_DIR}/server/tls.key"
export OPENSHELL_TLS_CLIENT_CA="${OPENSHELL_TLS_DIR}/ca.crt"
export OPENSHELL_DB_URL="sqlite:${OPENSHELL_STATE_DIR}/gateway/openshell.db"
export OPENSHELL_GRPC_ENDPOINT="https://127.0.0.1:${OPENSHELL_SERVER_PORT}"
export OPENSHELL_SSH_GATEWAY_HOST=127.0.0.1
export OPENSHELL_SSH_GATEWAY_PORT="${OPENSHELL_SERVER_PORT}"
export OPENSHELL_SSH_HANDSHAKE_SECRET="$(openssl rand -hex 32)"
export OPENSHELL_DRIVERS=docker
export OPENSHELL_SANDBOX_IMAGE=ghcr.io/nvidia/openshell-community/sandboxes/base:latest
export OPENSHELL_DOCKER_TLS_CA="${OPENSHELL_TLS_DIR}/ca.crt"
export OPENSHELL_DOCKER_TLS_CERT="${OPENSHELL_TLS_DIR}/client/tls.crt"
export OPENSHELL_DOCKER_TLS_KEY="${OPENSHELL_TLS_DIR}/client/tls.key"

openshell-gateway
```

If you move this command into a service manager, persist the same environment values so restarts keep the same database, mTLS bundle, and SSH handshake secret.

For Podman, enable the user socket and replace the Docker driver exports:

```shell
systemctl --user enable --now podman.socket

export OPENSHELL_DRIVERS=podman
export OPENSHELL_SUPERVISOR_IMAGE="ghcr.io/nvidia/openshell/supervisor:${VERSION#v}"
export OPENSHELL_PODMAN_TLS_CA="${OPENSHELL_TLS_DIR}/ca.crt"
export OPENSHELL_PODMAN_TLS_CERT="${OPENSHELL_TLS_DIR}/client/tls.crt"
export OPENSHELL_PODMAN_TLS_KEY="${OPENSHELL_TLS_DIR}/client/tls.key"
```

In another terminal, register the manually started gateway:

```shell
openshell gateway add "https://127.0.0.1:17670" --local --name openshell
openshell gateway select openshell
openshell status
```

## 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 listens on `https://127.0.0.1:17670` and generates a local mTLS bundle on install. 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.

The Debian user service listens on `https://127.0.0.1:17670` and generates a local mTLS bundle before the gateway starts. 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
```

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