mirror of
https://github.com/NVIDIA/OpenShell.git
synced 2026-10-15 05:09:44 +08:00
Oliver Calder
994750e3a1
Previously, the openshell snap used the ssh-keys interface to get access to the host's ssh binary, which is used for sandbox connect/exec/forward. However, ssh-keys is a privileged interface which also grants access to the public and private ssh keys on the host. As such, it required manual connection in order to be used. This weakened the security sandbox of the snap, and hurt the UX of installing it. This commit changes this by removing the `ssh-keys` interface and instead vendoring the `ssh` binary within the snap. This is safe because OpenShell always invokes the `ssh` binary with `StrictHostKeyChecking=no`, `UserKnownHostsFile=/dev/null`, and `GlobalKnownHostsFile=/dev/null`, and never uses any host credentials or ssh configuration. Openshell only ever access to `~/.ssh/config` to write OpenShell-managed aliases, and this can safely live within the snap sandbox, rather than leaking into the host environment. Signed-off-by: Oliver Calder <oliver.calder@canonical.com>
152 lines
7.0 KiB
Plaintext
152 lines
7.0 KiB
Plaintext
---
|
|
# 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. 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.
|
|
|
|
| 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 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:
|
|
|
|
```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`, 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:
|
|
|
|
```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).
|