mirror of
https://github.com/NVIDIA/OpenShell.git
synced 2026-10-21 06:11:31 +08:00
Drew NewberryandPiotr Mlocek
73a181d32f
* docs(readme): streamline README and move reference detail to docs Restructure the README as a short path from overview to quickstart to further reading. Move prerelease install steps into the installation guide and telemetry build flags into a new observability page. Fix broken docs links and outdated runtime and credential descriptions. Signed-off-by: Drew Newberry <anewberry@nvidia.com> * docs(readme): describe 0.1.0 as adding new isolation primitives Signed-off-by: Drew Newberry <anewberry@nvidia.com> * docs(architecture): add policy prover as a gateway component Signed-off-by: Drew Newberry <anewberry@nvidia.com> * docs: describe OpenShell as a runtime for fleets of autonomous AI agents Signed-off-by: Drew Newberry <anewberry@nvidia.com> * docs(architecture): describe policy prover as formal verification Signed-off-by: Drew Newberry <anewberry@nvidia.com> * docs(architecture): name OpenShell Sandbox in component table Signed-off-by: Drew Newberry <anewberry@nvidia.com> * docs(architecture): fold isolation backend into supervisor row Signed-off-by: Drew Newberry <anewberry@nvidia.com> * docs(architecture): mention formal verification in overview Signed-off-by: Drew Newberry <anewberry@nvidia.com> * docs(run-agent): use the published OpenCode image in the first-agent guide Signed-off-by: Drew Newberry <anewberry@nvidia.com> * docs(inference): correct provider examples and readiness Signed-off-by: Piotr Mlocek <pmlocek@nvidia.com> * docs(providers): correct Google binding and provider selection Signed-off-by: Piotr Mlocek <pmlocek@nvidia.com> * docs(readme): sharpen value prop, how it works, and explore further Signed-off-by: Drew Newberry <anewberry@nvidia.com> * docs(run-agent): use example Anthropic profile and add policy advisor step Import the example Anthropic profile, which now allows OpenCode, instead of editing it with sed. Add a step that shows how to review and approve mechanistic policy proposals as the agent needs more access. Signed-off-by: Drew Newberry <anewberry@nvidia.com> * feat(providers): add OpenRouter example for OpenCode Signed-off-by: Drew Newberry <anewberry@nvidia.com> * docs(run-agent): run OpenCode against OpenRouter with a free model Add an example OpenRouter provider profile scoped to OpenCode and switch the first-agent guide to it, using a free Nemotron model so readers do not need OpenRouter credits. Revert the OpenCode binary added to the example Anthropic profile. Signed-off-by: Drew Newberry <anewberry@nvidia.com> * docs(readme): link first-agent guide and add agent skills section Signed-off-by: Drew Newberry <anewberry@nvidia.com> --------- Signed-off-by: Drew Newberry <anewberry@nvidia.com> Signed-off-by: Piotr Mlocek <pmlocek@nvidia.com> Co-authored-by: Piotr Mlocek <pmlocek@nvidia.com>
191 lines
6.9 KiB
Plaintext
191 lines
6.9 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 even if `snap` is installed.
|
|
|
|
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 uses the [Snap](#snap) package when `snap` is available. Otherwise, or when you set `OPENSHELL_VERSION` to a release tag, it installs a Debian package on Debian and Ubuntu or an RPM package on Fedora and RHEL. 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_ACK_BREAKING_UPGRADE=1`.
|
|
|
|
The gateway runs as a system service at `http://127.0.0.1:17670` and reads `/var/snap/openshell/common/gateway.toml`.
|
|
|
|
<Warning>
|
|
The snap gateway allows unauthenticated access from the local host. Any local user or process can operate it. Do not expose it beyond the local host.
|
|
</Warning>
|
|
|
|
Snap refreshes do not restart the gateway, so active sandboxes keep running. Restart it to pick up a new version:
|
|
|
|
```shell
|
|
sudo systemctl restart snap.openshell.gateway
|
|
```
|
|
|
|
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.
|