Installation

Install OpenShell

Install OpenShell with a single command:

$
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 page.

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_drivers in the gateway TOML when you need to pin a specific driver.

For detailed driver behavior, refer to Sandbox Compute Drivers. For gateway and sandbox operations, refer to Gateways and 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 listens on https://127.0.0.1:17670 and generates a local mTLS bundle on install. The gateway starts from built-in defaults and reads ~/.config/openshell/gateway.toml when that file exists. If that file is absent, the Homebrew service also falls back to a Homebrew prefix config when present, such as /opt/homebrew/var/openshell/gateway.toml.

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:

$
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.31 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, starts from built-in defaults, and generates a local mTLS bundle before the gateway starts. Create ~/.config/openshell/gateway.toml only when you need to override those defaults.

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:

$
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:

$
sudo loginctl enable-linger $USER

Snap

Install the OpenShell snap from the Snap Store:

$
sudo snap install openshell --classic

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.

Snap store installs

When installing from the Snap Store, snapd automatically connects the home, network, network-bind, and ssh-keys plugs. The docker plug still requires manual connection:

$
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:

$
sudo snap install ./openshell_*.snap --dangerous --classic
$
sudo snap connect openshell:home
$
sudo snap connect openshell:network
$
sudo snap connect openshell:network-bind
$
sudo snap connect openshell:ssh-keys
$
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:

$
sudo systemctl restart snap.openshell.gateway

Kubernetes

Kubernetes deployments use the OpenShell Helm chart. For step-by-step installation, refer to Kubernetes Setup. For chart values and packaging details, refer to the Helm chart README.

Next Steps

• To create your first sandbox, refer to the Quickstart.
• To run the gateway as a container without the installer, refer to Running the Gateway as a Container.
• To register, select, and inspect gateways, refer to Gateways.
• To supply API keys or tokens, refer to Manage Providers.
• To control what the agent can access, refer to Policies.