diff --git a/README.md b/README.md index d441d5bcf9..6049b609a3 100644 --- a/README.md +++ b/README.md @@ -12,16 +12,16 @@ [![PyPI](https://img.shields.io/badge/PyPI-openshell-orange?logo=pypi)](https://pypi.org/project/openshell/) [![Security Policy](https://img.shields.io/badge/Security-Report%20a%20Vulnerability-red)](SECURITY.md) [![Documentation](https://img.shields.io/badge/docs-latest-brightgreen)](https://docs.nvidia.com/openshell/latest/index.html) -[![Project Status](https://img.shields.io/badge/status-alpha-orange)](https://docs.nvidia.com/openshell/latest/about/release-notes.html) +[![Project Status](https://img.shields.io/badge/status-alpha-orange)](https://github.com/NVIDIA/OpenShell/releases) > [!IMPORTANT] -> **OpenShell 0.1.0 is coming soon.** [Track progress in the 0.1.0 milestone](https://github.com/NVIDIA/OpenShell/milestone/10), [read the prerelease documentation](https://docs.nvidia.com/openshell/dev/index.html), or [install a prerelease](#prerelease-and-development-builds). +> **New in OpenShell 0.1.0:** a stable release cadence, an improved security model, an expanded extension surface, and new APIs. [Read the 0.1.0 upgrade guide](https://docs.nvidia.com/openshell/latest/upgrade/0-1-0). OpenShell is the safe, private runtime for autonomous AI agents. It provides sandboxed execution environments that protect your data, credentials, and infrastructure — governed by declarative YAML policies that prevent unauthorized file access, data exfiltration, and uncontrolled network activity. OpenShell is built agent-first. It ships public agent skills for using and operating OpenShell, plus separate repository-aware workflows for contributors and maintainers. -## Quickstart +## Install OpenShell ### Prerequisites @@ -190,20 +190,13 @@ Docker-backed GPU sandboxes auto-select CDI when available and otherwise fall ba **Requirements:** NVIDIA drivers and the [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html) must be installed on the host. The sandbox image itself must include the appropriate GPU drivers and libraries for your workload — the default Ubuntu image does not. See the [BYOC example](https://github.com/NVIDIA/OpenShell/tree/main/examples/bring-your-own-container) for building a custom sandbox image with GPU support. -## Supported Agents +## Running Agents OpenShell can run Linux agents packaged in OCI images. The default Ubuntu workload does not bundle agent CLIs. Build or select an image containing your -agent, then authorize its binary paths, service endpoints, and credentials. - -| Agent | Integration | -| ----- | ----------- | -| [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | Package Claude Code in a workload image and attach a `claude-code` provider or another endpoint-bearing model profile. | -| [OpenCode](https://opencode.ai/) | Package OpenCode in a workload image and attach its model provider and policy. | -| [Codex](https://developers.openai.com/codex) | Package Codex in a workload image and attach an OpenAI provider and policy. | -| [GitHub Copilot CLI](https://docs.github.com/en/copilot/github-copilot-in-the-cli) | Package the CLI in a workload image and attach GitHub credentials and policy. | -| [OpenClaw](https://openclaw.ai/) | Use the [NemoClaw](https://github.com/NVIDIA/NemoClaw) blueprint. | -| [Hermes Agent](https://github.com/NousResearch/hermes-agent) | Use the [NemoClaw](https://github.com/NVIDIA/NemoClaw) blueprint. | +agent, then authorize its binary paths, service endpoints, and credentials. See +[Run Your First Agent](https://docs.nvidia.com/openshell/latest/about/run-an-agent) +for the image, provider, and policy workflow. ## Key Commands @@ -284,7 +277,7 @@ Agent implementation is human-directed: a user may request a phase directly, or ## Learn More - [Full Documentation](https://docs.nvidia.com/openshell/latest/index.html) — overview, architecture, tutorials, and reference -- [Quickstart](https://docs.nvidia.com/openshell/latest/get-started/quickstart) — detailed install and first sandbox walkthrough +- [Run Your First Agent](https://docs.nvidia.com/openshell/latest/about/run-an-agent) — prepare an image, attach providers, and launch an agent - [GitHub Sandbox Tutorial](https://docs.nvidia.com/openshell/latest/get-started/tutorials/github-sandbox) — end-to-end scoped GitHub repo access - [Architecture](https://github.com/NVIDIA/OpenShell/tree/main/architecture) — detailed architecture docs and design decisions - [Roadmap](https://github.com/orgs/NVIDIA/projects/233) — planned work and project priorities diff --git a/docs/_components/CommandTerminal.tsx b/docs/_components/CommandTerminal.tsx index 9f8e75d0a0..27247b7be1 100644 --- a/docs/_components/CommandTerminal.tsx +++ b/docs/_components/CommandTerminal.tsx @@ -3,10 +3,6 @@ * SPDX-License-Identifier: Apache-2.0 */ -declare const React: unknown; - -const rotatingAgents = ["", "claude", "opencode", "codex"]; - export function CommandTerminal({ command }: { command: string }) { return (
-
$ - {"openshell sandbox create "} - - {rotatingAgents.map((agent, index) => ( - - {agent !== "" && ( - - {"-- "} - - {agent} - - - - )} - - ))} - + openshell sandbox create
diff --git a/docs/about/how-it-works.mdx b/docs/about/how-it-works.mdx index 9878fceb68..014af559ec 100644 --- a/docs/about/how-it-works.mdx +++ b/docs/about/how-it-works.mdx @@ -1,8 +1,8 @@ --- # 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" +title: "Architecture" +sidebar-title: "Architecture" description: "Understand the OpenShell architecture, runtime boundaries, gateways, sandboxes, and ecosystem integration points." keywords: "Generative AI, Cybersecurity, AI Agents, Architecture, Gateway, Sandbox, Providers" position: 2 @@ -90,7 +90,7 @@ device plugins without changing the gateway and sandbox contract. | [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. | -| [Provider-backed Inference](/sandboxes/inference-routing) | Per-sandbox provider attachment, native model endpoints, and endpoint-bound credential injection. | +| [Inference](/sandboxes/inference-routing) | Per-sandbox provider attachment, native model endpoints, and endpoint-bound credential injection. | ## Gateways and Sandboxes diff --git a/docs/about/installation.mdx b/docs/about/installation.mdx index e27d378381..9349ed51ca 100644 --- a/docs/about/installation.mdx +++ b/docs/about/installation.mdx @@ -3,11 +3,14 @@ # SPDX-License-Identifier: Apache-2.0 title: "Installation" sidebar-title: "Installation" -description: "Install OpenShell, choose a compute driver, and connect to a gateway." +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: 3 --- +Install OpenShell on a local workstation, choose the runtime that runs +your sandboxes, and verify the package-managed gateway configuration. + ## Install OpenShell Install OpenShell with a single command: @@ -20,37 +23,35 @@ The script detects your operating system and installs the OpenShell CLI, standal You can also download release artifacts directly from the [OpenShell GitHub Releases](https://github.com/NVIDIA/OpenShell/releases) page. -### Install a prerelease - -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 rejects expired candidates, downloads only the artifact required for your platform, and installs with Debian, RPM, or Homebrew. Installed packages retain the candidate's exact version, such as `0.1.0-pre.3`. Prerelease tags do not create entries on the GitHub Releases page. +Use `openshell status` to confirm the CLI can reach the gateway. -The `openshell` package on PyPI provides the Python SDK only. It does not install the `openshell` CLI. Add the SDK to a Python project with: +## Release Cadence -```shell -uv add openshell -``` +OpenShell publishes stable versions as coordinated release sets. The default +installer selects the newest stable release, and the `latest` documentation +channel follows that release. Use the same version of the gateway, compute and +credential drivers, supervisors, CLI, and SDK clients together. -Use `openshell status` to confirm the CLI can reach the gateway. +Between stable releases, numbered prereleases such as `0.1.0-pre.3` provide +evaluation checkpoints. Rolling development builds track successful releases +from `main` and use versions such as `0.0.0-dev.`. Prerelease and +development builds may change before the next stable release; their matching +documentation is published in the `dev` channel. -## Supported Compute Drivers +## Supported Runtimes -OpenShell supports several local compute drivers. Package-managed gateways leave the driver unset by default so the gateway can auto-detect an available driver. Set `compute_driver` in the gateway TOML when you need to pin a specific driver. +OpenShell supports several sandbox runtimes. Package-managed gateways leave the +runtime unset by default so the gateway can auto-detect an available backend. +Set `compute_driver` in the gateway TOML when you need to pin a specific +runtime. -| Compute Driver | How It Is Configured | System Requirements | +| 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.0 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). +For detailed runtime behavior, refer to [Sandbox Runtimes](/reference/sandbox-compute-drivers). For gateway and sandbox operations, refer to [Gateways](/sandboxes/manage-gateways) and [Sandboxes](/sandboxes/manage-sandboxes). ## macOS @@ -160,14 +161,6 @@ sudo systemctl restart snap.openshell.gateway Kubernetes deployments use the OpenShell Helm chart. For step-by-step installation, refer to [Kubernetes Setup](/kubernetes/setup). For chart values and packaging details, 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 run the gateway as a container without the installer, refer to [Running the Gateway as a Container](/about/container-gateway). -- 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). - ## Validate a package-managed gateway configuration Debian and Ubuntu packages validate the selected gateway configuration before @@ -194,3 +187,11 @@ Snap replays its effective daemon arguments through preflight and gives a nonemp `OPENSHELL_GATEWAY_CONFIG` precedence over `SNAP_COMMON/gateway.toml`. See [Gateway Configuration](/reference/gateway-config#gateway-config-preflight) for preflight details and manual schema-v1 migration steps. + +## Next Steps + +- To prepare an image and launch an agent, refer to [Run Your First Agent](/about/run-an-agent). +- To run the gateway as a container without the installer, refer to [Running the Gateway as a Container](/reference/container-gateway). +- 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 4c8a234e73..3e8632080f 100644 --- a/docs/about/overview.mdx +++ b/docs/about/overview.mdx @@ -10,6 +10,12 @@ position: 1 NVIDIA OpenShell is an open-source runtime for executing autonomous AI agents in sandboxed environments with kernel-level isolation. It combines sandbox runtime controls and a declarative YAML policy so teams can run agents without giving them unrestricted access to local files, credentials, and external networks. + +New in OpenShell 0.1.0 is a [stable release cadence](/about/installation#release-cadence), a stronger [security model](/about/how-it-works), and an expanded [extension surface](/extensibility/extension-negotiation), along with much more. + +See our [upgrade guide](/upgrade/0-1-0) for everything that's changed. + + ## Why OpenShell Exists AI agents are most useful when they can read files, install packages, call APIs, and use credentials. That same access can create material risk. OpenShell is designed for this tradeoff: preserve agent capability while enforcing explicit controls over what the agent can access. @@ -54,5 +60,5 @@ OpenShell supports a range of agent deployment patterns. Explore these topics to go deeper: - 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 prepare an image and launch an agent, refer to [Run Your First Agent](/about/run-an-agent). - 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 deleted file mode 100644 index 62a3094b87..0000000000 --- a/docs/about/release-notes.mdx +++ /dev/null @@ -1,79 +0,0 @@ ---- -# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -# SPDX-License-Identifier: Apache-2.0 -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: 6 ---- - -NVIDIA OpenShell follows a frequent release cadence. Use the following GitHub resources directly. - -## 0.1.0 migration notes - -### Workload images - -The default workload image is now `nvcr.io/nvidia/base/ubuntu:24.04`. It is a -minimal Ubuntu Noble environment and does not include agent CLIs or an -image-baked OpenShell policy. OpenShell applies its built-in restrictive policy -when no explicit policy is supplied. - -The CLI no longer expands bare catalog names or supports the former catalog -registry override. Build or select an OCI image and pass its explicit reference: - -```shell -openshell sandbox create --from registry.example.com/agents/my-agent:1.0 -- my-agent -``` - -Gateway operators can replace the default with the driver configuration or the -Helm `server.sandboxImage` value. - -### Network endpoint TLS handling - -OpenShell 0.1.0 closes the network endpoint `tls` field to two forms: omit it to auto-detect and terminate TLS for inspection, or set `skip` to stop inspecting that endpoint. The gateway, the sandbox supervisor, provider profile lint, and agent-authored policy proposals all reject any other value, including the former `terminate` and `passthrough` spellings. - -Remove the `tls` field from affected endpoints before upgrading. Removal preserves behavior, because `terminate` and `passthrough` already selected automatic termination. - -Do not substitute `tls: skip` for a removed `terminate`. `skip` stops TLS inspection, credential placeholder rewriting, dynamic token grant injection, and L7 rule enforcement for that endpoint, so it widens what the endpoint allows. - -A stored policy carrying a removed value fails validation on read, and affected sandboxes cannot start. Run `openshell policy list --global` to see which revision is invalid and why, then re-apply a corrected policy with `openshell policy set --global`. - -A policy baked into a workload image at `/etc/openshell/policy.yaml` is rejected the same way, because the supervisor requests it over the sandbox boundary when the gateway has no policy for the sandbox. Setting a policy with `openshell policy set --global` repairs that case too; rebuilding the image without the field restores the original behavior. - -### Provider profiles are import-only - -OpenShell 0.1.0 stops compiling provider profiles into the gateway binary. A gateway's catalog contains exactly the profiles an operator imported, the default `provider_profile_sources` is `[{ type = "user" }]`, and the `builtin` source type is removed: a `gateway.toml` that still names it is rejected at startup with the import command. A gateway with nothing imported reaches ready and serves an empty catalog. - -Export the profiles your deployment relies on **before** upgrading: - -```shell -openshell provider profile export -o yaml --global > .yaml -``` - -After upgrading, import them at the scope your providers use. You can also take them from the `providers/` directory of the matching release tag: - -```shell -openshell provider profile import --from ./providers --global -``` - -Omit `--global` for workspace-scoped providers. The canonical IDs are no longer reserved, so `github`, `openai`, `pypi` and the rest import at their own IDs, and the imported profile is the only definition for that ID. - -A provider whose profile is absent after the upgrade stays listable and exportable, but creating a sandbox with it, or attaching it to one, fails with a message naming the provider, the missing profile ID, and the import command. Legacy provider type aliases are gone with the compiled catalog: use a profile's own ID, so `--type claude-code` rather than `--type claude`, and `--type github` rather than `--type gh`. - -Command-to-provider inference is removed. `openshell sandbox create -- ` no longer derives a provider from the trailing command, and the compiled alias table that drove it is gone. A profile's `binaries` list authorizes a binary to reach that profile's endpoints; it is not a statement that running the binary asks for the provider, so treating it as attachment intent could attach credentials the operator did not select. Name providers explicitly with `--provider `, which still creates a missing provider from local discovery when the name matches an imported profile ID. - -The files under `providers/` are reviewable examples, not defaults. Read each file's header before importing it: several bind network access to binary paths from the image layout where they were authored, and imported unchanged into another image the profile matches nothing. - -### Network policy binaries - -OpenShell 0.1.0 removes the deprecated `NetworkBinary.harness` protobuf field and reserves its field number and name. Generated protobuf decoders ignore the unknown value. When the gateway loads policy history written by an older version, it migrates binaries marked by the former field into endpoint-provenance-marked rules so the upgrade cannot widen private-address access. - -Remove `harness` from sandbox policies and provider profiles before upgrading. Policy and profile YAML now reject the property. Provider profiles should list binaries as scalar paths, such as `- /usr/bin/curl`; the transitional object form `- path: /usr/bin/curl` remains accepted and is exported as a scalar. - -| Resource | Description | -|---|---| -| [Releases](https://github.com/NVIDIA/OpenShell/releases) | Versioned release notes and downloadable assets. | -| [Release comparison](https://github.com/NVIDIA/OpenShell/compare) | Diff between any two tags or branches. | -| [Merged pull requests](https://github.com/NVIDIA/OpenShell/pulls?q=is%3Apr+is%3Amerged) | Individual changes with review discussion. | -| [Commit history](https://github.com/NVIDIA/OpenShell/commits/main) | Full commit log on `main`. | diff --git a/docs/about/run-an-agent.mdx b/docs/about/run-an-agent.mdx new file mode 100644 index 0000000000..46581d54c5 --- /dev/null +++ b/docs/about/run-an-agent.mdx @@ -0,0 +1,132 @@ +--- +# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 +title: "Run Your First Agent" +sidebar-title: "Run Your First Agent" +description: "Prepare a sandbox image, provider profile, and policy for an AI agent or another autonomous workload." +keywords: "Generative AI, Cybersecurity, AI Agents, Sandboxing, Provider Profiles, Policies, Custom Images" +position: 4 +--- + +OpenShell can run an AI agent or another autonomous command when its executable +is available in the sandbox image. The image, provider profile, and policy +define what the workload can execute and access. OpenShell does not require the +agent to use a specific framework or model API. + +## Prepare the Workload + +An agent needs three pieces: + +| Requirement | Purpose | +|---|---| +| Sandbox image | Contains the agent executable and its runtime dependencies. | +| Provider profile | Declares credential fields, service endpoints, and the executable paths allowed to use them. | +| Sandbox policy | Controls filesystem access, process behavior, and network destinations beyond access contributed by attached providers. | + +Build and maintain an OCI image for each workload. Install the agent, shell, +development tools, CA certificates, and language runtimes that the workload +needs. Use pinned versions so you can review and reproduce image updates. + +```shell +docker build -t registry.example.com/team/agent:1.0 . +docker push registry.example.com/team/agent:1.0 +openshell sandbox create --from registry.example.com/team/agent:1.0 +``` + +The `--from` option also accepts a local rootfs archive. It does not build a +Dockerfile or directory. Refer to +[Custom Containers](/sandboxes/manage-sandboxes#custom-containers) for image and +runtime details. The fallback image contains no agent or development toolchain, +so pass your image explicitly for agent workloads. + +## Prepare Provider Access + +A provider profile defines the credentials and endpoints an agent uses. The +gateway serves only profiles that an administrator or user has imported. +Review a profile before importing it, especially its executable paths and +network endpoints. + +```shell +curl -LsSfO https://raw.githubusercontent.com/NVIDIA/OpenShell/main/providers/claude-code.yaml +openshell profile import -f claude-code.yaml --global +ANTHROPIC_API_KEY= \ + openshell provider create --name my-claude --type claude-code --from-existing +``` + +The repository includes example profiles in +[`providers/`](https://github.com/NVIDIA/OpenShell/tree/main/providers). Copy +and adapt an example when the agent binary is installed at another path or uses +a different service endpoint. Refer to [Profiles](/providers/profiles) for the +profile schema and import workflow. + +## Launch the Agent + +Pass the agent command after `--` and attach the provider instances it needs. +For example, this command starts Claude Code from an image your team built with +the `claude` executable installed: + +```shell +openshell sandbox create \ + --from registry.example.com/team/claude-code:1.0 \ + --provider my-claude \ + -- claude +``` + +The command before `--` configures the sandbox. The command after `--` becomes +the sandbox's main process. OpenShell keeps the sandbox after that process exits +unless you pass `--no-keep`. + +Use `--detach` for an unattended or long-running agent: + +```shell +openshell sandbox create \ + --name worker \ + --detach \ + --from my-registry.example.com/team/agent:latest \ + --provider model-provider \ + -- ./worker +``` + +Use a profile-backed provider for credentials that the agent should not read +directly. Plain values passed with `--env` are visible to the agent process. + +## Build an Agent Image + +Prepare each agent as part of your normal container build and release process: + +1. Select a trusted base image and install the agent executable and tools. +2. Create or adapt provider profiles for every external service the agent uses. +3. Add policy rules for required files, child processes, package registries, + tool servers, and other network destinations. +4. Build, scan, sign, and publish the image to a registry the gateway can pull. +5. Launch the executable as the sandbox's main process. + +Provider profiles can contribute endpoint and executable rules to the effective +policy. They do not grant unrelated network or filesystem access. Use +[Customize Sandbox Policies](/sandboxes/policies) when the agent needs access +beyond its attached providers. + +## Verify and Troubleshoot + +Inspect the sandbox, effective policy, provider attachments, and logs: + +```shell +openshell sandbox list +openshell policy get my-sandbox --full +openshell sandbox provider list my-sandbox +openshell logs my-sandbox --tail +``` + +If the executable is missing, change the sandbox image. If a provider request +is denied, confirm that the profile names the actual endpoint and executable +path. For another denied network or filesystem operation, update the sandbox +policy after reviewing the requested access. + +## Next Steps + +- For sandbox lifecycle, resources, templates, files, and connectivity, refer + to [Sandboxes](/sandboxes/manage-sandboxes). +- For the restrictive fallback policy, refer to + [Default Policy](/reference/default-policy). +- For operating-system and runtime requirements, refer to the + [Support Matrix](/reference/support-matrix). diff --git a/docs/about/supported-agents.mdx b/docs/about/supported-agents.mdx deleted file mode 100644 index 601a91ebe8..0000000000 --- a/docs/about/supported-agents.mdx +++ /dev/null @@ -1,22 +0,0 @@ ---- -# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -# SPDX-License-Identifier: Apache-2.0 -title: "Supported Agents" -description: "AI agent frameworks and runtimes compatible with OpenShell sandboxes." -keywords: "Generative AI, Cybersecurity, AI Agents, Sandboxing, Claude, Codex, Cursor" -position: 5 ---- - -OpenShell can run containerized agents that support Linux. The default Ubuntu workload image does not bundle agent CLIs. Build or select an OCI image containing the agent, pass its explicit image reference to `--from`, and attach the providers and policy it needs. - -| Agent | Image workflow | Provider and policy requirements | -|---|---|---| -| [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | Add Claude Code to your workload image. | Attach a `claude-code` provider or an endpoint-bearing profile for the selected model platform. Authorize the agent binary and service endpoints. | -| [OpenCode](https://opencode.ai/) | Add OpenCode to your workload image. | Attach the selected model provider and authorize OpenCode's binary paths and service endpoints. | -| [Codex](https://developers.openai.com/codex) | Add Codex to your workload image. | Attach an OpenAI provider and authorize the Codex binary paths and OpenAI endpoints. | -| [GitHub Copilot CLI](https://docs.github.com/en/copilot/github-copilot-in-the-cli) | Add GitHub Copilot CLI to your workload image. | Attach GitHub credentials and authorize the CLI binary and required GitHub endpoints. | -| [OpenClaw](https://openclaw.ai/) | Use the [NemoClaw](https://github.com/NVIDIA/NemoClaw) blueprint. | The blueprint manages the workload and its policy. | -| [Hermes Agent](https://github.com/NousResearch/hermes-agent) | Use the [NemoClaw](https://github.com/NVIDIA/NemoClaw) blueprint. | The blueprint manages the workload and its policy. | -| [Ollama](https://ollama.com/) | Build an image containing Ollama, or connect a sandbox to a separately managed Ollama service. | Authorize the client binary and the Ollama endpoint. Refer to [Inference with Ollama](/get-started/tutorials/inference-ollama). | - -For image selection and `--from` usage, refer to [Manage Sandboxes](/sandboxes/manage-sandboxes#sandbox-images). For a complete platform matrix, refer to [Support Matrix](/reference/support-matrix). diff --git a/docs/extensibility/drivers.mdx b/docs/extensibility/drivers.mdx new file mode 100644 index 0000000000..c988b651a6 --- /dev/null +++ b/docs/extensibility/drivers.mdx @@ -0,0 +1,40 @@ +--- +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 +title: "Drivers" +description: "Understand the compute and credential driver extension points in OpenShell." +keywords: "OpenShell Extensions, Compute Drivers, Credential Drivers, Extensibility" +--- + +OpenShell uses drivers to connect the gateway to workload runtimes and +credential stores. Drivers implement a stable capability boundary while the +gateway owns the public API, authorization, workspace scoping, and resource +lifecycle. + +## Compute Drivers + +Compute drivers create, inspect, and delete sandbox workloads. OpenShell ships +drivers for Kubernetes, Docker, Podman, virtual machines, and Windows MXC. An +external compute driver communicates with the gateway over a Unix domain +socket and negotiates its protocol version and capabilities before serving +requests. + +For built-in driver configuration and behavior, refer to +[Runtimes](/reference/sandbox-compute-drivers). + +## Credential Drivers + +Credential drivers store provider credentials behind opaque handles. The +gateway resolves those handles when a provider is attached without persisting +the secret value in the provider record. OpenShell includes database, +Kubernetes Secret, and Vault-compatible credential drivers. + +Configure the active credential driver in the +[Gateway Configuration](/reference/gateway-config#credential-drivers). + +## Compatibility + +Drivers exchange peer metadata with the gateway and advertise their extension +family capability. Upgrade both peers together when the protocol version +changes. Refer to [Extensibility Overview](/extensibility/extension-negotiation) +for the negotiation contract. diff --git a/docs/extensibility/extension-negotiation.mdx b/docs/extensibility/extension-negotiation.mdx index c8e3a1d791..eca4d6a47e 100644 --- a/docs/extensibility/extension-negotiation.mdx +++ b/docs/extensibility/extension-negotiation.mdx @@ -2,7 +2,7 @@ # SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. # SPDX-License-Identifier: Apache-2.0 title: "Extension Protocol Negotiation" -sidebar-title: "Protocol Negotiation" +sidebar-title: "Overview" description: "Implement version and capability negotiation for OpenShell extensions." keywords: "OpenShell Extensions, Protocol Version, Capabilities, Version Skew, Migration" --- diff --git a/docs/extensibility/isolation-backends.mdx b/docs/extensibility/isolation-backends.mdx new file mode 100644 index 0000000000..5b6856c956 --- /dev/null +++ b/docs/extensibility/isolation-backends.mdx @@ -0,0 +1,26 @@ +--- +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 +title: "Isolation Backends" +description: "Understand the runtime boundary used to launch and supervise sandboxed workloads." +keywords: "OpenShell Extensions, Isolation Backends, Sandbox Runtime, Extensibility" +--- + +An isolation backend connects the OpenShell supervisor to the runtime that +launches and controls a sandboxed workload. It defines how the supervisor +starts processes, attaches terminal streams, forwards signals, reports exit +status, and applies runtime-specific isolation. + +OpenShell separates this interface from compute drivers. A compute driver +provisions the workload environment, while the isolation backend controls +process execution inside that environment. This boundary lets runtimes evolve +without changing the gateway API or policy model. + +The OpenShell runtime backend implements the authenticated OpenShell Sandbox +Protocol used by the supervisor and `openshell-sandbox`. Backend selection and +capabilities remain internal to the workload runtime; users create and manage +sandboxes through the same gateway API. + +For the deployment-level runtime architecture, refer to +[Sandbox Runtime](/kubernetes/sandbox-runtime). For driver-specific workload +behavior, refer to [Runtimes](/reference/sandbox-compute-drivers). diff --git a/docs/get-started/quickstart.mdx b/docs/get-started/quickstart.mdx deleted file mode 100644 index 55b1eb3ab4..0000000000 --- a/docs/get-started/quickstart.mdx +++ /dev/null @@ -1,100 +0,0 @@ ---- -# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -# SPDX-License-Identifier: Apache-2.0 -title: "Quickstart" -description: "Install the OpenShell CLI, connect to a gateway, and create your first sandboxed AI agent." -keywords: "Generative AI, Cybersecurity, AI Agents, Sandboxing, Installation, Quickstart, Gateway, Docker, Kubernetes, Podman" -position: 1 ---- - -This page gets you from a reachable OpenShell gateway to a running, policy-enforced sandbox. - -## Prerequisites - -Before you begin, make sure you have: - -- A reachable OpenShell gateway. -- 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 - -Run the install script: - -```shell -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. - -After installing the CLI, run `openshell --help` in your terminal to view the full CLI reference. - - -Install the public OpenShell agent skills with `npx skills add NVIDIA/OpenShell`. The `openshell-cli` skill guides your agent through common workflows and uses the installed CLI help as the command reference; no OpenShell source checkout is required. - - -## Import a Provider Profile - -A provider profile describes the credentials, endpoints, and client binaries a -provider needs. A gateway serves only the profiles you imported, so import one -before creating a sandbox that uses a provider. - -The OpenShell repository ships example profiles in -[`providers/`](https://github.com/NVIDIA/OpenShell/tree/main/providers). Download -the one matching your agent and import it at platform scope: - -```shell -curl -LsSfO https://raw.githubusercontent.com/NVIDIA/OpenShell/main/providers/claude-code.yaml -openshell provider profile import -f claude-code.yaml --global -``` - -Use `codex.yaml` for Codex, or `openai.yaml` for OpenCode. Confirm the catalog: - -```shell -openshell provider list-profiles -``` - - -Read the comment header at the top of each file before importing it. It names -the client binaries the profile expects and the image layout those paths assume. -If your sandbox image installs the agent somewhere else, edit `binaries` first — -otherwise the profile matches nothing and the credential is never injected. - - -## Create Your First Sandbox - -Create a sandbox with the gateway's default workload image: - -```shell -openshell sandbox create --name quickstart -``` - -The default is `nvcr.io/nvidia/base/ubuntu:24.04`. It provides a minimal Ubuntu Noble environment; install workload-specific tools in your own image. - -Connect to the sandbox: - -```shell -openshell sandbox connect quickstart -``` - -Run a command without opening an interactive session: - -```shell -openshell sandbox exec -n quickstart -- cat /etc/os-release -``` - -## Run an Agent Image - -Build an OCI image containing your agent and its dependencies, then pass its full image reference: - -```shell -docker build -t my-agent:latest ./my-agent -openshell sandbox create --from my-agent:latest -- my-agent -``` - -For a Podman gateway, build and use a Podman-visible name such as `localhost/my-agent:latest`. For a remote gateway, push the image to a registry that the gateway can pull from. - -Attach a provider and a policy that authorize the agent's credentials, endpoints, and executable paths. Refer to [Bring Your Own Container](https://github.com/NVIDIA/OpenShell/tree/main/examples/bring-your-own-container), [Providers](/providers), and [Customize Sandbox Policies](/sandboxes/policies). diff --git a/docs/get-started/tutorials/docker-compose.mdx b/docs/get-started/tutorials/docker-compose.mdx deleted file mode 100644 index 33f6b0c1d3..0000000000 --- a/docs/get-started/tutorials/docker-compose.mdx +++ /dev/null @@ -1,207 +0,0 @@ ---- -# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -# SPDX-License-Identifier: Apache-2.0 -title: "Run the Gateway with Docker Compose" -sidebar-title: "Docker Compose Setup" -slug: "get-started/tutorials/docker-compose" -description: "Run the OpenShell gateway as a Docker Compose service and create agent sandboxes." -keywords: "Generative AI, Docker Compose, Gateway, Sandbox, OpenClaw, Docker, Installation" ---- - -This tutorial shows how to run the OpenShell gateway as a Docker Compose service on a Linux host or on a machine running Docker Desktop (Windows or macOS). - -After completing this tutorial you have: - -- An OpenShell gateway running as a Compose service. -- The `openshell` CLI registered against that gateway. -- An AI provider configured with your API key. -- A running agent sandbox. - -## Prerequisites - -- Docker Desktop (Windows or macOS) or Docker Engine with the Compose plugin (Linux). -- The `openshell` CLI installed on your workstation. See [Install the CLI](#install-the-cli) below. -- Port 8080 available on the host. - -## Compose files - -The Compose configuration lives at [`deploy/docker/`](https://github.com/NVIDIA/OpenShell/tree/main/deploy/docker) in the repository. - -| File | Purpose | -|---|---| -| `docker-compose.yml` | Gateway service, volumes, and environment variables | -| `gateway.toml` | TOML reference for release builds with config-file support | - -## Port note - -The Docker supervisor uses host networking and connects to the gateway through -the host's loopback port. The gateway listens on port 8080 inside the container, -so **port 8080 must be published at the same number on the Docker host**. -Publishing it as a different host port (for example `18080:8080`) leaves the -supervisor unable to establish its gateway session and the sandbox remains in -the `Provisioning` phase. - -If port 8080 is taken, change `OPENSHELL_SERVER_PORT` and update the port mapping to `:8080`, then set `OPENSHELL_PORT=` in an `.env` file. - -## Data directory - -The gateway extracts the `openshell-sandbox` supervisor binary from `ghcr.io/nvidia/openshell/supervisor:latest` on first start and caches it at: - -```text -/var/lib/openshell/openshell/docker-supervisor//openshell-sandbox -``` - -This path is used as a bind-mount source when Docker creates sandbox containers. -Docker resolves bind-mount sources against the **host filesystem**, not the container filesystem, so the data directory must be bind-mounted at the **same absolute path** in both the host and the container. - -The Compose file uses `/var/lib/openshell` for this purpose and sets `create_host_path: true` so Docker creates it on first run. - -## Start the gateway - -```shell -cd deploy/docker -docker compose up -d -``` - -Verify the gateway is healthy: - -```shell -curl -sf http://localhost:8080/healthz -``` - -## Install the CLI - -**Binary (recommended — macOS / Linux / WSL):** - -```shell -curl -LsSf https://raw.githubusercontent.com/NVIDIA/OpenShell/main/install.sh | sh -``` - - -The `openshell` package on PyPI provides the Python SDK only and does not install the CLI. - -On Windows without WSL, install the CLI inside a WSL 2 distribution (for example AlmaLinux or Ubuntu) and run all `openshell` commands from that distribution. - - -## Register the gateway - -Run this once after the gateway starts: - -```shell -openshell gateway add http://localhost:8080 --name openshell-docker -``` - -Verify the connection: - -```shell -openshell status -``` - -The output should show `Status: Connected`. - -## Configure an AI provider - -Import the provider profile for the service you use, then set your API key as an -environment variable and create a provider. A gateway serves only the profiles -you imported: - -```shell -curl -LsSfO https://raw.githubusercontent.com/NVIDIA/OpenShell/main/providers/anthropic.yaml -openshell provider profile import -f anthropic.yaml --global -``` - -Use `openai.yaml` for the OpenAI tab below. - - - - -```shell -ANTHROPIC_API_KEY=sk-ant-... \ - openshell provider create --name anthropic --type anthropic --from-existing -``` - - - - -```shell -OPENAI_API_KEY=sk-... \ - openshell provider create --name openai --type openai --from-existing -``` - - - - -Confirm the provider was stored: - -```shell -openshell provider list -``` - -## Pre-pull workload images (optional) - -Workload images are pulled automatically on first use. Pre-pull the default -Ubuntu workload or your own agent image to avoid waiting during sandbox -creation: - -```shell -docker pull nvcr.io/nvidia/base/ubuntu:24.04 -docker pull registry.example.com/your-org/agent:latest -``` - -## Create a Sandbox - -Create a minimal Ubuntu sandbox: - -```shell -openshell sandbox create --name compose-demo -``` - -To run an agent, use an explicit OCI image that contains it: - -```shell -openshell sandbox create \ - --from registry.example.com/your-org/agent:latest \ - --provider \ - -- my-agent -``` - -OpenClaw runs through [NemoClaw](https://github.com/NVIDIA/NemoClaw), which -manages its sandbox image, model provider, and security policies. Follow the -[NemoClaw Quickstart](https://docs.nvidia.com/nemoclaw/latest/get-started/quickstart/) -for that workflow. - -Wait for the phase to change from `Provisioning` to `Ready`: - -```shell -openshell sandbox list -``` - -Then connect: - -```shell -openshell sandbox connect -``` - -## Manage the gateway - -| Command | Purpose | -|---|---| -| `docker compose up -d` | Start or restart the gateway | -| `docker compose down` | Stop the gateway and remove the container | -| `docker compose logs -f` | Tail gateway logs | -| `docker compose pull` | Pull a new gateway image version | - -## Linux notes - -On Linux, `host.docker.internal` and `host.openshell.internal` are not automatically resolvable from containers. Add the following under the `gateway` service in `docker-compose.yml`: - -```yaml -extra_hosts: - - "host.docker.internal:host-gateway" - - "host.openshell.internal:host-gateway" -``` - -## Next steps - -- [First Network Policy](/get-started/tutorials/first-network-policy) — apply L7 policies to your sandbox. -- [GitHub Push Access](/get-started/tutorials/github-sandbox) — grant a sandbox scoped GitHub access. diff --git a/docs/get-started/tutorials/first-network-policy.mdx b/docs/get-started/tutorials/first-network-policy.mdx index cbf9eaaf92..1a5cf67786 100644 --- a/docs/get-started/tutorials/first-network-policy.mdx +++ b/docs/get-started/tutorials/first-network-policy.mdx @@ -19,8 +19,9 @@ After completing this tutorial, you understand: ## Prerequisites -- A working OpenShell installation. Complete the [Quickstart](/get-started/quickstart) before proceeding. +- A working OpenShell installation with an active gateway. Refer to [Installation](/about/installation) before proceeding. - Docker Desktop running on your machine. +- A user-owned workload image with `curl` installed. To run every step of this tutorial, you can also use the automated demo script at the [examples/sandbox-policy-quickstart](https://github.com/NVIDIA/OpenShell/blob/main/examples/sandbox-policy-quickstart) directory in the NVIDIA OpenShell repository. It runs the full walkthrough in under a minute but without any user interaction. @@ -38,7 +39,10 @@ bash examples/sandbox-policy-quickstart/demo.sh Start by creating a sandbox with no network policies. This gives you a clean environment to observe default-deny behavior. ```shell -openshell sandbox create --name demo --no-auto-providers +openshell sandbox create \ + --name demo \ + --from registry.example.com/team/agent-tools:1.0 \ + --no-auto-providers ``` `--no-auto-providers` skips the provider setup prompt since this tutorial uses `curl` instead of an AI agent. diff --git a/docs/get-started/tutorials/github-sandbox.mdx b/docs/get-started/tutorials/github-sandbox.mdx index 6be5b3445c..2e52826e77 100644 --- a/docs/get-started/tutorials/github-sandbox.mdx +++ b/docs/get-started/tutorials/github-sandbox.mdx @@ -4,226 +4,140 @@ title: "Grant GitHub Push Access to a Sandboxed Agent" sidebar-title: "GitHub Push Access" slug: "get-started/tutorials/github-sandbox" -description: "Learn the iterative policy workflow by launching a sandbox, diagnosing a GitHub access denial, and applying a custom policy to fix it." +description: "Launch an agent with a GitHub provider, diagnose a denied push, and grant repository-scoped write access." keywords: "Generative AI, Cybersecurity, Tutorial, GitHub, Sandbox, Policy, Claude Code" --- -This tutorial walks through an iterative sandbox policy workflow. You launch a sandbox, ask Claude Code to push code to GitHub, and observe the default network policy denying the request. -You then diagnose the denial from your machine and from inside the sandbox, apply a policy update, and verify that the policy update to the sandbox takes effect. +This tutorial shows how provider access and sandbox policy work together. You +attach a GitHub provider that contributes read-only GitHub access, observe a +denied push, and add a user policy that permits writes to one repository. -After completing this tutorial, you have: - -- A running sandbox with Claude Code that can push to a GitHub repository. -- A custom network policy that grants GitHub access for a specific repository. -- Experience with the policy iteration workflow: fail, diagnose, update, verify. - - -This tutorial shows example prompts and responses from Claude Code. The exact wording you see might vary between sessions. Use the examples as a guide for the type of interaction, not as expected output. - - +The built-in [default policy](/reference/default-policy) does not grant network +access. Imported provider profiles contribute the endpoints and executable +paths needed by their providers. ## Prerequisites -This tutorial requires the following: - -- A working OpenShell installation. Complete the [Quickstart](/get-started/quickstart) before proceeding. -- A GitHub personal access token (PAT) with `repo` scope. Generate one from the [GitHub personal access token settings page](https://github.com/settings/tokens) by selecting **Generate new token (classic)** and enabling the `repo` scope. -- An [Anthropic account](https://console.anthropic.com/) with access to Claude Code. OpenShell provides the sandbox runtime, not the agent. You must authenticate with your own account. -- A GitHub repository you own to use as the push target. A scratch repository is sufficient. You can [create one](https://github.com/new) with a README if needed. - -This tutorial uses two terminals to demonstrate the iterative policy workflow: +You need: -- **Terminal 1**: The sandbox terminal. You create the sandbox in this terminal by running `openshell sandbox create` and interact with Claude Code inside it. -- **Terminal 2**: A terminal outside the sandbox on your machine. You use this terminal for viewing the sandbox logs with `openshell term` and applying an updated policy with `openshell policy set`. +- A working OpenShell installation and active gateway. +- An OCI image you built with Claude Code, `git`, and the GitHub CLI installed. +- An Anthropic API key. +- A GitHub fine-grained personal access token with read and write access to the + target repository's contents. +- A scratch GitHub repository that you can push to. -Each section below indicates which terminal to use. +Use two host terminals. Terminal 1 runs the agent. Terminal 2 inspects denials +and updates policy. -## Set Up a Sandbox with Your GitHub Token +## Import the Provider Profiles -Depending on whether you start a new sandbox or use an existing sandbox, choose the appropriate tab and follow the instructions. - - - - -In terminal 2, create a new sandbox with Claude Code. The [default policy](/reference/default-policy) is applied automatically, which allows read-only access to GitHub. - -Create a [credential provider](/sandboxes/manage-providers) that injects your GitHub token into the sandbox automatically. The provider reads `GITHUB_TOKEN` from your host environment and sets it as an environment variable inside the sandbox: +Download and review the Claude Code and GitHub profiles. Confirm that their +`binaries` paths match the executables in your image, then import them: ```shell +curl -LsSfO https://raw.githubusercontent.com/NVIDIA/OpenShell/main/providers/claude-code.yaml curl -LsSfO https://raw.githubusercontent.com/NVIDIA/OpenShell/main/providers/github.yaml -openshell provider profile import -f github.yaml --global - -GITHUB_TOKEN= -openshell provider create --name my-github --type github --from-existing -openshell sandbox create --from registry.example.com/your-org/claude-agent:latest --provider my-github -- claude +openshell profile import -f claude-code.yaml --global +openshell profile import -f github.yaml --global ``` -The import step registers the `github` profile on your gateway. OpenShell ships -no profiles inside the gateway binary, so `--type github` resolves only after the -profile is imported. Import it once per gateway. +The gateway contains no built-in profiles. Import each profile once per gateway +at the scope where users need it. -`openshell sandbox create` keeps the sandbox running after Claude Code exits, so you can apply policy updates later without recreating the environment. Add `--no-keep` if you want the sandbox deleted automatically instead. +## Create the Providers -Claude Code starts inside the sandbox. It prints an authentication link. Open it in your browser, sign in to your Anthropic account, and return to the terminal. When prompted, trust the `/sandbox` workspace to allow Claude Code to read and write files. - - - - -In terminal 1, connect to a sandbox that is already running and set your GitHub token as an environment variable: +Create provider instances from credentials in your host environment. Passing a +credential on the same command line exports it only to that command: ```shell -openshell sandbox connect -export GITHUB_TOKEN= -``` - -To find the name of running sandboxes, run `openshell sandbox list` in terminal 2. - - - - - -## Push Code to GitHub +ANTHROPIC_API_KEY= \ + openshell provider create --name my-claude --type claude-code --from-existing -In terminal 1, ask Claude Code to write a simple script and push it to your repository. Replace `` with your GitHub organization or username and `` with your repository name. - -```md title="Prompt" wordWrap showLineNumbers={false} -Write a `hello_world.py` script and push it to `https://github.com//`. +GITHUB_TOKEN= \ + openshell provider create --name my-github --type github --from-existing ``` -Claude recognizes that it needs GitHub credentials. It asks how you want to authenticate. Provide your GitHub personal access token by pasting it into the conversation. Claude configures authentication and attempts the push. - -The push fails. Claude reports an error, but the failure is not an authentication problem. The default sandbox policy permits read-only access to GitHub and blocks write operations, so the proxy denies the push before the request reaches the GitHub server. - -## Diagnose the Denial +OpenShell stores the credentials through the configured credential driver. The +agent receives opaque placeholders; the sandbox proxy resolves them only for +endpoints allowed by the corresponding profile. -In this section, you diagnose the denial from your machine and from inside the sandbox. +## Start the Agent -### View the Logs from Your Machine - -In terminal 2, launch the OpenShell terminal: +In terminal 1, start Claude Code from your image and attach both providers: ```shell -openshell term +openshell sandbox create \ + --name github-demo \ + --from registry.example.com/your-org/claude-agent:latest \ + --provider my-claude \ + --provider my-github \ + -- claude ``` -The dashboard shows sandbox status and a live stream of policy decisions. Look for entries with `l7_decision=deny`. Select a deny entry to see the full detail: +To use an existing sandbox, attach the providers from a host terminal, then +start a new agent process so it receives the provider environment variables: -```text -l7_action: PUT -l7_target: /repos///contents/hello_world.py -l7_decision: deny -dst_host: api.github.com -dst_port: 443 -l7_protocol: rest -policy: github_rest_api -l7_deny_reason: PUT /repos///contents/hello_world.py not permitted by policy +```shell +openshell sandbox provider attach my-claude +openshell sandbox provider attach my-github +openshell sandbox connect ``` -The log shows that the sandbox proxy intercepted an outbound `PUT` request to `api.github.com` and denied it. The `github_rest_api` policy allows read operations (GET) but blocks write operations (PUT, POST, DELETE) to the GitHub API. A similar denial appears for `github.com` if Claude attempted a git push over HTTPS. +## Attempt a Push -### Ask Claude Code to Check the Sandbox Logs - -In terminal 1, ask Claude Code to check the sandbox logs for denied requests: +Ask the agent to create a file and push it to your scratch repository. Replace +`` and `` with the repository owner and name: ```md title="Prompt" wordWrap showLineNumbers={false} -Check the sandbox logs for any denied network requests. What is blocking the push? +Create `hello_world.py`, commit it, and push it to +`https://github.com//.git`. Use the GitHub credentials already +available in the environment. Do not ask me to paste a token. ``` -Claude reads the deny entries and identifies the root cause. It explains that the failure is a sandbox network policy restriction, not a token permissions issue. For example, the following is a possible response: - - -The sandbox runs a proxy that enforces policies on outbound traffic. -The `github_rest_api` policy allows GET requests (used to read the file) -but blocks PUT/write requests to GitHub. This is a sandbox-level restriction, -not a token issue. No matter what token you provide, pushes through the API -are blocked until you update the policy. - - -Both perspectives confirm the same thing: the proxy is doing its job. The default policy is designed to be restrictive. To allow GitHub pushes, you need to update the network policy. - -Copy the deny reason from Claude's response. You paste it into an agent running on your machine in the next step. +The push fails. The GitHub profile permits clone and fetch operations but does +not permit `git-receive-pack`, the Git Smart HTTP operation used for a push. +The credential remains attached and endpoint-scoped; changing the token would +not grant the missing network authority. -## Update the Policy from Your Machine +## Inspect the Denial -In terminal 2, paste the deny reason from the previous step into your coding agent on your machine, such as Claude Code or Cursor, and ask it to recommend a policy update. The deny reason gives the agent the context it needs to generate the correct policy rules. After pasting the following prompt sample, properly provide the GitHub organization and repository names of the repository you are pushing to. +In terminal 2, inspect recent sandbox logs: -```md title="Prompt" wordWrap showLineNumbers={false} -Based on the following deny reasons, recommend a sandbox policy update that allows GitHub pushes to `https://github.com//`, and save to `/tmp/sandbox-policy-update.yaml`: - -The `filesystem_policy` and `landlock` sections are static. They are read once at sandbox creation and cannot be changed by a hot reload. They are included here for completeness so the file is self-contained. Process identity is omitted so the active compute driver can select it, and only the `network_policies` section takes effect when you apply this to a running sandbox. +```shell +openshell logs github-demo --level warn --since 5m ``` -The following steps outline the expected process done by the agent: - -1. Inspects the deny reasons. -2. Writes an updated policy that adds `github_git` and `github_api` blocks that grant write access to your repository. -3. Saves the policy to `/tmp/sandbox-policy-update.yaml`. +You should see a denial for a request resembling this one: -## Review the Generated Policy - -Refer to the following policy example to compare with the generated policy before applying it. Confirm that the policy grants only the access you expect. In this case, `git push` operations and GitHub REST API access scoped to a single repository. +```text +action=deny dst_host=github.com dst_port=443 binary=/usr/bin/git l7_action=POST l7_target=//.git/git-receive-pack +``` - +You can also run `openshell term` to inspect policy decisions in the terminal +dashboard. -The following YAML shows a complete policy that extends the [default policy](/reference/default-policy) with GitHub access for a single repository. Replace `` with your GitHub organization or username and `` with your repository name. +## Create a Repository-Scoped Policy -The `filesystem_policy` and `landlock` sections are static. OpenShell reads them at sandbox creation, and a hot reload cannot change them. They are included here for completeness so the file is self-contained. Process identity is omitted so the active compute driver can select it, and only the `network_policies` section takes effect when you apply this to a running sandbox. +Create `github-push.yaml`. Replace `` and ``, and adjust `binaries` +to match your image: ```yaml version: 1 -# ── Static (locked at sandbox creation) ────────────────────────── - filesystem_policy: include_workdir: true - read_only: - - /usr - - /lib - - /proc - - /dev/urandom - - /app - - /etc - - /var/log - read_write: - - /tmp - - /dev/null + read_only: [/usr, /lib, /proc, /dev/urandom, /etc, /var/log] + read_write: [/tmp, /dev/null] landlock: compatibility: best_effort -# ── Dynamic (hot-reloadable) ───────────────────────────────────── - network_policies: - - # Claude Code ↔ Anthropic API - claude_code: - name: claude-code - endpoints: - - { host: api.anthropic.com, port: 443, protocol: rest, enforcement: enforce, access: full } - - { host: statsig.anthropic.com, port: 443 } - - { host: sentry.io, port: 443 } - - { host: raw.githubusercontent.com, port: 443 } - - { host: platform.claude.com, port: 443 } - binaries: - - { path: /usr/local/bin/claude } - - { path: /usr/bin/node } - - # NVIDIA inference endpoint - nvidia_inference: - name: nvidia-inference - endpoints: - - { host: integrate.api.nvidia.com, port: 443 } - binaries: - - { path: /usr/bin/curl } - - { path: /bin/bash } - - { path: /usr/local/bin/opencode } - - # ── GitHub: git operations (clone, fetch, push) ────────────── - - github_git: - name: github-git + github_repository_push: + name: github-repository-push endpoints: - host: github.com port: 443 @@ -240,126 +154,70 @@ network_policies: method: POST path: "//.git/git-receive-pack" binaries: - - { path: /usr/bin/git } + - path: /usr/bin/git + - path: /usr/local/bin/git - # ── GitHub: REST API ───────────────────────────────────────── - - github_api: - name: github-api + github_repository_api: + name: github-repository-api endpoints: - host: api.github.com port: 443 - path: "/repos///**" protocol: rest enforcement: enforce rules: - # Full read-write access to the repository - allow: method: "*" path: "/repos///**" - - host: api.github.com - port: 443 - path: "/graphql" - protocol: graphql - enforcement: enforce - rules: - # GitHub GraphQL API (used by gh CLI) - - allow: - operation_type: query - - allow: - operation_type: mutation - fields: [createIssue, updateIssue, addComment] - deny_rules: - - operation_type: mutation - fields: [deleteRepository, deleteRef, updateBranchProtectionRule] - binaries: - - { path: /usr/local/bin/claude } - - { path: /usr/local/bin/opencode } - - { path: /usr/bin/gh } - - { path: /usr/bin/curl } - - # ── Package managers ───────────────────────────────────────── - - pypi: - name: pypi - endpoints: - - { host: pypi.org, port: 443 } - - { host: files.pythonhosted.org, port: 443 } - - { host: github.com, port: 443 } - - { host: objects.githubusercontent.com, port: 443 } - - { host: api.github.com, port: 443 } - - { host: downloads.python.org, port: 443 } - binaries: - - { path: /sandbox/.venv/bin/python } - - { path: /sandbox/.venv/bin/python3 } - - { path: /sandbox/.venv/bin/pip } - - { path: "/sandbox/.uv/python/**/python*" } - - { path: /usr/local/bin/uv } - - { path: "/sandbox/.uv/python/**" } - - # ── VS Code Remote ────────────────────────────────────────── - - vscode: - name: vscode - endpoints: - - { host: update.code.visualstudio.com, port: 443 } - - { host: "*.vo.msecnd.net", port: 443 } - - { host: vscode.download.prss.microsoft.com, port: 443 } - - { host: marketplace.visualstudio.com, port: 443 } - - { host: "*.gallerycdn.vsassets.io", port: 443 } binaries: - - { path: /usr/bin/curl } - - { path: /usr/bin/wget } - - { path: "/sandbox/.vscode-server/**" } - - { path: "/sandbox/.vscode-remote-containers/**" } + - path: /usr/bin/gh + - path: /usr/local/bin/gh ``` -The following table summarizes the two GitHub-specific blocks: - -| Block | Endpoint | Behavior | -|---|---|---| -| `github_git` | `github.com:443` | Git Smart HTTP protocol. The proxy auto-detects and terminates TLS to inspect requests. Permits `info/refs` (clone/fetch), `git-upload-pack` (fetch data), and `git-receive-pack` (push) for the specified repository. Denies all operations on unlisted repositories. | -| `github_api` | `api.github.com:443` | REST API. The proxy auto-detects and terminates TLS to inspect requests. Permits all HTTP methods for the specified repository and GraphQL queries. Denies API access to unlisted repositories. | +The first entry grants Git Smart HTTP operations only for the selected +repository. The second lets `gh` use REST operations scoped to the same +repository. The attached GitHub provider continues to supply credential +placement and its broader read-only rules. -The remaining blocks (`claude_code`, `nvidia_inference`, `pypi`, `vscode`) are identical to the [default policy](/reference/default-policy). The default policy's `github_ssh_over_https` and `github_rest_api` blocks are replaced by the `github_git` and `github_api` blocks above, which grant write access to the specified repository. Sandbox behavior outside of GitHub operations is unchanged. - -For details on policy block structure, refer to [Policies](/sandboxes/policies). - +The filesystem and Landlock sections preserve the fallback policy's static +settings because `policy set` replaces the complete user-authored base policy. +Process identity remains omitted so the compute driver can select it. ## Apply the Policy -After you have reviewed the generated policy, apply it to the running sandbox: +Apply the policy and wait for the new revision to load: ```shell -openshell policy set --policy /tmp/sandbox-policy-update.yaml --wait +openshell policy set github-demo --policy github-push.yaml --wait ``` -Network policies are hot-reloadable. The `--wait` flag blocks until the policy engine confirms the new revision loaded, and the update takes effect immediately without restarting the sandbox or reconnecting Claude Code. +Network policy changes hot-reload without recreating the sandbox. Provider +rules are composed with this user-authored base policy. -## Retry the Push +## Retry and Verify -In terminal 1, ask Claude Code to retry the push: +Ask the agent to retry the push. Then confirm that the proxy allowed the scoped +request: -```md title="Prompt" wordWrap showLineNumbers={false} -The sandbox policy has been updated. Try pushing to the repository again. +```shell +openshell logs github-demo --since 5m +openshell policy get github-demo --full ``` -The push completes successfully. The `openshell term` dashboard now shows `l7_decision=allow` entries for `api.github.com` and `github.com` where it previously showed denials. +The push succeeds for the selected repository. Requests to push to another +repository remain denied. ## Clean Up -When you are finished, delete the sandbox to free gateway compute resources: +Delete the sandbox when you are finished: ```shell -openshell sandbox delete +openshell sandbox delete github-demo ``` ## Next Steps -The following resources cover related topics in greater depth: - -- To add per-repository access levels (read-write vs read-only) or restrict to specific API methods, refer to the [Policy Schema Reference](/reference/policy-schema). -- To learn the full policy iteration workflow (pull, edit, push, verify), refer to [Policies](/sandboxes/policies). -- To inject credentials automatically instead of pasting tokens, refer to [Manage Providers](/sandboxes/manage-providers) +- Review [Profiles](/providers/profiles) for endpoint-scoped credential placement. +- Review [Policies](/sandboxes/policies) for incremental policy updates and policy history. +- Review the [Policy Schema](/reference/policy-schema) for REST, GraphQL, and other protocol rules. diff --git a/docs/get-started/tutorials/index.mdx b/docs/get-started/tutorials/index.mdx index cda35bfffd..8d13198d99 100644 --- a/docs/get-started/tutorials/index.mdx +++ b/docs/get-started/tutorials/index.mdx @@ -27,19 +27,4 @@ Launch Claude Code in a sandbox, diagnose a policy denial, and iterate on a cust Configure a Microsoft Graph provider profile with gateway-managed OAuth2 refresh-token rotation. - - -Attach a profile that authorizes a sandbox to use a host-level Ollama service. - - - - -Attach an endpoint-bearing profile and call a local LM Studio server directly. - - - - -Run the OpenShell gateway as a Docker Compose service and create agent sandboxes including OpenClaw. - - diff --git a/docs/get-started/tutorials/inference-ollama.mdx b/docs/get-started/tutorials/inference-ollama.mdx deleted file mode 100644 index 017e8ec889..0000000000 --- a/docs/get-started/tutorials/inference-ollama.mdx +++ /dev/null @@ -1,99 +0,0 @@ ---- -# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -# SPDX-License-Identifier: Apache-2.0 -title: "Run Local Inference with Ollama" -sidebar-title: "Inference with Ollama" -slug: "get-started/tutorials/inference-ollama" -description: "Authorize an OpenShell sandbox to use an Ollama service running on the gateway host." -keywords: "Generative AI, Cybersecurity, Tutorial, Ollama, Local Inference, Sandbox, Provider Profile" ---- - -This tutorial connects an explicitly authorized sandbox to an Ollama service running on the same machine as the OpenShell gateway. - -## Prerequisites - -Complete the [Quickstart](/get-started/quickstart) before proceeding. Your workload image must contain the client or agent you plan to use. - -## Start Ollama on a Reachable Address - -Install Ollama on the gateway host and listen on an address reachable from sandboxes: - -```shell -curl -fsSL https://ollama.com/install.sh | sh -OLLAMA_HOST=0.0.0.0:11434 ollama serve -``` - -In another terminal, pull a model: - -```shell -ollama pull qwen3.5:0.8b -``` - -## Import an Endpoint-bearing Profile - -Save this as `ollama-openai.yaml`: - -```yaml -id: ollama-openai -display_name: Ollama -description: Host-level Ollama OpenAI-compatible API -category: inference -inference_capable: true -credentials: [] -endpoints: - - host: host.openshell.internal - port: 11434 - protocol: rest - access: read-write - enforcement: enforce -binaries: - - /usr/bin/curl - - /usr/local/bin/curl - - /usr/bin/python3 - - /usr/local/bin/python - - /sandbox/.uv/python/** - - /sandbox/.venv/** -``` - -```shell -openshell provider profile lint -f ollama-openai.yaml -openshell provider profile import -f ollama-openai.yaml -openshell provider create --name ollama --type ollama-openai -``` - -The provider has no secret because this Ollama server does not authenticate. Its attachment still carries the endpoint and binary policy. - -## Attach and Verify - -Use an explicit workload image containing `curl`: - -```shell -openshell sandbox create \ - --name ollama-client \ - --from registry.example.com/tools/curl:latest \ - --provider ollama \ - -- \ - curl http://host.openshell.internal:11434/v1/chat/completions \ - --json '{ - "model":"qwen3.5:0.8b", - "messages":[{"role":"user","content":"hello"}], - "max_tokens":10 - }' -``` - -For an OpenAI SDK client, set its base URL to `http://host.openshell.internal:11434/v1`, use any non-empty API key value the SDK accepts, and select the real Ollama model in the request. - -## Troubleshooting - -- Bind host-level Ollama to `0.0.0.0`, not `127.0.0.1`. -- Use `host.openshell.internal`, not `localhost`, from a sandbox. -- Confirm attachment with `openshell sandbox provider list ollama-client`. -- Inspect the effective policy with `openshell policy get ollama-client --full`. -- Run `ollama ps` and `ollama pull ` when the model is unavailable. -- If the gateway is remote, the hostname refers to the remote gateway host, not your laptop. Use a shared service address or tunnel instead. - -## Next Steps - -- [Provider-backed Inference](/sandboxes/inference-routing) -- [Profiles](/providers/profiles) -- [Customize Sandbox Policies](/sandboxes/policies) diff --git a/docs/get-started/tutorials/local-inference-lmstudio.mdx b/docs/get-started/tutorials/local-inference-lmstudio.mdx deleted file mode 100644 index 4f7ffc7aed..0000000000 --- a/docs/get-started/tutorials/local-inference-lmstudio.mdx +++ /dev/null @@ -1,139 +0,0 @@ ---- -# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -# SPDX-License-Identifier: Apache-2.0 -title: "Use Local Inference with LM Studio" -sidebar-title: "Local Inference with LM Studio" -slug: "get-started/tutorials/local-inference-lmstudio" -description: "Attach a provider profile for a local LM Studio server and call its native compatible endpoints." -keywords: "Generative AI, Cybersecurity, Tutorial, LM Studio, Local Inference, Sandbox, Provider Profile" ---- - -This tutorial exposes an LM Studio server on the gateway host to selected -sandboxes. The provider attachment grants access; the workload calls LM -Studio's OpenAI- or Anthropic-compatible endpoint directly. - -## Prerequisites - -- Complete the [Quickstart](/get-started/quickstart). -- Install [LM Studio](https://lmstudio.ai/download) on the gateway host. - -For a headless installation: - - - - -```shell -curl -fsSL https://lmstudio.ai/install.sh | bash -``` - - - - -```shell -irm https://lmstudio.ai/install.ps1 | iex -``` - - - - -Start the daemon and server: - -```shell -lms daemon up -lms server start --bind 0.0.0.0 -``` - -Load a model: - -```shell -lms get qwen/qwen3.5-2b -lms load qwen/qwen3.5-2b -``` - -## Create the Provider Profile - -Save this as `lmstudio.yaml`: - -```yaml -id: lmstudio -display_name: LM Studio -description: Host-level LM Studio compatible APIs -category: inference -inference_capable: true -credentials: [] -endpoints: - - host: host.openshell.internal - port: 1234 - protocol: rest - access: read-write - enforcement: enforce -binaries: - - /usr/bin/curl - - /usr/local/bin/curl - - /usr/bin/python3 - - /usr/local/bin/python - - /sandbox/.uv/python/** - - /sandbox/.venv/** -``` - -```shell -openshell provider profile lint -f lmstudio.yaml -openshell provider profile import -f lmstudio.yaml -openshell provider create --name lmstudio --type lmstudio -``` - -The profile intentionally has no credential. LM Studio does not require one by -default, but the provider attachment still supplies its policy boundary. - -## Attach and Call the Native Endpoint - -OpenAI-compatible request: - -```shell -openshell sandbox create \ - --name lmstudio-client \ - --provider lmstudio \ - -- \ - curl http://host.openshell.internal:1234/v1/chat/completions \ - --json '{ - "model":"qwen/qwen3.5-2b", - "messages":[{"role":"user","content":"hello"}], - "max_tokens":10 - }' -``` - -Anthropic-compatible request: - -```shell -openshell sandbox exec lmstudio-client -- \ - curl http://host.openshell.internal:1234/v1/messages \ - --json '{ - "model":"qwen/qwen3.5-2b", - "messages":[{"role":"user","content":"hello"}], - "max_tokens":10 - }' -``` - -Configure SDKs with the same native base URL. Some SDKs require a non-empty -API key even when LM Studio ignores it; use a literal non-secret value such as -`unused`. Keep the actual model ID in the client request. - -## Troubleshooting - -- Enable **Serve on Local Network** in the LM Studio Developer tab, or use - `lms server start --bind 0.0.0.0`. -- Use `host.openshell.internal`, not `127.0.0.1` or `localhost`, in the - sandbox. -- Confirm the model is loaded with `lms ps`. -- Confirm the attachment with - `openshell sandbox provider list lmstudio-client`. -- Inspect endpoint and binary policy with - `openshell policy get lmstudio-client --full`. -- A remote gateway cannot reach an LM Studio process on your laptop without a - tunnel or shared network path. - -## Next Steps - -- [Provider-backed Inference](/sandboxes/inference-routing) -- [Profiles](/providers/profiles) -- [LM Studio CLI](https://lmstudio.ai/docs/cli) diff --git a/docs/get-started/tutorials/microsoft-graph-provider-refresh.mdx b/docs/get-started/tutorials/microsoft-graph-provider-refresh.mdx index 4204e7ebfb..301678d91f 100644 --- a/docs/get-started/tutorials/microsoft-graph-provider-refresh.mdx +++ b/docs/get-started/tutorials/microsoft-graph-provider-refresh.mdx @@ -22,7 +22,7 @@ This tutorial starts after your OAuth client has already completed the initial M ## Prerequisites -- A working OpenShell installation with an active gateway. Complete the [Quickstart](/get-started/quickstart) before proceeding. +- A working OpenShell installation with an active gateway. Refer to [Installation](/about/installation) before proceeding. - A Microsoft Entra app registration that can acquire delegated Microsoft Graph mail access. - Delegated Microsoft Graph mail permission for the signed-in user. `Mail.Read` allows reading the signed-in user's mailbox; see the [Microsoft Graph permissions reference](https://learn.microsoft.com/en-us/graph/permissions-reference). OAuth material from your initial Microsoft sign-in flow: @@ -152,6 +152,7 @@ Launch a sandbox with the Microsoft Graph provider attached: ```shell openshell sandbox create \ --name microsoft-graph-mail \ + --from registry.example.com/team/agent-tools:1.0 \ --provider microsoft-mail \ --no-auto-providers \ -- /bin/sh diff --git a/docs/index.mdx b/docs/index.mdx index 9a40bca095..a48bff2bca 100644 --- a/docs/index.mdx +++ b/docs/index.mdx @@ -49,12 +49,13 @@ Install OpenShell and create your first sandbox in two commands. ```shell curl -LsSf https://raw.githubusercontent.com/NVIDIA/OpenShell/main/install.sh | sh -openshell sandbox create --name quickstart +openshell sandbox create ``` -Refer to the [Quickstart](/get-started/quickstart) for more details. +Refer to [Run Your First Agent](/about/run-an-agent) for the complete image, +provider, and policy workflow. --- @@ -70,9 +71,9 @@ Learn about OpenShell and its capabilities. Concept - + -Install OpenShell and create your first sandbox in two commands. +Prepare an image, attach providers, and launch an agent in a sandbox. Tutorial @@ -91,7 +92,7 @@ Deploy gateways, create sandboxes, configure policies, providers, and workload i Concept - + Attach model providers to selected sandboxes and call their native endpoints without exposing credentials. @@ -105,9 +106,9 @@ Understand sandbox logs, access them with the CLI and TUI, and export OCSF JSON How-To - + -Policy schema, environment variables, and default policy details. +Define filesystem, process, and network controls for sandbox workloads. Reference diff --git a/docs/index.yml b/docs/index.yml index 45db451a78..30241862fb 100644 --- a/docs/index.yml +++ b/docs/index.yml @@ -6,28 +6,115 @@ landing-page: path: index.mdx navigation: -- folder: about - title: "About NVIDIA OpenShell" -- section: "Get Started" - slug: get-started +- section: "About NVIDIA OpenShell" + slug: about contents: - - page: "Quickstart" - path: get-started/quickstart.mdx - - folder: get-started/tutorials - skip-slug: true -- folder: sandboxes - title: "Manage OpenShell" -- folder: providers - title: "Providers" -- folder: extensibility - title: "Extensibility" + - page: "Why OpenShell" + path: about/overview.mdx + - page: "Architecture" + path: about/how-it-works.mdx + - page: "Installation" + path: about/installation.mdx + - page: "Run Your First Agent" + path: about/run-an-agent.mdx + - page: "Support Matrix" + path: reference/support-matrix.mdx +- section: "How It Works" + slug: manage + contents: + - section: "Gateways" + slug: gateways + contents: + - page: "Overview" + path: sandboxes/manage-gateways.mdx + - page: "Authentication" + path: reference/gateway-auth.mdx + - page: "Configuration" + path: reference/gateway-config.mdx + - page: "Container Deployment" + path: reference/container-gateway.mdx + - page: "Workspaces" + path: sandboxes/manage-workspaces.mdx + - section: "Sandboxes" + slug: sandboxes + contents: + - page: "Overview" + path: sandboxes/manage-sandboxes.mdx + - page: "Runtimes" + path: reference/sandbox-compute-drivers.mdx + - section: "Providers" + slug: providers + contents: + - page: "Overview" + path: sandboxes/manage-providers.mdx + - page: "Profiles" + path: providers/profiles.mdx + - page: "AWS" + path: providers/aws-sigv4.mdx + - page: "Google" + path: providers/google-cloud.mdx + - section: "Policies" + slug: policies + contents: + - page: "Overview" + path: sandboxes/policies.mdx + - page: "Advisor" + path: sandboxes/policy-advisor.mdx + - page: "Schema" + path: reference/policy-schema.mdx + - page: "Prover" + path: reference/policy-prover.mdx + - page: "Default Policy" + path: reference/default-policy.mdx + - page: "Inference" + path: sandboxes/inference-routing.mdx +- section: "Extensibility" + slug: extensibility + contents: + - page: "Overview" + path: extensibility/extension-negotiation.mdx + - page: "Middleware" + path: extensibility/supervisor-middleware.mdx + - page: "Interceptors" + path: extensibility/gateway-interceptors.mdx + - page: "Drivers" + path: extensibility/drivers.mdx + - page: "Isolation Backends" + path: extensibility/isolation-backends.mdx - folder: observability title: "Observability" - folder: kubernetes title: "Kubernetes" -- folder: reference - title: "Reference" +- section: "Tutorials" + slug: tutorials + contents: + - page: "First Network Policy" + path: get-started/tutorials/first-network-policy.mdx + - page: "GitHub Push Access" + path: get-started/tutorials/github-sandbox.mdx + - page: "Microsoft Graph Provider Refresh" + path: get-started/tutorials/microsoft-graph-provider-refresh.mdx +- section: "SDK Reference" + slug: sdk + contents: + - page: "Go" + path: sdk/go.mdx + - page: "Rust" + path: sdk/rust.mdx + - page: "Python" + path: sdk/python.mdx + - page: "TypeScript" + path: sdk/typescript.mdx + - page: "API Errors" + path: reference/api-errors.mdx + - page: "Protobuf Time Types" + path: reference/protobuf-time-types.mdx - folder: security title: "Security" +- section: "Upgrade Guides" + slug: upgrade + contents: + - page: "0.1.0" + path: upgrade/0-1-0.mdx - folder: resources title: "Resources" diff --git a/docs/kubernetes/access-control.mdx b/docs/kubernetes/access-control.mdx index 1ff54a0e01..3d17597fbe 100644 --- a/docs/kubernetes/access-control.mdx +++ b/docs/kubernetes/access-control.mdx @@ -5,7 +5,7 @@ title: "Access Control" sidebar-title: "Access Control" description: "Configure OIDC user authentication or reverse-proxy auth termination for a Kubernetes-deployed OpenShell gateway." keywords: "Generative AI, Cybersecurity, Kubernetes, Authentication, mTLS, OIDC, Keycloak, Entra ID, Okta, Gateway Auth" -position: 5 +position: 6 --- The OpenShell gateway supports two access-control models for human callers on Kubernetes: diff --git a/docs/kubernetes/high-availability.mdx b/docs/kubernetes/high-availability.mdx new file mode 100644 index 0000000000..c45ce9a1f6 --- /dev/null +++ b/docs/kubernetes/high-availability.mdx @@ -0,0 +1,215 @@ +--- +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 +title: "High Availability" +sidebar-title: "High Availability" +description: "Run multiple OpenShell gateway replicas on Kubernetes with shared PostgreSQL and authenticated peer routing." +keywords: "Generative AI, Cybersecurity, Kubernetes, High Availability, HA, Gateway, PostgreSQL, Replicas, Failover" +position: 3 +--- + +Run two or more gateway replicas when the OpenShell control plane must remain +available during a gateway pod failure or rolling update. Every replica can +serve API requests. The replicas share persistent state through PostgreSQL and +relay session-bound requests to the replica connected to each sandbox +supervisor. + + +Gateway replicas do not make PostgreSQL highly available. Use a managed +PostgreSQL service or a separately operated PostgreSQL cluster with its own +backup and failover plan. + + +## Requirements + +An HA gateway deployment requires: + +- Two or more schedulable Kubernetes nodes or failure domains. +- PostgreSQL reachable from every gateway pod. +- A Kubernetes Secret in the OpenShell namespace with the PostgreSQL connection + URI in a key named `uri`. +- `workload.kind: deployment`. The default StatefulSet and per-pod SQLite + database are intended for a single gateway replica. +- An ingress or load balancer that routes clients to the gateway Service. Refer + to [Ingress](/kubernetes/ingress) for a Gateway API configuration. + +The Helm chart rejects `replicaCount` values above `1` unless +`server.externalDbSecret` is set. It also rejects a multi-replica StatefulSet +unless `workload.allowMultiReplicaStatefulSet` is explicitly enabled. Use a +Deployment for the standard HA configuration. + +## Create the PostgreSQL Secret + +Provision PostgreSQL outside the OpenShell chart, then create the connection +Secret. The chart does not install PostgreSQL. + +```shell +kubectl create namespace openshell + +kubectl -n openshell create secret generic openshell-postgres \ + --from-literal=uri='postgresql://openshell:@:5432/openshell' +``` + +Use your PostgreSQL provider's required TLS parameters in the connection URI. +Keep the Secret in the same namespace as the gateway release. + +## Configure Gateway Replicas + +Create `values-ha.yaml`: + +```yaml +replicaCount: 2 + +workload: + kind: deployment + +server: + externalDbSecret: openshell-postgres + +affinity: + podAntiAffinity: + requiredDuringSchedulingIgnoredDuringExecution: + - labelSelector: + matchLabels: + app.kubernetes.io/name: openshell + app.kubernetes.io/instance: openshell + topologyKey: kubernetes.io/hostname +``` + +The anti-affinity rule places the two replicas on different nodes. The +`app.kubernetes.io/instance` value must match the Helm release name. Change the +topology key to a zone label when replicas must span availability zones. A +required rule leaves a replica Pending when the cluster does not have enough +matching failure domains; use preferred anti-affinity when scheduling the +replica is more important than strict separation. + +Install or upgrade OpenShell: + +```shell +helm upgrade --install openshell \ + oci://ghcr.io/nvidia/openshell/helm-chart \ + --version \ + --namespace openshell \ + --set supervisor.sandboxRuntime.networkPolicyEnforced=true \ + --values values-ha.yaml \ + --wait +``` + +The chart shares its retained sandbox JWT signing material, TLS material, and +default credential-storage encryption key across the gateway pods. Do not +create different copies of those Secrets for individual replicas. + +## Verify the Deployment + +Wait for all gateway replicas to become ready: + +```shell +kubectl -n openshell rollout status deployment/openshell +kubectl -n openshell get pods \ + -l app.kubernetes.io/name=openshell,app.kubernetes.io/instance=openshell \ + -o wide +``` + +Confirm that the client-facing Service and headless peer Service have ready +endpoints: + +```shell +kubectl -n openshell get service openshell openshell-peer +kubectl -n openshell get endpointslice \ + -l app.kubernetes.io/service-name=openshell +kubectl -n openshell get endpointslice \ + -l app.kubernetes.io/service-name=openshell-peer +``` + +If you changed the chart's generated names with `nameOverride` or +`fullnameOverride`, use the rendered Service names instead. + +After registering the gateway with the CLI, verify that requests succeed: + +```shell +openshell status +openshell sandbox list +``` + +## Protect Voluntary Disruptions + +Add a PodDisruptionBudget so a voluntary disruption, such as node maintenance, +does not evict every ready gateway pod at once: + +```yaml +apiVersion: policy/v1 +kind: PodDisruptionBudget +metadata: + name: openshell + namespace: openshell +spec: + minAvailable: 1 + selector: + matchLabels: + app.kubernetes.io/name: openshell + app.kubernetes.io/instance: openshell +``` + +Apply the manifest separately from the OpenShell chart. Match the namespace and +release labels to your installation. A PodDisruptionBudget controls voluntary +evictions; it does not protect against an unavailable node or failure domain. + +## How Peer Routing Works + +A sandbox supervisor keeps one active control stream to one gateway replica. +That replica records ownership in PostgreSQL. When Kubernetes sends a client +request to another replica, the receiving gateway relays exec, forwarding, +file-sync, service, and status traffic to the owner through the headless peer +Service. + +Peer RPCs use a projected, pod-bound ServiceAccount token with the +`openshell-gateway-peer` audience. The receiving gateway validates the token +with the Kubernetes TokenReview API, verifies the live pod identity and release +labels, and authorizes only peer methods. When gateway TLS is enabled, peer +connections also use the chart's TLS materials. + +You do not need session affinity at the ingress or client-facing Service. + +## Failure and Rollout Behavior + +When a non-owner gateway pod stops, Kubernetes removes it from ready Service +endpoints and new requests go to another replica. Existing requests through the +stopped pod disconnect and must be retried. + +When an owner gateway pod stops, its connected supervisors reconnect through +the gateway Service and publish new ownership. Other replicas re-read ownership +while waiting to relay a request. A request fails if no fresh, reachable owner +appears before its normal deadline. + +Established streams do not move between gateway replicas. An interrupted exec, +forwarding, or service stream must reconnect. File sync retries with a new SSH +session instead of resuming the interrupted byte stream. Rolling updates can +temporarily concentrate supervisor sessions on the replicas that stayed up; +client requests remain routable through peer relay. + +## Scale the Gateway + +Change `replicaCount` in `values-ha.yaml`, then apply the release again: + +```shell +helm upgrade openshell \ + oci://ghcr.io/nvidia/openshell/helm-chart \ + --version \ + --namespace openshell \ + --set supervisor.sandboxRuntime.networkPolicyEnforced=true \ + --values values-ha.yaml \ + --wait +``` + +Keep at least two ready replicas when availability must survive one gateway pod +failure. Size PostgreSQL connection capacity and the cluster nodes for the +selected replica count. + +## Next Steps + +- To expose the gateway through a highly available data path, refer to + [Ingress](/kubernetes/ingress). +- To configure automatic certificate renewal, refer to + [Managing Certificates](/kubernetes/managing-certificates). +- To configure user authentication and authorization, refer to + [Access Control](/kubernetes/access-control). diff --git a/docs/kubernetes/ingress.mdx b/docs/kubernetes/ingress.mdx index 5af0589f20..fd6be78fbd 100644 --- a/docs/kubernetes/ingress.mdx +++ b/docs/kubernetes/ingress.mdx @@ -5,7 +5,7 @@ title: "Ingress" sidebar-title: "Ingress" description: "Expose the OpenShell gateway externally using the Kubernetes Gateway API and a GRPCRoute." keywords: "Generative AI, Cybersecurity, Kubernetes, Gateway API, Envoy Gateway, GRPCRoute, Ingress, External Access" -position: 4 +position: 5 --- By default, the OpenShell gateway is only reachable inside the cluster. To let CLI clients connect without a `kubectl port-forward`, expose the gateway through an ingress. diff --git a/docs/kubernetes/managing-certificates.mdx b/docs/kubernetes/managing-certificates.mdx index efef147f0a..13815e5cf9 100644 --- a/docs/kubernetes/managing-certificates.mdx +++ b/docs/kubernetes/managing-certificates.mdx @@ -5,7 +5,7 @@ title: "Managing Certificates" sidebar-title: "Managing Certificates" description: "Configure the OpenShell Helm chart to use cert-manager for mTLS certificate issuance and automatic renewal." keywords: "Generative AI, Cybersecurity, Kubernetes, cert-manager, PKI, TLS, mTLS, Certificates" -position: 3 +position: 4 --- The OpenShell gateway uses mTLS certificates for transport between the gateway and sandbox supervisors. These certificates are not Kubernetes user authentication; configure OIDC or a trusted access proxy for user access. The Helm chart supports two ways to provision and manage the certificate bundle: diff --git a/docs/kubernetes/openshift.mdx b/docs/kubernetes/openshift.mdx index 39b0a4bf14..e510fc44c4 100644 --- a/docs/kubernetes/openshift.mdx +++ b/docs/kubernetes/openshift.mdx @@ -5,7 +5,7 @@ title: "OpenShift" sidebar-title: "OpenShift" description: "Install the OpenShell Helm chart on OpenShift with capability-free sandbox workloads." keywords: "Generative AI, Cybersecurity, Kubernetes, OpenShift, SCC, Security Context Constraints, Helm, Gateway, Installation" -position: 6 +position: 7 --- The Kubernetes driver resolves the UID range assigned to each OpenShift diff --git a/docs/kubernetes/setup.mdx b/docs/kubernetes/setup.mdx index 494e14aa22..0f2e5694f3 100644 --- a/docs/kubernetes/setup.mdx +++ b/docs/kubernetes/setup.mdx @@ -217,21 +217,9 @@ The most commonly changed values are: ### Run multiple gateway replicas -Use a Deployment and shared PostgreSQL for high availability: - -```yaml -replicaCount: 2 -workload: - kind: deployment -server: - externalDbSecret: openshell-postgres -``` - -The chart creates the peer Service, projected ServiceAccount identity, and RBAC -that gateway replicas use to route exec, forwarding, file-sync, and service -traffic to the replica holding the external supervisor's live session. Peer -traffic uses the chart TLS materials when gateway TLS is enabled. Do not use -the per-pod SQLite database with more than one replica. +Use a Deployment and shared PostgreSQL to run more than one gateway replica. +Refer to [High Availability](/kubernetes/high-availability) for the database +Secret, Helm values, pod placement, verification, and failover behavior. Use a values file for repeatable deployments: @@ -340,6 +328,7 @@ The gateway exposes `/healthz` for process liveness and `/readyz` for dependency ## Next Steps - Kubernetes sandboxes use separate workload and directly managed supervisor Pods; refer to [Sandbox runtime](/kubernetes/sandbox-runtime). +- To run multiple gateway replicas, refer to [High Availability](/kubernetes/high-availability). - To enable automatic certificate rotation with cert-manager, refer to [Managing Certificates](/kubernetes/managing-certificates). - To expose the gateway externally without port-forwarding, refer to [Ingress](/kubernetes/ingress). - To configure OIDC or reverse-proxy authentication, refer to [Access Control](/kubernetes/access-control). diff --git a/docs/providers/aws-sigv4.mdx b/docs/providers/aws-sigv4.mdx index 101d796e5c..a9251f134d 100644 --- a/docs/providers/aws-sigv4.mdx +++ b/docs/providers/aws-sigv4.mdx @@ -2,7 +2,7 @@ # SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. # SPDX-License-Identifier: Apache-2.0 title: "AWS SigV4 Credential Signing" -sidebar-title: "AWS SigV4" +sidebar-title: "AWS" description: "Configure proxy-side AWS SigV4 request signing so sandbox agents can reach AWS services through CONNECT tunnels without holding real credentials." keywords: "Generative AI, Cybersecurity, AI Agents, AWS, SigV4, Bedrock, S3, Credential Signing, Sandbox" --- diff --git a/docs/providers/google-cloud.mdx b/docs/providers/google-cloud.mdx index 9168be25e3..dee210b77b 100644 --- a/docs/providers/google-cloud.mdx +++ b/docs/providers/google-cloud.mdx @@ -1,9 +1,9 @@ --- # SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. # SPDX-License-Identifier: Apache-2.0 -title: "Google Cloud" -sidebar-title: "Google Cloud" -description: "Authenticate with GCP APIs inside OpenShell sandboxes." +title: "Google" +sidebar-title: "Google" +description: "Authenticate with Google Cloud APIs and Vertex AI inside OpenShell sandboxes." keywords: "Generative AI, Google Cloud, Vertex AI, GCP, OAuth2, Credentials, Sandbox" --- @@ -200,3 +200,178 @@ The `google-cloud` provider type does not include any network policy endpoints by default. You must add endpoint rules to your sandbox policy for each GCP API the sandbox needs to reach. See "Using with GCP APIs" above for an example. + +## Vertex AI + +The `google-vertex-ai` provider gives selected sandboxes access to native +Google Vertex AI endpoints. OpenShell keeps refresh bootstrap material at the +gateway, rotates short-lived access tokens, and resolves token placeholders +only at endpoints authorized by the provider profile. + +OpenShell does not choose a model or transform a request. The workload uses the +native Vertex endpoint and request format for its selected model. + +### Prerequisites + +- A GCP project with the Vertex AI API enabled. +- A service account with the Vertex AI User role and a downloaded JSON key for + production, or gcloud Application Default Credentials for local development. +- Access to the selected model in the intended Vertex region. + +### Create a Vertex AI Provider + +Import the `google-vertex-ai` profile first: + +```shell +curl -LsSfO https://raw.githubusercontent.com/NVIDIA/OpenShell/main/providers/google-vertex-ai.yaml +openshell provider profile import -f google-vertex-ai.yaml --global +``` + +#### Service Account Key + +Create the provider with the JSON key as gateway-only bootstrap material: + +```shell +openshell provider create \ + --name vertex-prod \ + --type google-vertex-ai \ + --credential GOOGLE_SERVICE_ACCOUNT_KEY="$(cat /path/to/key.json)" \ + --config VERTEX_AI_PROJECT_ID=my-gcp-project \ + --config VERTEX_AI_REGION=us-central1 +``` + +Configure gateway-managed refresh: + +```shell +openshell provider refresh configure vertex-prod \ + --credential-key GOOGLE_VERTEX_AI_SERVICE_ACCOUNT_TOKEN \ + --strategy google-service-account-jwt \ + --material client_email="sa@my-gcp-project.iam.gserviceaccount.com" \ + --material private_key="$(jq -r .private_key /path/to/key.json)" \ + --secret-material-key private_key +``` + +The private key remains in the gateway credential store. Sandboxes receive +only an opaque placeholder for the short-lived access token. + +#### gcloud Application Default Credentials + +For local development: + +```shell +gcloud auth application-default login + +openshell provider create \ + --name vertex-local \ + --type google-vertex-ai \ + --from-gcloud-adc \ + --config VERTEX_AI_PROJECT_ID=my-gcp-project \ + --config VERTEX_AI_REGION=us-central1 +``` + +`--from-gcloud-adc` reads authorized-user ADC, configures an OAuth2 refresh +grant at the gateway, and immediately mints `GOOGLE_VERTEX_AI_TOKEN`. The ADC +file and refresh token do not enter the sandbox. + +### Vertex AI Configuration Keys + +| Key | Required | Default | Description | +|---|---|---|---| +| `VERTEX_AI_PROJECT_ID` | Yes | — | GCP project ID exposed as non-secret workload configuration. | +| `VERTEX_AI_REGION` | No | `us-central1` | Vertex location exposed as non-secret workload configuration. | + +When the provider is attached, OpenShell also projects standard project and +location aliases such as `GOOGLE_CLOUD_PROJECT`, `ANTHROPIC_VERTEX_PROJECT_ID`, +`CLOUD_ML_REGION`, and `VERTEX_LOCATION`. + +### Attach the Vertex AI Provider + +Attach it while creating a sandbox: + +```shell +openshell sandbox create \ + --from registry.example.com/team/agent:1.0 \ + --name vertex-agent \ + --provider vertex-local +``` + +Or attach it to an existing sandbox: + +```shell +openshell sandbox provider attach vertex-agent vertex-local +``` + +Launch a new process after runtime attachment so it receives the provider +environment. Existing processes do not gain newly attached environment +variables. + +### Call the Native Vertex API + +Claude models use Vertex's publisher-model endpoint. Run a request from a new +sandbox process: + +```shell +openshell sandbox exec vertex-agent -- sh -lc ' + token=${GOOGLE_VERTEX_AI_SERVICE_ACCOUNT_TOKEN:-$GOOGLE_VERTEX_AI_TOKEN} + curl -X POST \ + -H "Authorization: Bearer $token" \ + -H "Content-Type: application/json" \ + -d '\''{ + "anthropic_version":"vertex-2023-10-16", + "max_tokens":1024, + "messages":[{"role":"user","content":"Hello"}] + }'\'' \ + "https://${CLOUD_ML_REGION}-aiplatform.googleapis.com/v1/projects/${GOOGLE_CLOUD_PROJECT}/locations/${CLOUD_ML_REGION}/publishers/anthropic/models/claude-sonnet-4-6:rawPredict" +' +``` + +Use the model ID and location supported by your GCP project. For `global`, `us`, +or `eu`, use the corresponding Google-documented hostname instead of the +regional `-aiplatform.googleapis.com` form. + +Gemini and third-party models use their documented native or +OpenAI-compatible Vertex endpoints. Configure the model, URL, streaming mode, +and timeout in the client. OpenShell does not rewrite them. + +### Verify and Troubleshoot Vertex AI + +Inspect the attachment and effective policy: + +```shell +openshell sandbox provider list vertex-agent +openshell policy get vertex-agent --full +openshell provider refresh status vertex-local +``` + +Common failures: + +- A missing token variable usually means the process started before provider + attachment. Launch a new process. +- `connection not allowed by policy` means the provider endpoint or caller + binary is absent from the effective policy. A gateway global policy override + suppresses provider-derived entries. +- `credential_endpoint_mismatch` means the request destination is outside the + provider profile's endpoint binding. +- A Vertex 400 or 404 usually means the model, location, publisher path, or + request body does not match the native API. +- A Vertex 401 or 403 can indicate an expired refresh grant or missing GCP IAM + permission. Check `provider refresh status` and the Vertex AI User role. + +Provider creation does not verify model access. The native request is the +end-to-end check. + +### Migrate an Existing Vertex Route + +An earlier managed route stored the provider and model separately and rewrote +requests for the workload. After upgrading, the provider and its refresh state +remain, but the route does not. + +1. Attach the preserved Vertex provider to each intended sandbox. +2. Launch new workload processes. +3. Move the route's model and timeout into the client configuration. +4. Change the client to the native Vertex endpoint and request format. +5. Verify one non-streaming and one streaming native request before production + rollout. + +Do not attach the provider to every sandbox automatically. The old route was +workspace-global; the replacement intentionally grants access per sandbox. diff --git a/docs/providers/google-vertex-ai.mdx b/docs/providers/google-vertex-ai.mdx deleted file mode 100644 index 0832baee90..0000000000 --- a/docs/providers/google-vertex-ai.mdx +++ /dev/null @@ -1,188 +0,0 @@ ---- -# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -# SPDX-License-Identifier: Apache-2.0 -title: "Google Vertex AI" -sidebar-title: "Google Vertex AI" -description: "Attach a Google Vertex AI provider and call native Vertex endpoints with gateway-refreshed credentials." -keywords: "Generative AI, Cybersecurity, AI Agents, Sandboxing, Google Vertex AI, Anthropic Claude" ---- - -The `google-vertex-ai` provider gives selected sandboxes access to native -Google Vertex AI endpoints. OpenShell keeps refresh bootstrap material at the -gateway, rotates short-lived access tokens, and resolves token placeholders -only at endpoints authorized by the provider profile. - -OpenShell does not choose a model or transform a request. The workload uses the -native Vertex endpoint and request format for its selected model. - -## Prerequisites - -- A GCP project with the Vertex AI API enabled. -- A service account with the Vertex AI User role and a downloaded JSON key for - production, or gcloud Application Default Credentials for local development. -- Access to the selected model in the intended Vertex region. - -## Create a Provider - -Import the `google-vertex-ai` profile first; a gateway serves only the profiles you -imported: - -```shell -curl -LsSfO https://raw.githubusercontent.com/NVIDIA/OpenShell/main/providers/google-vertex-ai.yaml -openshell provider profile import -f google-vertex-ai.yaml --global -``` - -### Service Account Key - -Create the provider with the JSON key as gateway-only bootstrap material: - -```shell -openshell provider create \ - --name vertex-prod \ - --type google-vertex-ai \ - --credential GOOGLE_SERVICE_ACCOUNT_KEY="$(cat /path/to/key.json)" \ - --config VERTEX_AI_PROJECT_ID=my-gcp-project \ - --config VERTEX_AI_REGION=us-central1 -``` - -Configure gateway-managed refresh: - -```shell -openshell provider refresh configure vertex-prod \ - --credential-key GOOGLE_VERTEX_AI_SERVICE_ACCOUNT_TOKEN \ - --strategy google-service-account-jwt \ - --material client_email="sa@my-gcp-project.iam.gserviceaccount.com" \ - --material private_key="$(jq -r .private_key /path/to/key.json)" \ - --secret-material-key private_key -``` - -The private key remains in the gateway credential store. Sandboxes receive -only an opaque placeholder for the short-lived access token. - -### gcloud Application Default Credentials - -For local development: - -```shell -gcloud auth application-default login - -openshell provider create \ - --name vertex-local \ - --type google-vertex-ai \ - --from-gcloud-adc \ - --config VERTEX_AI_PROJECT_ID=my-gcp-project \ - --config VERTEX_AI_REGION=us-central1 -``` - -`--from-gcloud-adc` reads authorized-user ADC, configures an OAuth2 refresh -grant at the gateway, and immediately mints `GOOGLE_VERTEX_AI_TOKEN`. The ADC -file and refresh token do not enter the sandbox. - -## Configuration Keys - -| Key | Required | Default | Description | -|---|---|---|---| -| `VERTEX_AI_PROJECT_ID` | Yes | — | GCP project ID exposed as non-secret workload configuration. | -| `VERTEX_AI_REGION` | No | `us-central1` | Vertex location exposed as non-secret workload configuration. | - -When the provider is attached, OpenShell also projects standard project and -location aliases such as `GOOGLE_CLOUD_PROJECT`, `ANTHROPIC_VERTEX_PROJECT_ID`, -`CLOUD_ML_REGION`, and `VERTEX_LOCATION`. - -## Attach the Provider - -Attach it while creating a sandbox: - -```shell -openshell sandbox create \ - --name vertex-agent \ - --provider vertex-local -``` - -Or attach it to an existing sandbox: - -```shell -openshell sandbox provider attach vertex-agent vertex-local -``` - -Launch a new process after runtime attachment so it receives the provider -environment. Existing processes do not gain newly attached environment -variables. - -## Call the Native Vertex API - -Claude models use Vertex's publisher-model endpoint. Run a request from a new -sandbox process: - -```shell -openshell sandbox exec vertex-agent -- sh -lc ' - token=${GOOGLE_VERTEX_AI_SERVICE_ACCOUNT_TOKEN:-$GOOGLE_VERTEX_AI_TOKEN} - curl -X POST \ - -H "Authorization: Bearer $token" \ - -H "Content-Type: application/json" \ - -d '\''{ - "anthropic_version":"vertex-2023-10-16", - "max_tokens":1024, - "messages":[{"role":"user","content":"Hello"}] - }'\'' \ - "https://${CLOUD_ML_REGION}-aiplatform.googleapis.com/v1/projects/${GOOGLE_CLOUD_PROJECT}/locations/${CLOUD_ML_REGION}/publishers/anthropic/models/claude-sonnet-4-6:rawPredict" -' -``` - -Use the model ID and location supported by your GCP project. For `global`, `us`, -or `eu`, use the corresponding Google-documented hostname instead of the -regional `-aiplatform.googleapis.com` form. - -Gemini and third-party models use their documented native or -OpenAI-compatible Vertex endpoints. Configure the model, URL, streaming mode, -and timeout in the client. OpenShell does not rewrite them. - -## Verify and Troubleshoot - -Inspect the attachment and effective policy: - -```shell -openshell sandbox provider list vertex-agent -openshell policy get vertex-agent --full -openshell provider refresh status vertex-local -``` - -Common failures: - -- A missing token variable usually means the process started before provider - attachment. Launch a new process. -- `connection not allowed by policy` means the provider endpoint or caller - binary is absent from the effective policy. A gateway global policy override - suppresses provider-derived entries. -- `credential_endpoint_mismatch` means the request destination is outside the - provider profile's endpoint binding. -- A Vertex 400 or 404 usually means the model, location, publisher path, or - request body does not match the native API. -- A Vertex 401 or 403 can indicate an expired refresh grant or missing GCP IAM - permission. Check `provider refresh status` and the Vertex AI User role. - -Provider creation does not verify model access. The native request is the -end-to-end check. - -## Migrate an Existing Vertex Route - -An earlier managed route stored the provider and model separately and rewrote -requests for the workload. After upgrading, the provider and its refresh state -remain, but the route does not. - -1. Attach the preserved Vertex provider to each intended sandbox. -2. Launch new workload processes. -3. Move the route's model and timeout into the client configuration. -4. Change the client to the native Vertex endpoint and request format. -5. Verify one non-streaming and one streaming native request before production - rollout. - -Do not attach the provider to every sandbox automatically. The old route was -workspace-global; the replacement intentionally grants access per sandbox. - -## Next Steps - -- [Provider-backed Inference](/sandboxes/inference-routing) -- [Profiles](/providers/profiles) -- [Providers](/sandboxes/manage-providers) -- [Customize Sandbox Policies](/sandboxes/policies) diff --git a/docs/providers/profiles.mdx b/docs/providers/profiles.mdx index 66f498ee11..446715a5c6 100644 --- a/docs/providers/profiles.mdx +++ b/docs/providers/profiles.mdx @@ -209,7 +209,7 @@ The following provider profile design items are not part of the current behavior | Policy prover integration | OpenShell does not yet run the policy prover automatically on sandbox startup or block startup based on prover findings. | | Refresh telemetry as OCSF events | Credential refresh logs are secret-safe gateway logs. OCSF refresh events and metrics are future work. | -Use [Provider-backed Inference](/sandboxes/inference-routing) to attach an +Use [Inference](/sandboxes/inference-routing) to attach an inference provider and call its native endpoint. ## Provider Profiles diff --git a/docs/about/container-gateway.mdx b/docs/reference/container-gateway.mdx similarity index 97% rename from docs/about/container-gateway.mdx rename to docs/reference/container-gateway.mdx index 57be7d0142..fc52cf2b1a 100644 --- a/docs/about/container-gateway.mdx +++ b/docs/reference/container-gateway.mdx @@ -2,10 +2,10 @@ # SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. # SPDX-License-Identifier: Apache-2.0 title: "Running the Gateway as a Container" -sidebar-title: "Container Gateway" +sidebar-title: "Container Deployment" description: "Run the OpenShell gateway using docker run or docker-compose without the installer." keywords: "Generative AI, Cybersecurity, AI Agents, Sandboxing, Docker, Podman, docker-compose, container, immutable OS, bootc, rpm-ostree" -position: 4 +position: 8 --- Use this approach when you want to run the OpenShell gateway as a container instead of installing it with the system package manager. This is useful on immutable OS distributions (Fedora CoreOS, bootc-based images, Silverblue) where the standard installer is not appropriate, or anywhere you prefer a container-first workflow. @@ -197,6 +197,6 @@ podman run -d \ ## Next Steps -- To create your first sandbox, refer to the [Quickstart](/get-started/quickstart). +- To prepare an image and launch an agent, refer to [Run Your First Agent](/about/run-an-agent). - To control what the agent can access, refer to [Policies](/sandboxes/policies). -- For environment variable reference, refer to [Sandbox Compute Drivers](/reference/sandbox-compute-drivers). +- For environment variable reference, refer to [Sandbox Runtimes](/reference/sandbox-compute-drivers). diff --git a/docs/reference/gateway-auth.mdx b/docs/reference/gateway-auth.mdx index 5dc8298c67..644060dd2b 100644 --- a/docs/reference/gateway-auth.mdx +++ b/docs/reference/gateway-auth.mdx @@ -199,7 +199,7 @@ For a headless environment, set `OPENSHELL_NO_BROWSER=1` before registering or l 6. The gateway authorizes the gRPC method. Platform-scoped methods require the configured admin role. Workspace-scoped methods require the configured user role and a sufficient membership in the target workspace. Admin role holders satisfy user-role checks and bypass workspace membership checks. For the Platform Admin, Workspace Admin, and Workspace User permissions, refer -to [Manage Workspaces and Access](/sandboxes/manage-workspaces). +to [Workspaces](/sandboxes/manage-workspaces). #### JWT validation @@ -242,7 +242,7 @@ display name when available, identity provider, roles, and scopes. The gateway returns its validated identity; the CLI does not infer these values from an unverified local token payload. Use the `subject` value when adding the user to a workspace. For membership commands, refer to -[Manage Workspaces and Access](/sandboxes/manage-workspaces). +[Workspaces](/sandboxes/manage-workspaces). ### Edge JWT (cloud gateways) diff --git a/docs/reference/gateway-config.mdx b/docs/reference/gateway-config.mdx index 53bb8ceef0..c7fd919f38 100644 --- a/docs/reference/gateway-config.mdx +++ b/docs/reference/gateway-config.mdx @@ -2,7 +2,7 @@ # SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. # SPDX-License-Identifier: Apache-2.0 title: "Gateway Configuration File" -sidebar-title: "Gateway Config" +sidebar-title: "Configuration" description: "Reference for the OpenShell gateway TOML configuration file (RFC 0003)." keywords: "Generative AI, Cybersecurity, AI Agents, Sandboxing, Gateway, Configuration, TOML, Reference" position: 5 diff --git a/docs/reference/policy-prover.mdx b/docs/reference/policy-prover.mdx index f34106c83a..cc2bc9f97e 100644 --- a/docs/reference/policy-prover.mdx +++ b/docs/reference/policy-prover.mdx @@ -2,7 +2,7 @@ # SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. # SPDX-License-Identifier: Apache-2.0 title: "Standalone Policy Prover" -sidebar-title: "Policy Prover" +sidebar-title: "Prover" description: "Install and use the standalone OpenShell policy prover to check a local candidate policy against a managed boundary." keywords: "Generative AI, Cybersecurity, Policy, Prover, Boundary, Containment, CI" position: 4 diff --git a/docs/reference/policy-schema.mdx b/docs/reference/policy-schema.mdx index 3e1539b7b0..a1583ab4e7 100644 --- a/docs/reference/policy-schema.mdx +++ b/docs/reference/policy-schema.mdx @@ -2,7 +2,7 @@ # SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. # SPDX-License-Identifier: Apache-2.0 title: "Policy Schema Reference" -sidebar-title: "Policy Schema" +sidebar-title: "Schema" description: "Complete field reference for the sandbox policy YAML including static and dynamic sections." keywords: "Generative AI, Cybersecurity, Policy, Schema, YAML, Reference, Security" position: 3 diff --git a/docs/reference/sandbox-compute-drivers.mdx b/docs/reference/sandbox-compute-drivers.mdx index 2eb116902d..2076d61012 100644 --- a/docs/reference/sandbox-compute-drivers.mdx +++ b/docs/reference/sandbox-compute-drivers.mdx @@ -1,9 +1,9 @@ --- # SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. # SPDX-License-Identifier: Apache-2.0 -title: "Sandbox Compute Drivers" -sidebar-title: "Compute Drivers" -description: "Reference for Docker, Podman, MicroVM, Kubernetes, and Windows MXC sandbox compute drivers." +title: "Sandbox Runtimes" +sidebar-title: "Runtimes" +description: "Reference for Docker, Podman, MicroVM, Kubernetes, and Windows MXC sandbox runtimes." keywords: "Generative AI, Cybersecurity, AI Agents, Sandboxing, Docker, Podman, MicroVM, Kubernetes, MXC, Reference" position: 4 --- @@ -118,6 +118,7 @@ are driver names, such as `kubernetes`, and are not part of the nested schema. ```shell openshell sandbox create \ + --from registry.example.com/team/claude-code:1.0 \ --driver-config-json '{"kubernetes":{"pod":{"runtime_class_name":"kata-containers","priority_class_name":"batch-low"}}}' \ -- claude ``` @@ -226,6 +227,7 @@ docker volume create --label openshell.ai/sandbox-attachable=true \ --label openshell.ai/sandbox-attachable-workspace=default openshell-work openshell sandbox create \ + --from registry.example.com/team/claude-code:1.0 \ --driver-config-json '{"docker":{"mounts":[{"type":"volume","source":"openshell-work","target":"/sandbox/work","read_only":false}]}}' \ -- claude ``` @@ -251,6 +253,7 @@ enabled = false ```shell openshell sandbox create \ + --from registry.example.com/team/claude-code:1.0 \ --driver-config-json '{"docker":{"mounts":[{"type":"bind","source":"/srv/openshell/work","target":"/sandbox/work","read_only":false}]}}' \ -- claude ``` @@ -319,6 +322,7 @@ podman volume create --label openshell.ai/sandbox-attachable=true \ --label openshell.ai/sandbox-attachable-workspace=default openshell-work openshell sandbox create \ + --from registry.example.com/team/claude-code:1.0 \ --driver-config-json '{"podman":{"mounts":[{"type":"volume","source":"openshell-work","target":"/sandbox/work","read_only":false}]}}' \ -- claude ``` @@ -344,6 +348,7 @@ enabled = false ```shell openshell sandbox create \ + --from registry.example.com/team/claude-code:1.0 \ --driver-config-json '{"podman":{"mounts":[{"type":"bind","source":"/srv/openshell/work","target":"/sandbox/work","read_only":false}]}}' \ -- claude ``` @@ -397,7 +402,7 @@ compute_driver = "vm" For a launch-time override, set `OPENSHELL_COMPUTE_DRIVER=vm` in the gateway environment and restart the service. -Configure VM driver values such as `grpc_endpoint`, `driver_dir`, `state_dir`, `default_image`, `bootstrap_image`, `vcpus`, `mem_mib`, `overlay_disk_mib`, `krun_log_level`, and `guest_tls_*` in `[openshell.drivers.vm]`. The default sandbox image is `nvcr.io/nvidia/base/ubuntu:24.04`. The VM `state_dir` stores overlay disks, console logs, runtime state, image-rootfs cache, and the private `run/compute-driver.sock` socket. The VM socket path is managed by the gateway and is not configurable through remote endpoint settings. +Configure VM driver values such as `grpc_endpoint`, `driver_dir`, `state_dir`, `default_image`, `bootstrap_image`, `vcpus`, `mem_mib`, `overlay_disk_mib`, `krun_log_level`, and `guest_tls_*` in `[openshell.drivers.vm]`. The default workload and bootstrap image is `nvcr.io/nvidia/base/ubuntu:24.04`; configure a user-owned image with the agents and tools required by the workload. The VM `state_dir` stores overlay disks, console logs, runtime state, image-rootfs cache, and the private `run/compute-driver.sock` socket. The VM socket path is managed by the gateway and is not configurable through remote endpoint settings. The gateway starts `openshell-driver-vm` over a private Unix socket and passes its process ID so the driver can reject unexpected local clients. The driver's standalone TCP listener is disabled unless `--allow-unauthenticated-tcp` is set for local development. @@ -542,6 +547,7 @@ OpenShell-created `/sandbox` workspace PVC. ```shell openshell sandbox create \ + --from registry.example.com/team/claude-code:1.0 \ --driver-config-json '{ "kubernetes": { "volumes": [{ diff --git a/docs/reference/support-matrix.mdx b/docs/reference/support-matrix.mdx index 575058e4b9..6ef3082674 100644 --- a/docs/reference/support-matrix.mdx +++ b/docs/reference/support-matrix.mdx @@ -47,11 +47,11 @@ OpenShell publishes standalone `openshell-prover` release assets for manual down These artifacts are attached to GitHub releases. The Linux binaries are static and do not require glibc. All prover archives include the required solver linkage. -## Compute Drivers +## Runtimes -The gateway can manage sandboxes through several compute drivers. +The gateway can manage sandboxes through several runtimes. -| Compute Driver | Status | Notes | +| Runtime | Status | Notes | |---|---|---| | Docker | Supported for local development and single-machine gateways. | Requires Docker Desktop or Docker Engine on the gateway host. | | Podman | Supported for rootless local and workstation workflows. | Requires a Podman-compatible socket and rootless networking setup. | @@ -141,6 +141,9 @@ qualification output as `seccomp_listener_mode` (`killable` or On macOS, these kernel modules run inside the Docker Desktop Linux VM, not on the host kernel. -## Agent Compatibility +## Agent Workloads -For the full list of supported agents and their default policy coverage, refer to the [Supported Agents](/about/supported-agents) page. +OpenShell runs agents and tools that you install in a user-owned OCI image. The +image must satisfy the selected compute driver's platform requirements. Refer to +[Run Your First Agent](/about/run-an-agent) for the image, provider, and policy +workflow. diff --git a/docs/sandboxes/inference-routing.mdx b/docs/sandboxes/inference-routing.mdx index b0234e9686..4ba63ea7ca 100644 --- a/docs/sandboxes/inference-routing.mdx +++ b/docs/sandboxes/inference-routing.mdx @@ -1,8 +1,8 @@ --- # SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. # SPDX-License-Identifier: Apache-2.0 -title: "Provider-backed Inference" -sidebar-title: "Provider-backed Inference" +title: "Inference" +sidebar-title: "Inference" description: "Grant a sandbox access to model providers through provider profiles, attachments, and native endpoints." keywords: "Generative AI, Cybersecurity, Inference, Provider Profiles, Credentials, LLM" position: 8 @@ -60,6 +60,7 @@ openshell provider create \ openshell sandbox create \ --name inference-demo \ + --from registry.example.com/team/python-agent:1.0 \ --provider nvidia-prod \ -- python app.py ``` @@ -161,6 +162,7 @@ openshell provider create --name ollama --type ollama-openai openshell sandbox create \ --name ollama-client \ + --from registry.example.com/team/python-agent:1.0 \ --provider ollama \ --env OPENAI_BASE_URL=http://host.openshell.internal:11434/v1 \ -- python app.py @@ -295,7 +297,7 @@ Special cases require additional work: - Host-local services need `host.openshell.internal` or a reachable LAN/service hostname, not `127.0.0.1` or `localhost`. - Google Vertex AI clients must use the native Vertex endpoint and - authentication behavior. See [Google Vertex AI](/providers/google-vertex-ai). + authentication behavior. See [Google](/providers/google-cloud#vertex-ai). - A bridge-fronted AWS Bedrock deployment needs a custom profile that declares the bridge endpoint and allowed client binaries. @@ -313,4 +315,4 @@ headers, model selection, request shape, streaming, and timeout behavior. - [Profiles](/providers/profiles) - [Providers](/sandboxes/manage-providers) - [Customize Sandbox Policies](/sandboxes/policies) -- [Google Vertex AI](/providers/google-vertex-ai) +- [Google](/providers/google-cloud#vertex-ai) diff --git a/docs/sandboxes/manage-gateways.mdx b/docs/sandboxes/manage-gateways.mdx index 731fd52c12..0514e012ed 100644 --- a/docs/sandboxes/manage-gateways.mdx +++ b/docs/sandboxes/manage-gateways.mdx @@ -2,7 +2,7 @@ # SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. # SPDX-License-Identifier: Apache-2.0 title: "Manage Gateways" -sidebar-title: "Gateways" +sidebar-title: "Overview" description: "Register OpenShell gateways, switch between environments, inspect gateway status, and troubleshoot gateway access." keywords: "Generative AI, Cybersecurity, Gateway, Docker, Podman, Kubernetes, MicroVM, CLI" position: 2 @@ -20,11 +20,11 @@ The gateway is responsible for: OpenShell separates gateway access from the compute driver that runs sandboxes. Use [Installation](/about/installation) to install OpenShell, choose a compute driver, and start a gateway. This page covers working with gateway entries after a gateway exists. -## Gateway Compute Drivers +## Gateway Runtimes A gateway provisions sandboxes through the compute driver configured for that gateway. -| Compute Driver | Where sandboxes run | Best for | +| Runtime | Where sandboxes run | Best for | |---|---|---| | Docker | Containers on the gateway host. | Solo development, quick iteration, and single-machine gateways. | | Podman | Rootless containers on the gateway host. | Workstations that avoid a rootful Docker daemon. | @@ -195,5 +195,5 @@ For sandbox startup failures, inspect the selected compute driver: ## Next Steps - To install OpenShell and choose a compute driver, refer to [Installation](/about/installation). -- To configure workspace membership and roles, refer to [Manage Workspaces and Access](/sandboxes/manage-workspaces). +- To configure workspace membership and roles, refer to [Workspaces](/sandboxes/manage-workspaces). - To create a sandbox using the gateway, refer to [Manage Sandboxes](/sandboxes/manage-sandboxes). diff --git a/docs/sandboxes/manage-providers.mdx b/docs/sandboxes/manage-providers.mdx index a1837c0a07..8da46617e9 100644 --- a/docs/sandboxes/manage-providers.mdx +++ b/docs/sandboxes/manage-providers.mdx @@ -2,7 +2,7 @@ # SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. # SPDX-License-Identifier: Apache-2.0 title: "Providers" -sidebar-title: "Providers" +sidebar-title: "Overview" description: "Create and manage credential providers that inject API keys and tokens into OpenShell sandboxes." keywords: "Generative AI, Cybersecurity, Providers, Credentials, API Keys, Sandbox, Security" position: 4 @@ -476,14 +476,14 @@ An OpenAI-compatible protocol does not make the `openai` profile safe for an arbitrary host. Baseten, Bitdeer, Groq, Ollama, LM Studio, self-hosted NIM, and other alternate endpoints need their own profile declaring the actual host, port, credential, and allowed binaries. See -[Provider-backed Inference](/sandboxes/inference-routing) for complete examples +[Inference](/sandboxes/inference-routing) for complete examples and migration guidance. ## Next Steps Explore related topics: -- To manage workspace access for providers, refer to [Manage Workspaces and Access](/sandboxes/manage-workspaces). +- To manage workspace access for providers, refer to [Workspaces](/sandboxes/manage-workspaces). - To control what the agent can access, refer to [Policies](/sandboxes/policies). - To use the default workload image, refer to [Sandboxes](/sandboxes/manage-sandboxes#default-workload-image). - To view the complete field reference for the policy YAML, refer to the [Policy Schema Reference](/reference/policy-schema). diff --git a/docs/sandboxes/manage-sandboxes.mdx b/docs/sandboxes/manage-sandboxes.mdx index 3cf3fdf838..6363c2d167 100644 --- a/docs/sandboxes/manage-sandboxes.mdx +++ b/docs/sandboxes/manage-sandboxes.mdx @@ -2,7 +2,7 @@ # SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. # SPDX-License-Identifier: Apache-2.0 title: "Manage Sandboxes" -sidebar-title: "Sandboxes" +sidebar-title: "Overview" description: "Create sandboxes, understand sandbox isolation, and manage the full sandbox lifecycle." keywords: "Generative AI, Cybersecurity, Gateway, Sandboxing, AI Agents, Sandbox Management, CLI" position: 1 @@ -297,7 +297,7 @@ Override it with any image visible to the active compute driver: openshell sandbox create --from registry.example.com/agents/my-agent:1.0 ``` -Refer to [Default Policy](/reference/default-policy), [Supported Agents](/about/supported-agents), and the [BYOC example](https://github.com/NVIDIA/OpenShell/tree/main/examples/bring-your-own-container). +Refer to [Default Policy](/reference/default-policy), [Run Your First Agent](/about/run-an-agent), and the [bring-your-own-container example](https://github.com/NVIDIA/OpenShell/tree/main/examples/bring-your-own-container). ## Connect to a Sandbox @@ -899,16 +899,16 @@ with reason `MainProcessCompleted`. Nonzero and signal-normalized results use signal exits use the standard `128 + signal` convention. Compute runtimes do not automatically restart that process. -## Sandbox Compute Drivers +## Sandbox Runtimes The gateway's configured compute driver determines how OpenShell creates each sandbox. The CLI workflow stays the same across drivers: you create, connect to, inspect, and delete sandboxes through the gateway API. -For Docker, Podman, MicroVM, and Kubernetes behavior, refer to [Sandbox Compute Drivers](/reference/sandbox-compute-drivers). +For Docker, Podman, MicroVM, and Kubernetes behavior, refer to [Sandbox Runtimes](/reference/sandbox-compute-drivers). ## Next Steps - To follow a complete end-to-end example, refer to the [GitHub Sandbox](/get-started/tutorials/github-sandbox) tutorial. -- To select a workspace or understand access roles, refer to [Manage Workspaces and Access](/sandboxes/manage-workspaces). +- To select a workspace or understand access roles, refer to [Workspaces](/sandboxes/manage-workspaces). - 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). - To use the default runtime image, refer to [Default Workload Image](#default-workload-image). diff --git a/docs/sandboxes/manage-workspaces.mdx b/docs/sandboxes/manage-workspaces.mdx index 7fb6a1ff24..74ae99a71d 100644 --- a/docs/sandboxes/manage-workspaces.mdx +++ b/docs/sandboxes/manage-workspaces.mdx @@ -1,8 +1,8 @@ --- # SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. # SPDX-License-Identifier: Apache-2.0 -title: "Manage Workspaces and Access" -sidebar-title: "Workspaces and Access" +title: "Workspaces" +sidebar-title: "Workspaces" description: "Create OpenShell workspaces, assign members, and understand platform and workspace roles." keywords: "Generative AI, Cybersecurity, Workspaces, Access Control, RBAC, OIDC, Membership, CLI" position: 3 @@ -141,7 +141,11 @@ can appear before or after the subcommand. ```shell openshell sandbox list --workspace team-ml openshell provider list --workspace team-ml -openshell sandbox create --workspace team-ml --name research -- bash +openshell sandbox create \ + --workspace team-ml \ + --name research \ + --from registry.example.com/team/agent-tools:1.0 \ + -- bash ``` Set a default for the current shell with `OPENSHELL_WORKSPACE`: diff --git a/docs/sandboxes/policies.mdx b/docs/sandboxes/policies.mdx index d3fb6235d2..698701d505 100644 --- a/docs/sandboxes/policies.mdx +++ b/docs/sandboxes/policies.mdx @@ -2,7 +2,7 @@ # SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. # SPDX-License-Identifier: Apache-2.0 title: "Customize Sandbox Policies" -sidebar-title: "Policies" +sidebar-title: "Overview" description: "Apply, iterate, and debug sandbox network policies with hot-reload on running OpenShell sandboxes." keywords: "Generative AI, Cybersecurity, Policy, Network Policy, Sandbox, Security, Hot Reload" position: 6 diff --git a/docs/sandboxes/policy-advisor.mdx b/docs/sandboxes/policy-advisor.mdx index 80884620d5..938bf93bd1 100644 --- a/docs/sandboxes/policy-advisor.mdx +++ b/docs/sandboxes/policy-advisor.mdx @@ -2,7 +2,7 @@ # SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. # SPDX-License-Identifier: Apache-2.0 title: "Use Policy Advisor" -sidebar-title: "Policy Advisor" +sidebar-title: "Advisor" description: "Let sandboxed agents propose narrow policy changes through policy.local while keeping developer approval in the loop." keywords: "Generative AI, Cybersecurity, Policy Advisor, Policy, Sandbox, policy.local, Agent Policy" position: 7 diff --git a/docs/sdk/go.mdx b/docs/sdk/go.mdx new file mode 100644 index 0000000000..478280934d --- /dev/null +++ b/docs/sdk/go.mdx @@ -0,0 +1,126 @@ +--- +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 +title: "Go SDK" +sidebar-title: "Go" +description: "Install the OpenShell Go SDK, connect to a gateway, and manage a sandbox." +keywords: "OpenShell, SDK, Go, Golang, gRPC, Sandbox" +position: 1 +--- + +Use the Go SDK to manage OpenShell resources from Go applications, operators, +and controllers. Its typed subclients follow familiar Kubernetes client +patterns. Use the SDK and gateway from the same OpenShell release when possible. + +## Install the SDK + +The SDK requires Go 1.25.13 or later. Add it to your Go module: + +```shell +go get github.com/NVIDIA/OpenShell/sdk/go@latest +``` + +## Connect to a Gateway + +Pass a `host:port` address to `NewClient`. For a local gateway that allows +unauthenticated plaintext connections: + +```go +package main + +import ( + "context" + "fmt" + "log" + "time" + + v1 "github.com/NVIDIA/OpenShell/sdk/go/openshell/v1" +) + +func main() { + client, err := v1.NewClient(v1.Config{ + Address: "127.0.0.1:8080", + Auth: v1.NoAuth(), + }) + if err != nil { + log.Fatal(err) + } + defer client.Close() + + ctx, cancel := context.WithTimeout(context.Background(), 2*time.Minute) + defer cancel() + + health, err := client.Health().Check(ctx) + if err != nil { + log.Fatal(err) + } + fmt.Printf("gateway healthy: %v\n", health.Healthy) +} +``` + +For an authenticated TLS gateway, provide the bearer token and TLS settings: + +```go +client, err := v1.NewClient(v1.Config{ + Address: "gateway.example.com:443", + Auth: v1.StaticToken(os.Getenv("OPENSHELL_TOKEN")), + TLS: &v1.TLSConfig{CAFile: "/path/to/ca.crt"}, +}) +``` + +Omit `CAFile` to use system roots. For renewable OIDC service credentials, use +`oidc.NewClientCredentialsAuth` from +`github.com/NVIDIA/OpenShell/sdk/go/openshell/v1/oidc`. + +## Create and Use a Sandbox + +Resource methods take an explicit workspace. The following example creates a +sandbox in `default`, waits for readiness, runs a command, and requests +deletion: + +```go +sandbox, err := client.Sandboxes().Create( + ctx, + "default", + "sdk-example", + &v1.SandboxSpec{ + Template: &v1.SandboxTemplate{ + Image: "registry.example.com/team/python-agent:1.0", + }, + }, + nil, +) +if err != nil { + log.Fatal(err) +} + +sandbox, err = client.Sandboxes().WaitReady(ctx, "default", sandbox.Name) +if err != nil { + log.Fatal(err) +} + +result, err := client.Exec().Run( + ctx, + "default", + sandbox.Name, + []string{"python", "-c", "print('hello from OpenShell')"}, +) +if err != nil { + log.Fatal(err) +} +fmt.Print(string(result.Stdout)) + +if _, err := client.Sandboxes().Delete(ctx, "default", sandbox.Name); err != nil { + log.Fatal(err) +} +``` + +The root client also exposes subclients for providers, services, files, SSH, +TCP forwarding, policy, configuration, templates, and workspaces. List methods +return lazy pagers so callers choose when to fetch the next page. + +## Next Steps + +- Review [Gateway Authentication](/reference/gateway-auth) before connecting a service to a production gateway. +- Review [API Errors](/reference/api-errors) for the gateway error model. +- Browse the [Go package reference](https://pkg.go.dev/github.com/NVIDIA/OpenShell/sdk/go/openshell/v1) for all exported types and methods. diff --git a/docs/sdk/python.mdx b/docs/sdk/python.mdx new file mode 100644 index 0000000000..c03478cdd5 --- /dev/null +++ b/docs/sdk/python.mdx @@ -0,0 +1,114 @@ +--- +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 +title: "Python SDK" +sidebar-title: "Python" +description: "Install the OpenShell Python SDK, reuse a registered gateway, and manage a sandbox." +keywords: "OpenShell, SDK, Python, PyPI, gRPC, Sandbox" +position: 3 +--- + +Use the Python SDK to manage sandboxes from applications, notebooks, and +automation. It can reuse gateway registration and authentication state created +by the OpenShell CLI. Use the SDK and gateway from the same OpenShell release +when possible. + +## Install the SDK + +The package requires Python 3.11 or later. Add it to your project with `uv`: + +```shell +uv add openshell +``` + +The `openshell` package contains the SDK. It does not install the OpenShell CLI. + +## Connect to a Registered Gateway + +Register and select a gateway with the CLI first. Then construct the client from +the active gateway: + +```python +from openshell import SandboxClient + +with SandboxClient.from_active_cluster() as client: + health = client.health() + print(health.version) +``` + +`from_active_cluster()` reads the selected gateway endpoint, TLS files, and +OIDC token state. It refreshes an expiring OIDC token by default and writes the +rotated bundle back for other OpenShell processes. + +For a direct local plaintext connection, pass a `host:port` endpoint: + +```python +from openshell import SandboxClient + +with SandboxClient("127.0.0.1:8080") as client: + print(client.health().version) +``` + +For service automation against an OIDC gateway, use +`ClientCredentialsAuth`. Non-loopback endpoints require TLS: + +```python +import os + +from openshell import ClientCredentialsAuth, SandboxClient + +auth = ClientCredentialsAuth( + issuer="https://idp.example.com/realms/openshell", + client_id="openshell-service", + client_secret=lambda: os.environ["OPENSHELL_OIDC_CLIENT_SECRET"], + audience="openshell-gateway", +) + +with SandboxClient.from_active_cluster(client_credentials=auth) as client: + print(client.health().version) +``` + +## Create and Use a Sandbox + +Python SDK methods take an explicit workspace. This example creates a sandbox, +waits for readiness, runs a command, and waits for deletion: + +```python +from openshell import SandboxClient + +with SandboxClient.from_active_cluster() as client: + sandbox = client.create( + workspace="default", + name="sdk-example", + ) + client.wait_ready( + sandbox.name, + workspace="default", + timeout_seconds=120, + ) + + result = client.exec( + sandbox.name, + ["python", "-c", "print('hello from OpenShell')"], + workspace="default", + ) + print(result.stdout, end="") + + deletion = client.delete(sandbox.name, workspace="default") + client.wait_deleted( + sandbox.name, + workspace="default", + expected_sandbox_id=deletion.sandbox_id, + ) +``` + +Use `create_session()` when you want an object that retains the sandbox name and +workspace for repeated exec, stop, start, and delete operations. List methods +return lazy `Pager` instances; use `list_all()` only when you want to fetch the +complete collection. + +## Next Steps + +- Review [Manage Sandboxes](/sandboxes/manage-sandboxes) for labels, templates, services, and Python SDK examples. +- Review [Gateway Authentication](/reference/gateway-auth) for OIDC and client credentials. +- Review [API Errors](/reference/api-errors) for structured error handling. diff --git a/docs/sdk/rust.mdx b/docs/sdk/rust.mdx new file mode 100644 index 0000000000..20e938a84c --- /dev/null +++ b/docs/sdk/rust.mdx @@ -0,0 +1,129 @@ +--- +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 +title: "Rust SDK" +sidebar-title: "Rust" +description: "Install the OpenShell Rust SDK, connect to a gateway, and manage a sandbox asynchronously." +keywords: "OpenShell, SDK, Rust, Cargo, Tonic, gRPC, Sandbox" +position: 2 +--- + +The Rust SDK is the asynchronous gateway client used by the OpenShell CLI and +TUI. Its curated API covers common sandbox operations, while `raw` exposes the +generated Tonic clients for the complete RPC surface. Use the SDK and gateway +from the same OpenShell release when possible. + +## Install the SDK + +The Rust SDK is currently consumed from source. Pin the dependency to the same +release tag as your gateway: + +```shell +cargo add openshell-sdk \ + --git https://github.com/NVIDIA/OpenShell \ + --tag +cargo add tokio --features macros,rt-multi-thread +``` + +## Connect to a Gateway + +`ClientConfig` accepts a full gateway URL. This local example uses plaintext +transport and no authentication: + +```rust +use openshell_sdk::{ClientConfig, OpenShellClient}; + +let client = OpenShellClient::connect( + ClientConfig::new("http://127.0.0.1:8080"), +) +.await?; + +let health = client.health().await?; +println!("gateway status: {:?}", health.status); +``` + +For an OIDC gateway, attach a bearer token and use HTTPS: + +```rust +use openshell_sdk::{AuthConfig, ClientConfig, OpenShellClient}; + +let client = OpenShellClient::connect(ClientConfig { + gateway: "https://gateway.example.com".to_string(), + auth: Some(AuthConfig::oidc(std::env::var("OPENSHELL_TOKEN")?)), + ..Default::default() +}) +.await?; +``` + +Set `ca_cert` when the gateway uses a private CA. The Rust SDK supports +server-authenticated TLS and OIDC bearer authentication. It does not support +mTLS client certificates or read the CLI gateway configuration from disk. + +## Create and Use a Sandbox + +Curated operations use the `default` workspace. Use +`client.workspace("name")` when your application targets another +workspace. + +```rust +use std::time::Duration; + +use openshell_sdk::{ + ClientConfig, DeleteOptions, ExecOptions, OpenShellClient, SandboxSpec, +}; + +#[tokio::main] +async fn main() -> Result<(), Box> { + let client = OpenShellClient::connect( + ClientConfig::new("http://127.0.0.1:8080"), + ) + .await?; + + let sandbox = client + .create_sandbox(SandboxSpec { + name: Some("sdk-example".to_string()), + image: Some( + "registry.example.com/team/python-agent:1.0" + .to_string(), + ), + ..Default::default() + }) + .await?; + + client + .wait_ready(&sandbox.name, Duration::from_secs(120)) + .await?; + + let result = client + .exec( + &sandbox.name, + &["python".into(), "-c".into(), "print('hello from OpenShell')".into()], + ExecOptions::default(), + ) + .await?; + print!("{}", String::from_utf8_lossy(&result.stdout)); + + let deletion = client + .delete_sandbox(&sandbox.name, DeleteOptions::default()) + .await?; + client + .wait_deleted( + &sandbox.name, + Duration::from_secs(60), + deletion.sandbox_id.as_deref(), + ) + .await?; + + Ok(()) +} +``` + +Use `raw_grpc_fresh()` for RPCs that the curated API does not yet wrap. The raw +client returns generated protobuf types and requires callers to assemble full +requests. + +## Next Steps + +- Review [Gateway Authentication](/reference/gateway-auth) for transport and identity choices. +- Review [API Errors](/reference/api-errors) for the gateway error model. +- See the [Rust SDK source documentation](https://github.com/NVIDIA/OpenShell/tree/main/crates/openshell-sdk) for modules and advanced transport behavior. diff --git a/docs/sdk/typescript.mdx b/docs/sdk/typescript.mdx new file mode 100644 index 0000000000..f9ac855480 --- /dev/null +++ b/docs/sdk/typescript.mdx @@ -0,0 +1,110 @@ +--- +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 +title: "TypeScript SDK" +sidebar-title: "TypeScript" +description: "Install the OpenShell TypeScript SDK, connect to a gateway, and manage a sandbox." +keywords: "OpenShell, SDK, TypeScript, Node.js, Connect, gRPC, Sandbox" +position: 4 +--- + +Use the TypeScript SDK in Node.js applications and automation. It provides a +curated sandbox API and a raw generated client for the full gateway RPC surface. +Use the SDK and gateway from the same OpenShell release when possible. + +## Install the SDK + +The package requires Node.js 20.3 or later and is currently distributed through +GitHub Packages. Configure the `@nvidia` scope in your project `.npmrc`: + +```text +@nvidia:registry=https://npm.pkg.github.com +``` + +Authenticate npm with a GitHub token that has `read:packages`, then install the +package: + +```shell +npm install @nvidia/openshell-sdk +``` + +## Connect to a Gateway + +`OpenShellClient.connect()` accepts a gateway URL. It constructs a lazy client, +so call `health()` when startup must verify connectivity: + +```ts +import { OpenShellClient } from '@nvidia/openshell-sdk' + +const client = await OpenShellClient.connect({ + gateway: 'https://gateway.example.com', + oidcToken: process.env.OPENSHELL_TOKEN, +}) + +const health = await client.health() +console.log(`${health.status}: ${health.version}`) +``` + +For long-running OIDC service automation, use a renewable client-credentials +provider: + +```ts +import { clientCredentials, OpenShellClient } from '@nvidia/openshell-sdk' + +const client = await OpenShellClient.connect({ + gateway: 'https://gateway.example.com', + oidcTokenProvider: clientCredentials({ + issuer: 'https://idp.example.com/realms/openshell', + clientId: 'openshell-service', + clientSecret: () => process.env.OPENSHELL_OIDC_CLIENT_SECRET!, + audience: 'openshell-gateway', + }), +}) +``` + +The provider retains credentials and tokens in memory and renews the access +token before expiry. + +## Create and Use a Sandbox + +The curated client uses the `default` workspace unless you pass `workspace` in +an operation's options: + +```ts +const sandbox = await client.sandbox.create({ + name: 'sdk-example', + image: 'registry.example.com/team/python-agent:1.0', +}) + +await client.sandbox.waitReady(sandbox.name, 120) + +const result = await client.sandbox.exec( + sandbox.name, + ['python', '-c', "print('hello from OpenShell')"], +) +console.log(result.stdout.toString()) + +const deletion = await client.sandbox.delete(sandbox.name) +if (deletion.outcome === 'accepted') { + await client.sandbox.waitDeleted(sandbox.name, 60, { + expectedSandboxId: deletion.sandboxId, + }) +} +``` + +`client.sandbox` also supports streaming and interactive exec, TCP forwarding, +SSH sessions, sandbox provider attachment, configuration, and policy. Close +operation-scoped streams and forwarding handles when finished. The root client +does not retain a dedicated session and has no `close()` method. + +## Use the Raw Client + +Use `client.raw` for RPCs that the curated clients do not yet wrap. Import +generated message schemas and types from `@nvidia/openshell-sdk/raw`. Raw calls +return protobuf wire shapes, while curated calls return SDK-specific types. + +## Next Steps + +- Review [Gateway Authentication](/reference/gateway-auth) for OIDC and service authentication. +- Review [API Errors](/reference/api-errors) for structured error handling. +- See the [TypeScript SDK source documentation](https://github.com/NVIDIA/OpenShell/tree/main/sdk/typescript) for streaming, forwarding, and raw client examples. diff --git a/docs/security/best-practices.mdx b/docs/security/best-practices.mdx index a011677c23..c5b5c938cb 100644 --- a/docs/security/best-practices.mdx +++ b/docs/security/best-practices.mdx @@ -13,7 +13,7 @@ OpenShell enforces sandbox security across four layers: network, filesystem, pro This page documents every configurable control, its default, what it protects, and the risk of relaxing it. For the full policy YAML schema, refer to the [Policy Schema](/reference/policy-schema). -For the architecture of each enforcement layer, refer to [How OpenShell Works](/about/how-it-works). +For the architecture of each enforcement layer, refer to [Architecture](/about/how-it-works). If you use [NemoClaw](https://github.com/NVIDIA/NemoClaw), its [Security Best Practices](https://docs.nvidia.com/nemoclaw/latest/security/best-practices.html) guide covers additional entrypoint-level controls, policy presets, provider trust tiers, and posture profiles specific to the NemoClaw blueprint. @@ -239,7 +239,7 @@ This ordering is intentional: named network-namespace setup still relies on priv 6. Landlock filesystem restrictions. 7. Runtime seccomp socket domain and syscall filters. -## Provider-backed Inference Controls +## Inference Controls Inference providers use the same endpoint-bound credential mechanism as other providers. Attach a profile-backed provider only to sandboxes that need it. @@ -299,5 +299,5 @@ The following patterns weaken security without providing meaningful benefit. - [Policy Schema](/reference/policy-schema) for the full field-by-field YAML reference. - [Default Policy](/reference/default-policy) for the built-in default policy breakdown. - [Gateway Auth](/reference/gateway-auth) for gateway authentication details. -- [How OpenShell Works](/about/how-it-works) for the system architecture. +- [Architecture](/about/how-it-works) for the system architecture. - NemoClaw [Security Best Practices](https://docs.nvidia.com/nemoclaw/latest/security/best-practices.html) for entrypoint-level controls (capability drops, PATH hardening, build toolchain removal), policy presets, provider trust tiers, and posture profiles. diff --git a/docs/upgrade/0-1-0.mdx b/docs/upgrade/0-1-0.mdx new file mode 100644 index 0000000000..5d617c5189 --- /dev/null +++ b/docs/upgrade/0-1-0.mdx @@ -0,0 +1,118 @@ +--- +# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 +title: "Upgrade to NVIDIA OpenShell 0.1.0" +sidebar-title: "0.1.0" +description: "Prepare OpenShell operators and users for the breaking changes in version 0.1.0." +keywords: "Generative AI, Cybersecurity, AI Agents, Sandboxing, Upgrade, Migration" +--- + +Upgrading from OpenShell 0.0.x to 0.1.0? Start with the section that matches how you use the platform. + +Each item links to the pull request that defines the change. + +## Operators + +If you run OpenShell for a team, start here. + +- **Coordinate the upgrade.** Stop all gateway replicas, back up the database, and upgrade gateways, compute and credential drivers, supervisors, middleware, CLI clients, and SDK clients from the same release. The protocol, field-name, and time-type changes do not support mixed 0.0.x and 0.1.0 peers ([PR #3113](https://github.com/NVIDIA/OpenShell/pull/3113), [PR #3272](https://github.com/NVIDIA/OpenShell/pull/3272), [PR #3352](https://github.com/NVIDIA/OpenShell/pull/3352)). + +- **Recreate every sandbox.** Remove 0.0.x sandboxes before the upgrade and recreate them afterward. The persisted sandbox boundary and runtime descriptors are not compatible with 0.1.0 ([PR #2942](https://github.com/NVIDIA/OpenShell/pull/2942), [PR #3366](https://github.com/NVIDIA/OpenShell/pull/3366)). + +- **Export provider profiles before upgrading.** The gateway no longer includes built-in profiles. Import the saved profiles after the upgrade at the same global or workspace scope. Replace profile aliases such as `claude` and `gh` with the canonical IDs `claude-code` and `github` ([PR #2962](https://github.com/NVIDIA/OpenShell/pull/2962), [PR #3383](https://github.com/NVIDIA/OpenShell/pull/3383)). + + ```shell + openshell provider profile export -o yaml --global > .yaml + openshell profile import --from ./profiles --global + ``` + +- **Migrate `gateway.toml` to schema version 2.** Add the version, replace the plural compute-driver selector, move driver settings under `[openshell.drivers.]`, and apply the renamed Docker, Podman, and VM fields. Validate the file before restarting. See [Gateway Configuration](/reference/gateway-config#migrate-to-schema-version-2) for the complete field mapping and [PR #2814](https://github.com/NVIDIA/OpenShell/pull/2814) for the implementation. + + ```toml + [openshell] + version = 2 + + [openshell.gateway] + compute_driver = "kubernetes" + + [openshell.drivers.kubernetes] + namespace = "openshell" + ``` + + ```shell + openshell-gateway config preflight --path /etc/openshell/gateway.toml + ``` + +- **Move Helm application settings to `gatewayConfig`.** Express gateway settings with the schema-v2 TOML hierarchy. Keep TLS keys, passwords, client secrets, RBAC, Services, image settings, and volumes in the chart-owned values and Secret interfaces ([PR #3384](https://github.com/NVIDIA/OpenShell/pull/3384)). + +- **Review the default workload image.** The fallback becomes the minimal `nvcr.io/nvidia/base/ubuntu:24.04` image, which includes no agent CLI or image-baked policy. Bare image aliases are removed, so specify a fully qualified image that you built with the required agents, tools, and startup behavior. The runtime fallback policy denies network access and no longer grants `/app`; images without an OCI `USER` run as UID and GID `1000` ([PR #3386](https://github.com/NVIDIA/OpenShell/pull/3386)). + +- **Preserve credential encryption material.** New provider credentials use the active gateway credential driver, with encrypted database storage as the default. Preserve the generated key-encryption-key Secret, reconfigure refresh grants, and recreate credentials before switching credential drivers. Do not configure an empty `credential_drivers` list or run mixed gateway versions against the same refresh records ([PR #2437](https://github.com/NVIDIA/OpenShell/pull/2437)). + +- **Update Kubernetes user-namespace configuration.** Remove `platform_config.host_users`. Use the typed sandbox template `user_namespaces` field or the Kubernetes driver default ([PR #3248](https://github.com/NVIDIA/OpenShell/pull/3248)). + +- **Approve caller-selected compute resources.** Compute drivers now disable caller-supplied `driver_config` by default. If you enable it, label each allowed PVC, RuntimeClass, PriorityClass, Docker volume, or Podman volume with `openshell.ai/sandbox-attachable=true` and `openshell.ai/sandbox-attachable-workspace=`. Recreate legacy sandboxes without verifiable admission provenance, pass matching admission settings to standalone drivers, and set `gateway.allowDriverConfig=true` on each split Helm workspace release ([PR #3538](https://github.com/NVIDIA/OpenShell/pull/3538), [PR #3571](https://github.com/NVIDIA/OpenShell/pull/3571)). + +- **Review Helm PKI and ingress settings.** PKI initialization now fails an install or upgrade after its timeout by default. Increase `pkiInitJob.timeoutSeconds` when needed, and set `server.tls.enableMtls=false` when enabling `grpcRoute.backendTLSPolicy` ([PR #2728](https://github.com/NVIDIA/OpenShell/pull/2728)). + +- **Remove orphaned Helm RBAC objects.** After verifying the new namespace-qualified `ClusterRole` and `ClusterRoleBinding`, delete the old fixed-name `openshell-gateway-node-reader` objects if no release still owns them ([PR #2939](https://github.com/NVIDIA/OpenShell/pull/2939)). + +- **Implement extension protocol negotiation.** Custom compute drivers, credential drivers, gateway interceptors, and middleware must exchange `PeerMetadata`, use protocol `1.0`, and advertise their family base capability. Upgrade both peers together. See [Extension Protocol Negotiation](/extensibility/extension-negotiation) and [PR #3352](https://github.com/NVIDIA/OpenShell/pull/3352). + +- **Remove compute-driver callback-listener negotiation.** Regenerate custom compute-driver bindings and connect supervisors to the operator-configured primary gateway endpoint ([PR #3365](https://github.com/NVIDIA/OpenShell/pull/3365)). + +- **Update supervisor middleware events.** Accept `MiddlewareDescribeRequest`, replace the WebSocket-specific terminal-event types with the shared middleware types, and handle the renamed and split end reasons ([PR #3073](https://github.com/NVIDIA/OpenShell/pull/3073)). + +- **Regenerate extension bindings.** Update canonical request field names and protobuf `Timestamp` and `Duration` fields. Do not reuse generated 0.0.x bindings with 0.1.0 peers ([PR #3113](https://github.com/NVIDIA/OpenShell/pull/3113), [PR #3272](https://github.com/NVIDIA/OpenShell/pull/3272)). + +- **Bind authenticated drivers to a runtime identity.** A custom compute driver that advertises `supports_sandbox_authentication` must return a non-empty `runtime_identity` from create, start, and authentication. It must also honor `expected_runtime_identity` during restart so the gateway can bind bootstrap credentials to the current compute resource ([PR #3531](https://github.com/NVIDIA/OpenShell/pull/3531)). + +## End users + +If you use OpenShell through the CLI, policies, APIs, or SDKs, review these changes. + +- **Build local images before sandbox creation.** `openshell sandbox create --from` no longer builds a Dockerfile or directory. Build and tag with the gateway's container engine, then pass the image reference. Remote gateways need an image they can pull from a registry ([PR #3214](https://github.com/NVIDIA/OpenShell/pull/3214)). + + ```shell + docker build -t registry.example.com/team/agent:0.1.0 . + docker push registry.example.com/team/agent:0.1.0 + openshell sandbox create --from registry.example.com/team/agent:0.1.0 + ``` + +- **Name providers explicitly.** A trailing sandbox command no longer infers or attaches a provider. Pass `--provider `, and ask the operator to import the referenced profile when it is missing ([PR #3383](https://github.com/NVIDIA/OpenShell/pull/3383)). + +- **Replace managed inference routes.** The `openshell inference` commands, route APIs, and `inference.local` endpoint are removed. Attach a provider to each sandbox and call its native endpoint with its native model and request format. See [Migrate from Managed Inference Routes](/sandboxes/inference-routing#migrate-from-managed-inference-routes) and [PR #3195](https://github.com/NVIDIA/OpenShell/pull/3195). + +- **Remove `NetworkBinary.harness`.** In authored policies, keep each binary as an object containing only `path`, such as `- path: /usr/bin/curl`. In provider profiles, write binaries as scalar paths such as `- /usr/bin/curl` ([PR #3222](https://github.com/NVIDIA/OpenShell/pull/3222)). + +- **Fix unknown policy fields.** The authored policy schema rejects misspelled, obsolete, and other unknown fields instead of ignoring them ([PR #3334](https://github.com/NVIDIA/OpenShell/pull/3334)). + +- **Update endpoint modes.** Regenerate clients for the typed `tls`, `enforcement`, and `access` enums. Remove `tls: terminate` and `tls: passthrough`; omit `tls` for automatic inspection. Do not use `skip` as a replacement because it disables inspection ([PR #3187](https://github.com/NVIDIA/OpenShell/pull/3187), [PR #3414](https://github.com/NVIDIA/OpenShell/pull/3414)). + +- **Target L7 policy edits explicitly.** Policy update commands that append allow or deny rules must include `--rule-name` and every `--binary`, or `--any-binary`. Raw API calls must send the complete `L7RuleTarget` ([PR #3380](https://github.com/NVIDIA/OpenShell/pull/3380)). + +- **Send the negotiated MCP version.** MCP clients must include one `MCP-Protocol-Version` header on each post-initialization request, and the endpoint policy must allow that revision ([PR #3241](https://github.com/NVIDIA/OpenShell/pull/3241)). + +- **Select workspaces explicitly.** Regenerate clients for `WorkspaceSelector`, and select the literal `default` workspace when appropriate. Omission no longer selects it. See [Manage Workspaces](/sandboxes/manage-workspaces) and [PR #3245](https://github.com/NVIDIA/OpenShell/pull/3245). + +- **Use canonical resource names.** Public sandbox RPCs accept a sandbox name plus its workspace instead of an internal sandbox ID. Update renamed request and JSON fields such as `sandbox`, `provider`, and `name` ([PR #3272](https://github.com/NVIDIA/OpenShell/pull/3272)). + +- **Use protobuf time types.** Replace scalar millisecond, second, and string fields with `google.protobuf.Timestamp` and `google.protobuf.Duration`. Preserve the distinction between an absent field and a zero value. See [Protobuf Time Types](/reference/protobuf-time-types) and [PR #3113](https://github.com/NVIDIA/OpenShell/pull/3113). + +- **Replace offset pagination.** Send `page_size` and the opaque `page_token`, then continue while `next_page_token` is non-empty. Curated SDK list methods may return lazy, single-pass pagers; use `list_all` or `ListAll` only when the full collection is required ([PR #3249](https://github.com/NVIDIA/OpenShell/pull/3249), [PR #3256](https://github.com/NVIDIA/OpenShell/pull/3256), [PR #3279](https://github.com/NVIDIA/OpenShell/pull/3279)). + +- **Handle typed deletion outcomes.** Replace `deleted`, `removed`, and `revoked` booleans with `DeletionOutcome`. Treat `ACCEPTED` as asynchronous, use the returned sandbox ID when waiting, and set `allow_missing` only when absence is acceptable. See [SDK Migration for Deletion](/reference/api-errors#sdk-migration-for-deletion) and [PR #3317](https://github.com/NVIDIA/OpenShell/pull/3317). + +- **Update SDK error handling.** Python clients raise `GatewayError`, which is a `grpc.RpcError` but not a `grpc.Call`. Rust error variants contain additional status fields. SDKs expose retry details but do not automatically retry mutations ([PR #3313](https://github.com/NVIDIA/OpenShell/pull/3313)). + +- **Use stable request IDs for retries.** When a mutation includes `request_id`, retry with the same identity, scope, method, and payload. Cancellation does not cancel admitted work. Reconcile the result after `REQUEST_OUTCOME_UNCERTAIN` instead of submitting a new ID. An admitted exec retry cannot replay output, its exit code, or the stream, so handle `REQUEST_STREAM_UNAVAILABLE` separately ([PR #3321](https://github.com/NVIDIA/OpenShell/pull/3321), [PR #3323](https://github.com/NVIDIA/OpenShell/pull/3323), [PR #3324](https://github.com/NVIDIA/OpenShell/pull/3324)). + +- **Drain interactive exec after closing input.** Closing the request stream closes stdin but does not end output. Drain output concurrently and wait for both the exit event and final RPC status. Go clients use `CloseInteractiveInput` or `CancelInteractive`; TypeScript clients use `closeInput()` or `cancel()` ([PR #3359](https://github.com/NVIDIA/OpenShell/pull/3359)). + +- **Resume watch streams by cursor.** Treat stream warnings as recoverable gaps, persist the greatest processed opaque cursor, and send it when reconnecting. If the gateway returns `OUT_OF_RANGE`, discard the cursor and restart without resume ([PR #3209](https://github.com/NVIDIA/OpenShell/pull/3209)). + +- **Stop importing persistence messages.** The `StoredProviderProfile`, refresh-state, stored policy revision, and draft-chunk messages move to a private storage package and have no public API replacement ([PR #3169](https://github.com/NVIDIA/OpenShell/pull/3169)). + +- **Replace scripted `gateway info` calls.** The command now returns live, admin-gated runtime state. Use `openshell gateway list -o json` for local registration metadata ([PR #2202](https://github.com/NVIDIA/OpenShell/pull/2202)). + +- **Stop parsing the profile list table.** The human-readable columns change. Use JSON or YAML output in scripts; the structured profile schema is unchanged ([PR #3258](https://github.com/NVIDIA/OpenShell/pull/3258)). diff --git a/examples/local-inference/README.md b/examples/local-inference/README.md index 9f5d8bc7cd..7cc36513ed 100644 --- a/examples/local-inference/README.md +++ b/examples/local-inference/README.md @@ -1,4 +1,4 @@ -# Provider-backed Inference Example +# Inference Example This example calls the NVIDIA API Catalog through its native OpenAI-compatible endpoint. OpenShell supplies endpoint-bound credentials and network policy from diff --git a/fern/docs.yml b/fern/docs.yml index fc280965db..1be5371527 100644 --- a/fern/docs.yml +++ b/fern/docs.yml @@ -61,9 +61,21 @@ versions: slug: dev availability: beta announcement: - message: 'OpenShell 0.1.0 is coming soon. Track progress in the 0.1.0 milestone, read the prerelease documentation, or install a prerelease.' + message: 'New in OpenShell 0.1.0: a stable release cadence, an improved security model, an expanded extension surface, and new APIs. Read the 0.1.0 upgrade guide.' redirects: + - source: "/openshell/latest/providers/google-vertex-ai" + destination: "/openshell/latest/providers/google-cloud#vertex-ai" + - source: "/openshell/dev/providers/google-vertex-ai" + destination: "/openshell/dev/providers/google-cloud#vertex-ai" + - source: "/openshell/latest/about/supported-agents" + destination: "/openshell/latest/about/run-an-agent" + - source: "/openshell/dev/about/supported-agents" + destination: "/openshell/dev/about/run-an-agent" + - source: "/openshell/latest/get-started/quickstart" + destination: "/openshell/latest/about/run-an-agent" + - source: "/openshell/dev/get-started/quickstart" + destination: "/openshell/dev/about/run-an-agent" - source: "/openshell/latest/sandboxes/providers-v2" destination: "/openshell/latest/providers/profiles" # Paths are relative to the site root; subpath prefix matches instances + custom-domain.