From 248dc22931051d8fc613a81f096e296667a83d03 Mon Sep 17 00:00:00 2001 From: Drew Newberry Date: Wed, 6 May 2026 23:34:04 -0700 Subject: [PATCH 1/6] docs: consolidate documentation structure Signed-off-by: Drew Newberry --- docs/about/architecture.mdx | 70 -------- docs/about/get-openshell.mdx | 77 +++++++++ docs/about/overview.mdx | 98 ++++++++++- docs/about/supported-agents.mdx | 2 +- docs/get-started/quickstart.mdx | 11 +- .../tutorials/inference-ollama.mdx | 6 +- .../tutorials/local-inference-lmstudio.mdx | 4 +- docs/index.mdx | 49 ++++-- docs/index.yml | 3 +- docs/inference/about.mdx | 68 -------- docs/reference/support-matrix.mdx | 3 +- docs/sandboxes/about.mdx | 64 -------- docs/sandboxes/community-sandboxes.mdx | 99 ----------- .../inference-routing.mdx} | 102 ++++++++---- docs/sandboxes/manage-gateways.mdx | 154 +++++------------- docs/sandboxes/manage-providers.mdx | 8 +- docs/sandboxes/manage-sandboxes.mdx | 75 ++++++--- docs/sandboxes/policies.mdx | 6 +- docs/security/best-practices.mdx | 4 +- 19 files changed, 392 insertions(+), 511 deletions(-) delete mode 100644 docs/about/architecture.mdx create mode 100644 docs/about/get-openshell.mdx delete mode 100644 docs/inference/about.mdx delete mode 100644 docs/sandboxes/about.mdx delete mode 100644 docs/sandboxes/community-sandboxes.mdx rename docs/{inference/configure.mdx => sandboxes/inference-routing.mdx} (56%) diff --git a/docs/about/architecture.mdx b/docs/about/architecture.mdx deleted file mode 100644 index e1d2ff746..000000000 --- a/docs/about/architecture.mdx +++ /dev/null @@ -1,70 +0,0 @@ ---- -# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -# SPDX-License-Identifier: Apache-2.0 -title: "How OpenShell Works" -sidebar-title: "How It Works" -description: "OpenShell architecture overview covering the gateway, sandbox, and policy engine." -keywords: "Generative AI, Cybersecurity, AI Agents, Sandboxing, Security, Architecture" -position: 2 ---- - -OpenShell runs sandboxes through a gateway that uses one of four compute platforms: Kubernetes, Docker, Podman, or the experimental MicroVM runtime. Each sandbox is an isolated environment managed through the gateway. Three components work together to keep agents secure. - -![OpenShell architecture diagram](/assets/images/architecture.svg) - -## Components - -The following table describes each component and its role in the system: - -| Component | Role | -| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| **Gateway** | Control-plane API that coordinates sandbox lifecycle and state, and acts as the auth boundary between clients and sandboxes. | -| **Sandbox** | Isolated runtime that includes container supervision and policy-enforced egress routing. | -| **Policy Engine** | Policy definition and enforcement layer for filesystem, network, process, and inference constraints. Defense in depth enforces policies from the application layer down to infrastructure and kernel layers. | - -## How a Request Flows - -Every outbound connection from agent code passes through the same decision path: - -1. The agent process opens an outbound connection (API call, package install, git clone, and so on). -2. The proxy inside the sandbox intercepts the connection and identifies which binary opened it. -3. If the target is `https://inference.local`, the proxy handles it as managed inference before policy evaluation. OpenShell strips sandbox-supplied credentials, injects the configured backend credentials, and forwards the request to the managed model endpoint. -4. For every other destination, the proxy queries the policy engine with the destination, port, and calling binary. -5. The policy engine returns one of the following decisions. Explicit deny takes precedence over allow, and allow takes precedence over implicit deny. - - | Decision | When it applies | Outcome | - | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- | - | **Explicit Deny** | A deny rule, or a hardening rule such as server-side request forgery (SSRF) protection, a blocked control-plane port, or a Layer 7 (L7) deny, rejects the request even when an allow rule would otherwise permit it. | The connection is blocked and logged. | - | **Allow** | The destination and binary match a policy block, and no deny rule applies. | Traffic flows directly to the external service. | - | **Implicit Deny** | No policy block matched. | The connection is blocked and logged. | - -For REST endpoints, the proxy auto-detects Transport Layer Security (TLS) by peeking the first bytes of each tunnel. When TLS is detected, the proxy terminates it transparently using a per-sandbox ephemeral certificate authority (CA) so each HTTP request can be checked against per-method, per-path rules before forwarding. To trust a corporate or internal CA for upstream traffic, add the PEM-encoded certificate to the sandbox container's trust store at image build time. - -## Gateway Lifecycle - -OpenShell preserves gateway state in the configured gateway database. Kubernetes deployments commonly use the Helm chart's persistent volume, while standalone gateway deployments can use local storage or Postgres. Sandbox state depends on the selected compute driver and the storage configured for sandbox workloads. - -## Observability - -The sandbox emits operational decisions as Open Cybersecurity Schema Framework (OCSF) v1.7.0 structured logs. The events cover network connections, HTTP requests, SSH sessions, process lifecycle, detection findings, and configuration changes. For event classes and the JSON Lines (JSONL) export format, refer to [OCSF JSON Export](/observability/ocsf-json-export). - -## Deployment Modes - -OpenShell supports four deployment modes: Kubernetes, Docker, Podman, and MicroVM. Each mode runs or exposes a gateway, then registers that endpoint with the CLI. The gateway's compute driver determines where sandboxes run. - -| Mode | Description | -| -------------- | -------------------------------------------------------------------------------- | -| **Docker** | The gateway uses Docker to create local sandbox containers. | -| **Podman** | The gateway uses a Podman-compatible container runtime, commonly rootless. | -| **Kubernetes** | The Helm chart deploys the gateway and configures the Kubernetes compute driver. | -| **MicroVM** | The gateway uses the experimental VM compute driver. | - -You can register multiple gateways and switch between them with `openshell gateway select`. For the full deployment and management workflow, refer to the [Gateways](/sandboxes/manage-gateways) section. - -## Next Steps - -Continue with one of the following: - -- To deploy or register a gateway, refer to [Gateways](/sandboxes/manage-gateways). -- To create your first sandbox, refer to the [Quickstart](/get-started/quickstart). -- To learn how OpenShell enforces isolation across all protection layers, refer to [Sandboxes](/sandboxes/about). diff --git a/docs/about/get-openshell.mdx b/docs/about/get-openshell.mdx new file mode 100644 index 000000000..a4d7d0fa5 --- /dev/null +++ b/docs/about/get-openshell.mdx @@ -0,0 +1,77 @@ +--- +# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 +title: "Get OpenShell" +sidebar-title: "Get OpenShell" +description: "Install OpenShell, choose a sandbox runtime, and connect to a gateway." +keywords: "Generative AI, Cybersecurity, AI Agents, Sandboxing, Installation, Setup, Gateway, Docker, Podman, MicroVM, Kubernetes" +position: 2 +--- + +## Installation + +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 Sandbox Runtimes + +OpenShell supports several local sandbox runtimes. The installer chooses a default runtime for your platform, and the gateway reads the runtime choice from its startup configuration. Sandbox commands use the same CLI workflow after the gateway is running. + +| Runtime | 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.04 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 runtime behavior, 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 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. + +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 +``` + +## Kubernetes + +Kubernetes deployments use the OpenShell Helm chart. For chart installation and configuration, 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 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). diff --git a/docs/about/overview.mdx b/docs/about/overview.mdx index 6255c6225..8c59e70c7 100644 --- a/docs/about/overview.mdx +++ b/docs/about/overview.mdx @@ -36,7 +36,7 @@ OpenShell applies defense in depth across the following policy domains. | Process | Blocks privilege escalation and dangerous syscalls. | Locked at sandbox creation. | | Inference | Reroutes model API calls to controlled backends. | Hot-reloadable at runtime. | -For details, refer to [Sandbox Policies](/sandboxes/about#sandbox-policies) and [Customize Sandbox Policies](/sandboxes/policies). +For details, refer to [Sandbox Isolation and Policies](/sandboxes/manage-sandboxes#sandbox-isolation-and-policies) and [Customize Sandbox Policies](/sandboxes/policies). ## Common Use Cases @@ -51,10 +51,102 @@ OpenShell supports a range of agent deployment patterns. --- +## Architecture + +The target architecture is built around three stable runtime components: the **CLI**, the **Gateway**, and +the **Supervisor**. + +The CLI, SDK, and TUI provide user-facing access. The gateway is the +authenticated control plane: it owns API access, durable state, policy and +settings delivery, provider and inference configuration, and relay +coordination. The supervisor runs inside every sandbox workload and is the local +security boundary. It launches the agent as a restricted child process and +enforces policy where process identity, filesystem access, network egress, and +runtime credentials are visible. + +Infrastructure-specific work sits behind integration boundaries. Compute, +credentials, control-plane identity, and sandbox identity each have a driver or +adapter boundary so OpenShell can integrate with native runtimes, secret stores, +identity providers, and workload identity systems without moving those concerns +into the core gateway or sandbox model. + +```mermaid +flowchart TB + subgraph UI["User interfaces"] + CLI["CLI"] + SDK["SDK"] + TUI["TUI"] + end + + subgraph CP["Control plane"] + GW["Gateway core"] + DB[("Shared persistence")] + DRIVERS["Compute, credentials, and identity drivers"] + end + + subgraph INFRA["Integrated infrastructure"] + RUNTIME["Docker, Podman, Kubernetes, or VM"] + SECRETSTORE["Secret stores"] + IDP["Identity providers"] + WORKLOADID["Workload identity"] + end + + subgraph DP["Sandbox data plane"] + SUP["Supervisor"] + AGENT["Restricted agent process"] + PROXY["Policy proxy"] + POLICY["OPA policy engine"] + ROUTER["Inference router"] + end + + CLI -->|"gRPC / HTTP"| GW + SDK -->|"gRPC / HTTP"| GW + TUI -->|"gRPC / HTTP"| GW + GW --> DB + GW --> DRIVERS + DRIVERS --> RUNTIME + DRIVERS --> SECRETSTORE + DRIVERS --> IDP + DRIVERS --> WORKLOADID + RUNTIME -->|"provisions workload"| SUP + SUP -->|"control, config, logs, relay"| GW + SUP -->|"spawn and restrict"| AGENT + AGENT -->|"ordinary egress"| PROXY + PROXY -->|"evaluate"| POLICY + PROXY -->|"allowed traffic"| EXT["External services"] + PROXY -->|"inference.local"| ROUTER + ROUTER -->|"managed inference"| MODEL["Inference backends"] +``` + +### Core Components + +| Component | Boundary | +|---|---| +| [Sandboxes](/sandboxes/manage-sandboxes) | Data-plane workloads that run the supervisor, launch restricted agent processes, apply local isolation, push logs, and maintain the gateway session. | +| [Gateways](/sandboxes/manage-gateways) | Authenticated control plane that owns API access, durable state, sandbox lifecycle, settings delivery, authorization, and relay coordination. | +| [Providers](/sandboxes/manage-providers) | Credential and provider records that map logical agent needs to platform or user-managed secrets without exposing raw credentials to the agent process. | +| [Policies](/sandboxes/policies) | Declarative controls for filesystem access, process identity, network egress, L7 rules, credential injection, and runtime policy updates. | +| [Inference Routing](/sandboxes/inference-routing) | Managed `https://inference.local` path that routes model traffic to configured backends while keeping provider credentials outside the sandbox. | + +### Gateways and Sandboxes + +The gateway and sandbox split control-plane authority from runtime enforcement. The gateway owns durable platform state: sandboxes, policy revisions, runtime settings, provider records, inference configuration, session records, and authorization decisions. A sandbox owns the local execution boundary: process identity, filesystem access, network egress, credential injection, local logs, and the agent child process. + +The relationship is supervisor initiated. Each sandbox supervisor connects outbound to a known gateway endpoint, authenticates as a sandbox workload, and keeps a live session open for control traffic and relays. This avoids requiring every compute driver to solve gateway-to-sandbox reachability through pod IPs, bridge networks, port mappings, NAT traversal, or custom tunnels. + +The gateway delivers desired state. The supervisor applies it locally, keeps last-known-good config when refresh fails, and leaves static isolation controls in place until the sandbox is recreated. Live operations such as config refresh, policy updates, credential delivery, log push, connect, exec, file sync, and relay setup use the same authenticated gateway-supervisor relationship. + +### Ecosystem Integration + +OpenShell integrates with infrastructure ecosystems instead of replacing them. Runtimes, schedulers, secret stores, identity providers, workload identity systems, image pipelines, storage, and GPU or device exposure remain owned by the platforms that provide them. + +The gateway owns OpenShell control-plane semantics: sandbox state, lifecycle ordering, policy and settings resolution, credential mapping, authorization, inference configuration, and relay coordination. Drivers translate those semantics into platform-native operations. + +The supervisor owns OpenShell sandbox semantics. Filesystem policy, process privilege reduction, network proxying, inference interception, credential injection, security logging, and gateway relay behavior stay consistent across Docker, Podman, Kubernetes, VM-backed sandboxes, and future integrations. + ## Next Steps Explore these topics to go deeper: -- To understand the components that make up the OpenShell runtime, refer to the [Architecture Overview](/about/architecture). - To install the CLI and create your first sandbox, refer to the [Quickstart](/get-started/quickstart). -- To learn how OpenShell enforces isolation across all protection layers, refer to [Sandboxes](/sandboxes/about). +- To learn how OpenShell enforces isolation across all protection layers, refer to [Sandboxes](/sandboxes/manage-sandboxes#sandbox-isolation-and-policies). diff --git a/docs/about/supported-agents.mdx b/docs/about/supported-agents.mdx index e65778ab9..e2b715d7b 100644 --- a/docs/about/supported-agents.mdx +++ b/docs/about/supported-agents.mdx @@ -17,6 +17,6 @@ The following table summarizes the agents that run in OpenShell sandboxes. All a | [OpenClaw](https://openclaw.ai/) | [`openclaw`](https://github.com/NVIDIA/OpenShell-Community/tree/main/sandboxes/openclaw) | Bundled | Agent orchestration layer. Launch with `openshell sandbox create --from openclaw`. | | [Ollama](https://ollama.com/) | [`ollama`](https://github.com/NVIDIA/OpenShell-Community/tree/main/sandboxes/ollama) | Bundled | Run cloud and local models. Includes Claude Code, Codex, and OpenCode. Launch with `openshell sandbox create --from ollama`. | -More community agent sandboxes are available in the [Community Sandboxes](/sandboxes/community-sandboxes) catalog. +For base image details and `--from` usage, refer to [Sandboxes](/sandboxes/manage-sandboxes#base-sandbox-container). For a complete support matrix, refer to the [Support Matrix](/reference/support-matrix) page. diff --git a/docs/get-started/quickstart.mdx b/docs/get-started/quickstart.mdx index 903133876..827f3ccbf 100644 --- a/docs/get-started/quickstart.mdx +++ b/docs/get-started/quickstart.mdx @@ -18,6 +18,7 @@ Before you begin, make sure you have: - The OpenShell CLI installed on your workstation. For a complete list of requirements, refer to [Support Matrix](/reference/support-matrix). +If you have not chosen a runtime yet, refer to [Get OpenShell](/about/get-openshell). ## Install the OpenShell CLI @@ -27,6 +28,8 @@ Run the install script: curl -LsSf https://raw.githubusercontent.com/NVIDIA/OpenShell/main/install.sh | sh ``` +The install script uses Homebrew, RPM, or a Debian package based on your machine. It starts the local gateway server after installation. + If you prefer [uv](https://docs.astral.sh/uv/): ```shell @@ -95,14 +98,12 @@ Run the following command to create a sandbox with OpenClaw: openshell sandbox create --from openclaw ``` -The `--from` flag pulls a pre-built sandbox definition from the [OpenShell Community](https://github.com/NVIDIA/OpenShell-Community) catalog. -Each definition bundles a container image, a tailored policy, and optional skills into a single package. +The `--from` flag pulls a pre-built sandbox container with its bundled policy and optional skills. - + -Use the `--from` flag to pull other OpenShell sandbox images from the [OpenShell Community](https://github.com/NVIDIA/OpenShell-Community) catalog. -For example, to pull the `base` image, run: +Use the `--from` flag to create a sandbox from the base container: ```shell openshell sandbox create --from base diff --git a/docs/get-started/tutorials/inference-ollama.mdx b/docs/get-started/tutorials/inference-ollama.mdx index 4fcc018a7..4a16eee01 100644 --- a/docs/get-started/tutorials/inference-ollama.mdx +++ b/docs/get-started/tutorials/inference-ollama.mdx @@ -206,6 +206,6 @@ openshell provider get ollama ## Next Steps -- To learn more about managed inference, refer to [Index](/inference/about). -- To configure a different self-hosted backend, refer to [Configure](/inference/configure). -- To explore more community sandboxes, refer to [Community Sandboxes](/sandboxes/community-sandboxes). +- To learn more about managed inference, refer to [Inference Routing](/sandboxes/inference-routing). +- To configure a different self-hosted backend, refer to [Inference Routing](/sandboxes/inference-routing#configure-inference-routing). +- To learn how sandbox containers are selected, refer to [Sandboxes](/sandboxes/manage-sandboxes#custom-containers). diff --git a/docs/get-started/tutorials/local-inference-lmstudio.mdx b/docs/get-started/tutorials/local-inference-lmstudio.mdx index 976770d1f..2d1246459 100644 --- a/docs/get-started/tutorials/local-inference-lmstudio.mdx +++ b/docs/get-started/tutorials/local-inference-lmstudio.mdx @@ -210,5 +210,5 @@ openshell provider get lmstudio-anthropic ## Next Steps - To learn more about using the LM Studio CLI, refer to [LM Studio docs](https://lmstudio.ai/docs/cli) -- To learn more about managed inference, refer to [Index](/inference/about). -- To configure a different self-hosted backend, refer to [Configure](/inference/configure). +- To learn more about managed inference, refer to [Inference Routing](/sandboxes/inference-routing). +- To configure a different self-hosted backend, refer to [Inference Routing](/sandboxes/inference-routing#configure-inference-routing). diff --git a/docs/index.mdx b/docs/index.mdx index 73b8d1d0b..45dc61ef5 100644 --- a/docs/index.mdx +++ b/docs/index.mdx @@ -36,7 +36,7 @@ uncontrolled network activity. ## Get Started -Install the CLI and create your first sandbox in two commands. +Install OpenShell and create your first sandbox in two commands. {/*Terminal demo styles live in fern/main.css — inline