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/how-it-works.mdx b/docs/about/how-it-works.mdx new file mode 100644 index 000000000..5223072a2 --- /dev/null +++ b/docs/about/how-it-works.mdx @@ -0,0 +1,131 @@ +--- +# 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: "Understand the OpenShell architecture, runtime boundaries, gateways, sandboxes, and ecosystem integration points." +keywords: "Generative AI, Cybersecurity, AI Agents, Architecture, Gateway, Sandbox, Inference Routing" +position: 2 +--- + +OpenShell 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 +control plane: it owns API access, 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"] + DB[("Entity 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"] +``` + +## Deployment Models + +OpenShell can run on a single local machine or in a remote Kubernetes cluster. +The CLI workflow stays the same: users point the CLI, SDK, or TUI at a gateway, +and the gateway provisions sandboxes through its configured compute driver. + +| Deployment | How it works | Best for | +|---|---|---| +| Local machine | The gateway runs on the user's workstation or a nearby development host and creates sandboxes with Docker, Podman, or a VM runtime. The supervisor inside each sandbox connects back to that local gateway. | Individual development, local agent experiments, and private workstation workflows. | +| Remote Kubernetes cluster | The gateway runs as a cluster service and creates sandbox pods in the configured namespace. Supervisors connect outbound to the gateway endpoint, so clients do not need direct pod access. | Shared teams, centrally managed policy, remote compute, GPUs, and production-like environments. | + +This deployment split keeps the runtime model consistent. Local deployments use +the host's container or VM runtime as the integrated infrastructure. Kubernetes +deployments use the cluster scheduler, networking, secrets, identity, and GPU +device plugins without changing the gateway and sandbox contract. + +## 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. + +## Supervisor Protection Layers + +The supervisor is the sandbox-local enforcement component. It starts before the +agent process, prepares the sandbox runtime, fetches gateway configuration, and +then launches the agent under the active policy. + +| Protection layer | Supervisor responsibility | +|---|---| +| Process | Drops privileges, applies process identity rules, disables privilege escalation paths, and starts the agent as a restricted child process. | +| Filesystem | Applies filesystem policy before the agent starts so undeclared paths are inaccessible and declared paths are read-only or read-write as configured. | +| Network | Routes ordinary egress through the policy proxy so destination, port, binary identity, and L7 request rules can be evaluated before traffic leaves the sandbox. | +| Credentials | Receives credential material from the gateway and injects it only through configured policy paths or request-time proxy rules. | +| Inference | Intercepts `https://inference.local` and forwards model traffic through the configured inference route instead of exposing provider credentials to the agent. | +| Observability | Emits local security and lifecycle logs, pushes sandbox logs to the gateway, and keeps relay endpoints available for connect, exec, and file transfer operations. | + +Static controls such as filesystem and process isolation are established at +sandbox start and require sandbox recreation to change. Dynamic controls such as +network policy, credential delivery, and inference routing can refresh over the +live gateway-supervisor session. + +## 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. diff --git a/docs/about/installation.mdx b/docs/about/installation.mdx new file mode 100644 index 000000000..e2ad59bd9 --- /dev/null +++ b/docs/about/installation.mdx @@ -0,0 +1,77 @@ +--- +# 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. The installer chooses a default driver for your platform, and the gateway reads the driver choice from its startup configuration. Sandbox commands use the same CLI workflow after the gateway is running. + +| 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.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 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 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..3d23c8794 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 [Customize Sandbox Policies](/sandboxes/policies) and [Default Policy](/reference/default-policy). ## Common Use Cases @@ -49,12 +49,10 @@ OpenShell supports a range of agent deployment patterns. | Compliance and audit | Treat policy YAML as version-controlled security controls that can be reviewed and audited. | | Reusable environments | Use community sandbox images or bring your own containerized runtime. | ---- - ## 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 understand the runtime architecture, refer to [How OpenShell Works](/about/how-it-works). - 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 policy controls across protection layers, refer to [Customize Sandbox Policies](/sandboxes/policies). diff --git a/docs/about/release-notes.mdx b/docs/about/release-notes.mdx index 0d9a4407e..2efa2b82c 100644 --- a/docs/about/release-notes.mdx +++ b/docs/about/release-notes.mdx @@ -5,7 +5,7 @@ title: "NVIDIA OpenShell Release Notes" sidebar-title: "Release Notes" description: "Track the latest changes and improvements to NVIDIA OpenShell." keywords: "Generative AI, Cybersecurity, Release Notes, Changelog, AI Agents" -position: 4 +position: 5 --- NVIDIA OpenShell follows a frequent release cadence. Use the following GitHub resources directly. diff --git a/docs/about/supported-agents.mdx b/docs/about/supported-agents.mdx index e65778ab9..ec03cf755 100644 --- a/docs/about/supported-agents.mdx +++ b/docs/about/supported-agents.mdx @@ -4,7 +4,7 @@ title: "Supported Agents" description: "AI agent frameworks and runtimes compatible with OpenShell sandboxes." keywords: "Generative AI, Cybersecurity, AI Agents, Sandboxing, Claude, Codex, Cursor" -position: 3 +position: 4 --- The following table summarizes the agents that run in OpenShell sandboxes. All agent sandbox images are maintained in the [OpenShell Community](https://github.com/NVIDIA/OpenShell-Community) repository. Agents in the base image are auto-configured when passed as the trailing command to `openshell sandbox create`. @@ -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..fcfbc945b 100644 --- a/docs/get-started/quickstart.mdx +++ b/docs/get-started/quickstart.mdx @@ -14,10 +14,11 @@ This page gets you from a reachable OpenShell gateway to a running, policy-enfor Before you begin, make sure you have: - A reachable OpenShell gateway. -- At least one compute platform configured for the gateway: Kubernetes, Docker, Podman, or MicroVM. +- At least one compute driver configured for the gateway: Kubernetes, Docker, Podman, or MicroVM. - 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 compute driver yet, refer to [Installation](/about/installation). ## 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 af84aa0ba..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 [About Inference Routing](/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 c3d1f94a8..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 [About Inference Routing](/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 26135b874..4d358a827 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