From d12f3b1ae42462996ceba4d1270823b971bb212e Mon Sep 17 00:00:00 2001 From: Drew Newberry Date: Sun, 15 Mar 2026 17:23:49 -0700 Subject: [PATCH] docs: simplify quickstart install, reorder sections, and clean up sandbox docs Rewrite the quickstart install section to use the one-liner install script as the primary method with uv tool install as an alternative. Move the Deploy a Gateway section below Create Your First Sandbox. Clarify that cloud gateways are for individual users, not team access. Remove advanced start options from gateways, outlook provider type, simulation community sandbox, fully specified sandbox create example and flags table, and the delete --all example. --- docs/get-started/quickstart.md | 98 +++++++++++++-------------- docs/sandboxes/community-sandboxes.md | 1 - docs/sandboxes/index.md | 2 +- docs/sandboxes/manage-gateways.md | 9 --- docs/sandboxes/manage-providers.md | 1 - docs/sandboxes/manage-sandboxes.md | 22 ------ 6 files changed, 49 insertions(+), 84 deletions(-) diff --git a/docs/get-started/quickstart.md b/docs/get-started/quickstart.md index 4181b5d1..bd11b936 100644 --- a/docs/get-started/quickstart.md +++ b/docs/get-started/quickstart.md @@ -32,74 +32,28 @@ This page gets you from zero to a running, policy-enforced sandbox in two comman Before you begin, make sure you have: -- Python 3.12 or later. -- [uv](https://docs.astral.sh/uv/) installed. - Docker Desktop running on your machine. For a complete list of requirements, refer to {doc}`../reference/support-matrix`. ## Install the OpenShell CLI -Install the `openshell` package into a virtual environment. - -Activate your virtual environment: +Run the install script: ```console -$ uv venv && source .venv/bin/activate +$ curl -LsSf https://raw.githubusercontent.com/NVIDIA/OpenShell/main/install.sh | sh ``` -Install the CLI: +If you prefer [uv](https://docs.astral.sh/uv/): ```console -$ uv pip install openshell +$ uv tool install -U openshell ``` :::{tip} Run `openshell --help` in your terminal to see the full CLI reference, including all commands and flags. You can also clone the [NVIDIA OpenShell GitHub repository](https://github.com/NVIDIA/OpenShell) and use the `/openshell-cli` skill to load the CLI reference into your agent. ::: -## Deploy a Gateway (Optional) - -Running `openshell sandbox create` without a gateway auto-bootstraps a local one. -To start the gateway explicitly or deploy to a remote host, choose the tab that matches your setup. - -:::::{tab-set} - -::::{tab-item} Brev - -:::{note} -Deploy an OpenShell gateway on Brev by clicking **Deploy** on the [OpenShell Launchable](https://brev.nvidia.com/launchable/deploy/now?launchableID=env-3Ap3tL55zq4a8kew1AuW0FpSLsg). -::: - -After the instance starts running, find the gateway URL in the Brev console under **Using Secure Links**. -Copy the shareable URL for **port 8080**, which is the gateway endpoint. - -```console -$ openshell gateway add https://.brevlab.com -$ openshell status -``` - -:::: - -::::{tab-item} DGX Spark - -:::{note} -Set up your Spark with NVIDIA Sync first, or make sure SSH access is configured (such as SSH keys added to the host). -::: - -Deploy to a DGX Spark machine over SSH: - -```console -$ openshell gateway start --remote @.local -$ openshell status -``` - -After `openshell status` shows the gateway as healthy, all subsequent commands route through the SSH tunnel. - -:::: - -::::: - ## Create Your First OpenShell Sandbox Create a sandbox and launch an agent inside it. @@ -171,3 +125,47 @@ $ openshell sandbox create --from base ``` ::: + +:::: + +## Deploy a Gateway (Optional) + +Running `openshell sandbox create` without a gateway auto-bootstraps a local one. +To start the gateway explicitly or deploy to a remote host, choose the tab that matches your setup. + +:::::{tab-set} + +::::{tab-item} Brev + +:::{note} +Deploy an OpenShell gateway on Brev by clicking **Deploy** on the [OpenShell Launchable](https://brev.nvidia.com/launchable/deploy/now?launchableID=env-3Ap3tL55zq4a8kew1AuW0FpSLsg). +::: + +After the instance starts running, find the gateway URL in the Brev console under **Using Secure Links**. +Copy the shareable URL for **port 8080**, which is the gateway endpoint. + +```console +$ openshell gateway add https://.brevlab.com +$ openshell status +``` + +:::: + +::::{tab-item} DGX Spark + +:::{note} +Set up your Spark with NVIDIA Sync first, or make sure SSH access is configured (such as SSH keys added to the host). +::: + +Deploy to a DGX Spark machine over SSH: + +```console +$ openshell gateway start --remote @.local +$ openshell status +``` + +After `openshell status` shows the gateway as healthy, all subsequent commands route through the SSH tunnel. + +:::: + +::::: diff --git a/docs/sandboxes/community-sandboxes.md b/docs/sandboxes/community-sandboxes.md index 301107b5..3bcb2d27 100644 --- a/docs/sandboxes/community-sandboxes.md +++ b/docs/sandboxes/community-sandboxes.md @@ -45,7 +45,6 @@ The following community sandboxes are available in the catalog. | `base` | Foundational image with system tools and dev environment | | `openclaw` | Open agent manipulation and control | | `sdg` | Synthetic data generation workflows | -| `simulation` | General-purpose simulation sandboxes | ## Use a Community Sandbox diff --git a/docs/sandboxes/index.md b/docs/sandboxes/index.md index f78c90b9..59f2c078 100644 --- a/docs/sandboxes/index.md +++ b/docs/sandboxes/index.md @@ -38,7 +38,7 @@ A gateway provisions sandboxes, brokers CLI requests, enforces policies, and man |---|---|---| | **Local** | Docker on your workstation | Solo development and quick iteration. The CLI auto-bootstraps a local gateway if none exists. | | **Remote** | Docker on a remote host via SSH | Running sandboxes on a more powerful machine (for example, a DGX Spark) while keeping the CLI on your laptop. | -| **Cloud** | Behind a reverse proxy (for example, Cloudflare Access) | Shared team environments where multiple users connect to the same gateway through browser-based authentication. | +| **Cloud** | Behind a reverse proxy (for example, Cloudflare Access) | Individual users accessing OpenShell behind a cloud VM. Cloud gateways are not yet intended for shared team access. | All three types expose the same API surface. Sandboxes, policies, and providers work identically regardless of where the gateway runs. The only difference is how the CLI reaches the gateway, whether through a direct Docker socket, SSH tunnel, or HTTPS through a proxy. diff --git a/docs/sandboxes/manage-gateways.md b/docs/sandboxes/manage-gateways.md index 1cc70878..07449d64 100644 --- a/docs/sandboxes/manage-gateways.md +++ b/docs/sandboxes/manage-gateways.md @@ -164,15 +164,6 @@ $ openshell gateway info $ openshell gateway info --name my-remote-cluster ``` -## Advanced Start Options - -| Flag | Purpose | -|---|---| -| `--gpu` | Enable NVIDIA GPU passthrough. Requires NVIDIA drivers and the Container Toolkit on the host. | -| `--plaintext` | Listen on HTTP instead of mTLS. Use behind a TLS-terminating reverse proxy. | -| `--disable-gateway-auth` | Skip mTLS client certificate checks. Use when a reverse proxy cannot forward client certs. | -| `--registry-token` | GitHub PAT with `read:packages` scope for pulling container images from ghcr.io. Also configurable with `OPENSHELL_REGISTRY_TOKEN`. | - ## Stop and Destroy Stop a gateway while preserving its state for later restart: diff --git a/docs/sandboxes/manage-providers.md b/docs/sandboxes/manage-providers.md index 5052c4ee..d238e3ee 100644 --- a/docs/sandboxes/manage-providers.md +++ b/docs/sandboxes/manage-providers.md @@ -137,7 +137,6 @@ The following provider types are supported. | `gitlab` | `GITLAB_TOKEN`, `GLAB_TOKEN`, `CI_JOB_TOKEN` | GitLab API, `glab` CLI | | `nvidia` | `NVIDIA_API_KEY` | NVIDIA API Catalog | | `generic` | User-defined | Any service with custom credentials | -| `outlook` | *(none: no auto-discovery)* | Microsoft Outlook integration | :::{tip} Use the `generic` type for any service not listed above. You define the diff --git a/docs/sandboxes/manage-sandboxes.md b/docs/sandboxes/manage-sandboxes.md index fa2e4c8f..d2790d57 100644 --- a/docs/sandboxes/manage-sandboxes.md +++ b/docs/sandboxes/manage-sandboxes.md @@ -69,27 +69,6 @@ $ openshell sandbox create --from my-registry.example.com/my-image:latest The CLI resolves community names against the [OpenShell Community](https://github.com/NVIDIA/OpenShell-Community) catalog, pulls the bundled Dockerfile and policy, builds the image locally, and creates the sandbox. For the full catalog and how to contribute your own, refer to {doc}`community-sandboxes`. -The following is an example of a fully specified creation command: - -```console -$ openshell sandbox create \ - --name dev \ - --provider my-claude \ - --policy policy.yaml \ - --upload \ - -- claude -``` - -Additional `sandbox create` flags: - -| Flag | Purpose | -|---|---| -| `--no-keep` | Delete the sandbox automatically after the initial command exits | -| `--forward ` | Forward a local port to the sandbox before running | -| `--tty` / `--no-tty` | Force or disable pseudo-terminal allocation | -| `--no-bootstrap` | Error if no gateway is available instead of auto-bootstrapping | -| `--no-auto-providers` | Error if required providers are missing instead of prompting | - ## Connect to a Sandbox Open an SSH session into a running sandbox: @@ -203,7 +182,6 @@ Deleting a sandbox stops all processes, releases resources, and purges injected ```console $ openshell sandbox delete my-sandbox -$ openshell sandbox delete --all ``` ## Next Steps