mirror of
https://github.com/NVIDIA/OpenShell.git
synced 2026-10-04 16:39:35 +08:00
Drew Newberry
a67567e583
* fix(snap): require mTLS for the snap gateway Replace the installer opt-in with an authenticated snap gateway. The wrapper no longer forces plaintext, so the gateway serves TLS from the bundle it already generates in $SNAP_COMMON/tls. The install hook writes a config that enables mTLS user auth instead of unauthenticated access, and a new post-refresh hook migrates the exact legacy default on existing installs. install.sh waits for the gateway, detects whether it serves TLS, copies the client bundle into the target user's snap state directory, and registers the gateway over HTTPS. Older plaintext snap revisions still register over HTTP with a warning. The release canary asserts mTLS auth and HTTPS registration. Signed-off-by: Drew Newberry <anewberry@nvidia.com> * fix(snap): pass config preflight and detect the mTLS gateway reliably An explicit [openshell.gateway.mtls_auth] table fails config preflight, which validates mTLS auth before the local TLS bundle supplies the client CA. Write a default that pins the Docker driver instead; with the wrapper's TLS bundle the gateway requires client certificates and enables mTLS user auth automatically, as the native packages do. The mTLS gateway rejects TLS handshakes without a client certificate, and it still answers plaintext loopback HTTP for sandbox service routing, so the installer could misdetect it as a legacy plaintext gateway. Probe HTTPS with the root-owned client bundle, and treat a gateway as legacy only when a plaintext gRPC Health call succeeds. Signed-off-by: Drew Newberry <anewberry@nvidia.com> * chore(snap): simplify install hook comment Signed-off-by: Drew Newberry <anewberry@nvidia.com> * fix(snap): migrate insecure gateway configs on refresh Signed-off-by: Drew Newberry <anewberry@nvidia.com> * refactor(snap): simplify mTLS detection and config migration Detect the mTLS snap from the installed revision's post-refresh hook instead of probing plaintext gRPC, and drop the scheme global. Remove the installer's pre-hook config fallback, which is dead now that every channel ships the install hook and which wrote the insecure default. Give the install hook a single write path with a simple backup name, and shorten the manual client certificate steps. Signed-off-by: Drew Newberry <anewberry@nvidia.com> * fix(snap): stop keeping a copy of replaced insecure configs Signed-off-by: Drew Newberry <anewberry@nvidia.com> * feat(install): make the snap an opt-in install method Stop selecting the OpenShell snap just because the snap command exists. Linux installs default to the Debian or RPM package; OPENSHELL_INSTALL_METHOD=snap (or deb, rpm) selects the package explicitly. Hosts that already have the OpenShell snap keep refreshing it rather than gaining a second gateway on the same port. The release canary and snap repro script opt in explicitly. Signed-off-by: Drew Newberry <anewberry@nvidia.com> * fix(snap): let the gateway auto-detect its compute driver Signed-off-by: Drew Newberry <anewberry@nvidia.com> * fix(snap): restart the gateway after refresh Published revisions use refresh-mode: endure, and snapd honors the old revision's setting during a refresh, so the plaintext gateway kept running with the migrated config unused until a manual restart. Restart the gateway from the post-refresh hook so the mTLS config takes effect immediately. Signed-off-by: Drew Newberry <anewberry@nvidia.com> * docs(snap): drop refresh notes from the snap description Signed-off-by: Drew Newberry <anewberry@nvidia.com> * docs(snap): trim snap refresh notes from installation docs Signed-off-by: Drew Newberry <anewberry@nvidia.com> --------- Signed-off-by: Drew Newberry <anewberry@nvidia.com>
193 lines
7.3 KiB
Plaintext
193 lines
7.3 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 on a local workstation or Kubernetes."
|
|
keywords: "Generative AI, Cybersecurity, AI Agents, Sandboxing, Installation, Setup, Gateway, Docker, Podman, MicroVM, Kubernetes"
|
|
position: 3
|
|
---
|
|
|
|
Install OpenShell on a local workstation or Kubernetes.
|
|
|
|
## Install OpenShell
|
|
|
|
Install the CLI, policy prover, and a local gateway with one command:
|
|
|
|
```shell
|
|
curl -LsSf https://raw.githubusercontent.com/NVIDIA/OpenShell/main/install.sh | sh
|
|
```
|
|
|
|
The script picks a package for your platform and starts the gateway. Confirm the CLI can reach it:
|
|
|
|
```shell
|
|
openshell status
|
|
```
|
|
|
|
To install a specific release, set `OPENSHELL_VERSION` to a release tag. Release artifacts are also on the [GitHub Releases](https://github.com/NVIDIA/OpenShell/releases) page.
|
|
|
|
## Prerelease and Development Builds
|
|
|
|
Use a prerelease candidate to evaluate an upcoming release, or the rolling development build to test the latest commit on `main`. These builds may change before the next stable release. The matching documentation is published in the [development channel](https://docs.nvidia.com/openshell/dev/index.html).
|
|
|
|
Prerelease packages are retained as GitHub Actions artifacts for 90 days and require an authenticated [GitHub CLI](https://cli.github.com/) session. The `pre` alias installs the latest prerelease:
|
|
|
|
```shell
|
|
gh auth login
|
|
curl -LsSf https://raw.githubusercontent.com/NVIDIA/OpenShell/main/install.sh | \
|
|
OPENSHELL_VERSION=pre sh
|
|
```
|
|
|
|
The installer checks prerelease tags from newest to oldest, selects an unexpired artifact from a successful release run for the current platform, and downloads only that artifact. Installed packages keep the candidate's exact version, such as `0.1.0-pre.3`. Prerelease tags do not create entries on the GitHub Releases page. On Linux, prereleases and explicit release tags use Debian or RPM packages.
|
|
|
|
The rolling [`dev` release](https://github.com/NVIDIA/OpenShell/releases/tag/dev) does not require GitHub authentication:
|
|
|
|
```shell
|
|
curl -LsSf https://raw.githubusercontent.com/NVIDIA/OpenShell/main/install.sh | \
|
|
OPENSHELL_VERSION=dev sh
|
|
```
|
|
|
|
For Kubernetes, select the corresponding Helm chart version. Helm chart versions omit the leading `v` from release tags:
|
|
|
|
```shell
|
|
# Pin an exact candidate
|
|
helm upgrade --install openshell \
|
|
oci://ghcr.io/nvidia/openshell/helm-chart \
|
|
--version 0.1.0-pre.3
|
|
|
|
# Rolling development build
|
|
helm upgrade --install openshell \
|
|
oci://ghcr.io/nvidia/openshell/helm-chart \
|
|
--version 0.0.0-dev
|
|
```
|
|
|
|
Prerelease charts use exact `<version>-pre.N` versions. Development charts are also published as immutable `0.0.0-dev.<commit-sha>` versions when you need to pin a specific commit.
|
|
|
|
## Supported Runtimes
|
|
|
|
The local gateway auto-detects an available runtime. To pin one, set `compute_driver` in the gateway TOML file. See [Sandbox Runtimes](/how-it-works/sandboxes/runtimes).
|
|
|
|
| Runtime | Requirements |
|
|
|---|---|
|
|
| Docker | Docker Desktop or Docker Engine 28.0 or later. |
|
|
| Podman | Linux with Podman 5.x, cgroups v2, and an active Podman user socket. |
|
|
| MicroVM | Host virtualization: Hypervisor.framework on macOS or KVM on Linux. |
|
|
|
|
## macOS
|
|
|
|
The script installs OpenShell with Homebrew and runs the gateway as a Homebrew service at `https://localhost:17670`.
|
|
|
|
```shell
|
|
brew services list
|
|
brew services restart openshell
|
|
```
|
|
|
|
The gateway reads `~/.config/openshell/gateway.toml` if it exists, otherwise the Homebrew config at `$(brew --prefix)/var/openshell/gateway.toml`.
|
|
|
|
## Linux
|
|
|
|
The script installs a Debian package on Debian and Ubuntu or an RPM package on Fedora and RHEL. Set `OPENSHELL_INSTALL_METHOD=snap` to install the [Snap](#snap) package instead; hosts that already have the OpenShell snap keep refreshing it. Linux packages require glibc 2.28 or newer.
|
|
|
|
The gateway runs as a systemd user service at `https://127.0.0.1:17670` and reads `~/.config/openshell/gateway.toml`.
|
|
|
|
```shell
|
|
systemctl --user status openshell-gateway
|
|
systemctl --user restart openshell-gateway
|
|
journalctl --user -u openshell-gateway -f
|
|
```
|
|
|
|
To keep the gateway running after you log out, enable linger:
|
|
|
|
```shell
|
|
sudo loginctl enable-linger $USER
|
|
```
|
|
|
|
## Snap
|
|
|
|
The snap requires Docker Engine installed from your distribution or Docker's package repository. The Docker snap is not compatible.
|
|
|
|
```shell
|
|
sudo snap install openshell
|
|
```
|
|
|
|
The snap does not migrate existing Debian, RPM, or Homebrew installs. Remove any existing installation first, then rerun the script with `OPENSHELL_INSTALL_METHOD=snap OPENSHELL_ACK_BREAKING_UPGRADE=1`.
|
|
|
|
The gateway runs as a system service at `https://127.0.0.1:17670` and reads `/var/snap/openshell/common/gateway.toml`. It requires a client certificate. The install script copies that certificate to the installing user's Snap state and registers the gateway automatically. If you installed with `sudo snap install openshell`, give each trusted user the certificate and register the gateway from that user's account:
|
|
|
|
```shell
|
|
d=~/snap/openshell/common/.local/state/openshell/tls
|
|
mkdir -p -m 700 "$d" "$d/client"
|
|
sudo install -o "$USER" -m 600 /var/snap/openshell/common/tls/ca.crt "$d/"
|
|
sudo install -o "$USER" -m 600 -t "$d/client" \
|
|
/var/snap/openshell/common/tls/client/tls.crt /var/snap/openshell/common/tls/client/tls.key
|
|
openshell gateway add https://127.0.0.1:17670 --local --name openshell
|
|
openshell status
|
|
```
|
|
|
|
Keep the client key private.
|
|
|
|
To install a locally built snap, connect its interfaces 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
|
|
```
|
|
|
|
## Kubernetes
|
|
|
|
Deploy the gateway to a cluster with the OpenShell Helm chart. See [Kubernetes Setup](/kubernetes/setup).
|
|
|
|
## Validate Gateway Configuration
|
|
|
|
Check a gateway config file before restarting the service:
|
|
|
|
```shell
|
|
openshell-gateway config preflight --path ~/.config/openshell/gateway.toml
|
|
```
|
|
|
|
Preflight never changes the file. If the gateway reports a legacy schema, follow the [schema version 2 migration steps](/how-it-works/gateways/configuration#migrate-to-schema-version-2).
|
|
|
|
## Uninstall OpenShell
|
|
|
|
Homebrew:
|
|
|
|
```shell
|
|
brew services stop nvidia/openshell/openshell
|
|
brew uninstall nvidia/openshell/openshell
|
|
rm -rf "$(brew --prefix)/var/openshell"
|
|
```
|
|
|
|
Debian and Ubuntu:
|
|
|
|
```shell
|
|
systemctl --user disable --now openshell-gateway
|
|
sudo apt remove openshell
|
|
rm -rf "${XDG_STATE_HOME:-$HOME/.local/state}/openshell"
|
|
```
|
|
|
|
Fedora and RHEL:
|
|
|
|
```shell
|
|
systemctl --user disable --now openshell-gateway
|
|
sudo dnf remove openshell-gateway openshell-prover openshell
|
|
rm -rf "${XDG_STATE_HOME:-$HOME/.local/state}/openshell"
|
|
```
|
|
|
|
Snap:
|
|
|
|
```shell
|
|
sudo snap remove --purge openshell
|
|
```
|
|
|
|
Remove any custom config or database set through `OPENSHELL_GATEWAY_CONFIG` or `OPENSHELL_DB_URL` separately.
|
|
|
|
## Next Steps
|
|
|
|
- [Run Your First Agent](/about/run-your-first-agent) to prepare an image and launch an agent.
|
|
- [Running the Gateway as a Container](/how-it-works/gateways/container-deployment) to skip the installer.
|
|
- [Gateways](/how-it-works/gateways/overview) to register, select, and inspect gateways.
|
|
- [Providers](/how-it-works/providers/overview) to supply API keys and tokens.
|
|
- [Policies](/how-it-works/policies/overview) to control what the agent can access.
|