diff --git a/docs/about/architecture.md b/docs/about/architecture.md index 4b343882..64fb1059 100644 --- a/docs/about/architecture.md +++ b/docs/about/architecture.md @@ -19,15 +19,18 @@ content: # How OpenShell Works -OpenShell runs as a [k3s](https://k3s.io/) Kubernetes cluster inside a Docker container. Each sandbox is an isolated Kubernetes pod managed through the gateway. Four components work together to keep agents secure. +OpenShell runs as a [K3s](https://k3s.io/) Kubernetes cluster inside a Docker container. Each sandbox is an isolated Kubernetes pod managed through the gateway. Four components work together to keep agents secure. -```{image} architecture.svg -:alt: OpenShell architecture diagram showing the OpenShell component layout +```{figure} architecture.svg +:alt: OpenShell architecture diagram showing the component layout :align: center +:target: ../_images/architecture.svg ``` ## Components +The following table describes each component and its role in the system: + | Component | Role | |---|---| | **Gateway** | Control-plane API that coordinates sandbox lifecycle and state, acts as the auth boundary, and brokers requests across the platform. | @@ -39,7 +42,7 @@ OpenShell runs as a [k3s](https://k3s.io/) Kubernetes cluster inside a Docker co Every outbound connection from agent code passes through the same decision path: -1. The agent process opens an outbound connection (API call, package install, git clone, etc.). +1. The agent process opens an outbound connection (API call, package install, git clone, and so on). 2. The proxy inside the sandbox intercepts the connection and identifies which binary opened it. 3. The proxy queries the policy engine with the destination, port, and calling binary. 4. The policy engine returns one of three decisions: @@ -54,13 +57,15 @@ For REST endpoints with TLS termination enabled, the proxy also decrypts TLS and OpenShell can run locally or on a remote host. The architecture is identical in both cases — only the Docker container location changes. - **Local**: the k3s cluster runs inside Docker on your workstation. The CLI provisions it automatically on first use. -- **Remote**: the cluster runs on a remote host. Deploy with `openshell gateway start --remote user@host`. For example, connect to your DGX Spark +- **Remote**: the cluster runs on a remote host. Deploy with `openshell gateway start --remote user@host`. For example, connect to your DGX Spark. ```console - $ openshell gateway start --remote @.local + $ openshell gateway start --remote @.local $ openshell status ``` ## Next Steps -- [Quickstart](get-started.md): Create your first sandbox. -- [Sandboxes](../sandboxes/index.md): Learn how OpenShell enforces isolation across all protection layers. +Continue with one of the following: + +- To create your first sandbox, refer to the [Quickstart](../get-started/quickstart.md). +- To learn how OpenShell enforces isolation across all protection layers, refer to [Sandboxes](../sandboxes/index.md). diff --git a/docs/about/overview.md b/docs/about/overview.md index 8b46bfbe..0064b955 100644 --- a/docs/about/overview.md +++ b/docs/about/overview.md @@ -38,7 +38,7 @@ The table below summarizes common failure modes and how OpenShell mitigates them ## Protection Layers at a Glance -OpenShell applies defense in depth across four policy domains: +OpenShell applies defense in depth across the following policy domains. | Layer | What it protects | When it applies | |---|---|---| @@ -51,15 +51,21 @@ For details, refer to [Built-in Default Policy](../sandboxes/index.md#built-in-d ## Common Use Cases -- **Secure coding agents**: Run Claude Code, OpenCode, or OpenClaw with constrained file and network access. -- **Private enterprise development**: Route inference to self-hosted or private backends while keeping sensitive context under your control. -- **Compliance and audit**: Treat policy YAML as version-controlled security controls that can be reviewed and audited. -- **Reusable environments**: Use community sandbox images or bring your own containerized runtime. +OpenShell supports a range of agent deployment patterns. + +| Use Case | Description | +|-----------------------------|----------------------------------------------------------------------------------------------------------| +| Secure coding agents | Run Claude Code, OpenCode, or OpenClaw with constrained file and network access. | +| Private enterprise development | Route inference to self-hosted or private backends while keeping sensitive context under your control. | +| Compliance and audit | Treat policy YAML as version-controlled security controls that can be reviewed and audited. | +| Reusable environments | Use community sandbox images or bring your own containerized runtime. | --- ## Next Steps -- [Architecture Overview](architecture.md): Understand the components that make up the OpenShell runtime. -- [Quickstart](get-started.md): Install the CLI and create your first sandbox. -- [Sandboxes](../sandboxes/index.md): Learn how OpenShell enforces isolation across all protection layers. +Explore these topics to go deeper: + +- To understand the components that make up the OpenShell runtime, refer to the [Architecture Overview](architecture.md). +- To install the CLI and create your first sandbox, refer to the [Quickstart](../get-started/quickstart.md). +- To learn how OpenShell enforces isolation across all protection layers, refer to [Sandboxes](../sandboxes/index.md). diff --git a/docs/about/release-notes.md b/docs/about/release-notes.md index 1290a939..3916208d 100644 --- a/docs/about/release-notes.md +++ b/docs/about/release-notes.md @@ -5,9 +5,17 @@ # Release Notes -This page covers the highlights of each OpenShell release. +Track the latest changes and improvements to NVIDIA OpenShell. +This page covers the highlights of the release. For more details, refer to the [OpenShell GitHub Releases](https://github.com/NVIDIA/OpenShell/releases). ## 0.1.0 This is the first release of NVIDIA OpenShell. It introduces sandboxed AI agent execution with kernel-level isolation, policy enforcement, and credential management. + +### Highlights + +- Introduces sandboxed AI agent execution with kernel-level isolation, policy enforcement, and credential management. +- Introduces the `openshell` CLI for creating, managing, and customizing sandboxes. +- Introduces the `openshell-gateway` service for managing the gateway and sandboxes. +- Introduces the `openshell-sandbox` service for running the sandboxed agent. diff --git a/docs/about/get-started.md b/docs/get-started/quickstart.md similarity index 61% rename from docs/about/get-started.md rename to docs/get-started/quickstart.md index c786b47f..fcefb4ca 100644 --- a/docs/about/get-started.md +++ b/docs/get-started/quickstart.md @@ -27,10 +27,12 @@ Before you begin, make sure you have: - Python 3.12 or later - [uv](https://docs.astral.sh/uv/) installed -- Docker Desktop running on your machine +- Docker Desktop running on your machine ## Install the OpenShell CLI +Install the `openshell` package into a virtual environment. + Activate your virtual environment: ```bash @@ -45,7 +47,7 @@ uv pip install openshell ## Connect to a Remote Gateway (Optional) -If you're running locally, skip this step — the CLI creates a gateway automatically when you create your first sandbox. +If you're running locally, skip this step. The OpenShell CLI creates a gateway automatically when you create your first sandbox. :::::{tab-set} @@ -55,7 +57,7 @@ If you're running locally, skip this step — the CLI creates a gateway automati Deploy an OpenShell gateway on Brev by hitting **Deploy** on the [OpenShell Launchable](https://brev.nvidia.com/launchable/deploy/now?launchableID=env-3AaK9NmCzWp3pVyUDNNFBt805FT). ::: -Once the instance is running, find the gateway URL in the Brev console under **Using Secure Links**. Copy the shareable URL for **port 8080** — this is the gateway endpoint. +After the instance is running, find the gateway URL in the Brev console under **Using Secure Links**. Copy the shareable URL for **port 8080** — this is the gateway endpoint. ```console $ openshell gateway add https://.brevlab.com @@ -67,7 +69,7 @@ $ openshell status ::::{tab-item} DGX Spark :::{note} -Set up your Spark with NVIDIA Sync first, or make sure SSH access is configured (e.g., SSH keys added to the host). +Set up your Spark with NVIDIA Sync first, or make sure SSH access is configured (such as SSH keys added to the host). ::: Deploy to a DGX Spark machine over SSH: @@ -77,7 +79,7 @@ $ openshell gateway start --remote @.local $ openshell status ``` -Once `openshell status` shows the gateway as healthy, all subsequent commands route through the SSH tunnel. +After `openshell status` shows the gateway as healthy, all subsequent commands route through the SSH tunnel. :::: @@ -90,6 +92,9 @@ Choose the tab that matches your agent: ::::{tab-set} :::{tab-item} Claude Code + +Run the following command to create a sandbox with Claude Code: + ```console $ openshell sandbox create -- claude ``` @@ -98,22 +103,31 @@ The CLI prompts you to create a provider from local credentials — type `yes` t ::: :::{tab-item} OpenCode + +Run the following command to create a sandbox with OpenCode: + ```console $ openshell sandbox create -- opencode ``` -The CLI prompts you to create a provider from local credentials — type `yes` to continue. If `OPENAI_API_KEY` or `OPENROUTER_API_KEY` is set in your environment, it is picked up automatically. If not, you can configure it from inside the sandbox after it launches. +The CLI prompts you to create a provider from local credentials. Type `yes` to continue. If `OPENAI_API_KEY` or `OPENROUTER_API_KEY` is set in your environment, it is picked up automatically. If not, you can configure it from inside the sandbox after it launches. ::: :::{tab-item} Codex + +Run the following command to create a sandbox with Codex: + ```console $ openshell sandbox create -- codex ``` -The CLI prompts you to create a provider from local credentials — type `yes` to continue. If `OPENAI_API_KEY` is set in your environment, it is picked up automatically. If not, you can configure it from inside the sandbox after it launches. +The CLI prompts you to create a provider from local credentials. Type `yes` to continue. If `OPENAI_API_KEY` is set in your environment, it is picked up automatically. If not, you can configure it from inside the sandbox after it launches. ::: -:::{tab-item} Community Sandbox +:::{tab-item} OpenClaw + +Run the following command to create a sandbox with OpenClaw: + ```console $ openshell sandbox create --from openclaw ``` @@ -121,12 +135,12 @@ $ openshell sandbox create --from openclaw The `--from` flag pulls a pre-built sandbox definition from the [OpenShell Community](https://github.com/NVIDIA/OpenShell-Community) catalog. Each definition bundles a container image, a tailored policy, and optional skills into a single package. ::: -:::: +:::{tab-item} Community Sandbox -## Next Steps +You can use the `--from` flag to pull other OpenShell sandbox images from the [NVIDIA Container Registry](https://registry.nvidia.com/). For example, to pull the `base` image, run the following command: -You now have a working sandbox! From here, you can: +```console +$ openshell sandbox create --from base +``` -- **Follow a guided tutorial** — set up scoped GitHub repo access in {doc}`/tutorials/github-sandbox`. -- **Learn how sandboxes work** — see {doc}`/sandboxes/create-and-manage` for the full lifecycle. -- **Write your own policies** — see {doc}`/sandboxes/policies` for custom access rules. +::: diff --git a/docs/index.md b/docs/index.md index 4e65ae53..8b3b7e03 100644 --- a/docs/index.md +++ b/docs/index.md @@ -28,7 +28,7 @@ content: [![License](https://img.shields.io/badge/License-Apache_2.0-blue)](https://github.com/NVIDIA/OpenShell/blob/main/LICENSE) [![PyPI](https://img.shields.io/badge/PyPI-openshell-orange?logo=pypi)](https://pypi.org/project/openshell/) -OpenShell is the safe, private runtime for autonomous AI agents. It provides sandboxed execution environments +NVIDIA OpenShell is the safe, private runtime for autonomous AI agents. It provides sandboxed execution environments that protect your data, credentials, and infrastructure. Agents run with exactly the permissions they need and nothing more, governed by declarative policies that prevent unauthorized file access, data exfiltration, and uncontrolled network activity. @@ -70,13 +70,15 @@ Install the CLI and create your first sandbox in two commands. grid-area: 1 / 1; white-space: nowrap; opacity: 0; - animation: nc-cycle 6s ease-in-out infinite; + animation: nc-cycle 12s ease-in-out infinite; } .nc-swap > span:nth-child(2) { animation-delay: 3s; } +.nc-swap > span:nth-child(3) { animation-delay: 6s; } +.nc-swap > span:nth-child(4) { animation-delay: 9s; } @keyframes nc-cycle { - 0%, 5% { opacity: 0; } - 10%, 42% { opacity: 1; } - 50%, 100% { opacity: 0; } + 0%, 3% { opacity: 0; } + 5%, 20% { opacity: 1; } + 25%, 100% { opacity: 0; } } .nc-hl { color: #76b900; font-weight: 600; } .nc-cursor { @@ -98,12 +100,12 @@ Install the CLI and create your first sandbox in two commands.
$ uv pip install openshell
-
$ openshell sandbox create -- claude--from openclaw
+
$ openshell sandbox create -- claude--from openclaw-- opencode-- codex
``` -Refer to the [Quickstart](about/get-started.md) for more details. +Refer to the [Quickstart](get-started/quickstart.md) for more details. --- @@ -123,7 +125,7 @@ Learn about OpenShell and its capabilities. ::: :::{grid-item-card} Quickstart -:link: about/get-started +:link: get-started/quickstart :link-type: doc Install the CLI and create your first sandbox in two commands. @@ -132,8 +134,8 @@ Install the CLI and create your first sandbox in two commands. {bdg-secondary}`Tutorial` ::: -:::{grid-item-card} Tutorials -:link: tutorials/index +:::{grid-item-card} Set Up a Sandbox with GitHub Repo Access +:link: tutorials/github-sandbox :link-type: doc End-to-end guides: GitHub repo access, custom policies, and more. @@ -193,8 +195,8 @@ Release Notes :caption: Get Started :hidden: -Quickstart -tutorials/index +Quickstart +GitHub Sandbox ``` ```{toctree} @@ -223,6 +225,7 @@ inference/configure reference/cli reference/default-policy reference/policy-schema +reference/support-matrix ``` ```{toctree} @@ -231,4 +234,3 @@ reference/policy-schema resources/eula ``` - diff --git a/docs/inference/configure.md b/docs/inference/configure.md index 121ca51b..673b2a0a 100644 --- a/docs/inference/configure.md +++ b/docs/inference/configure.md @@ -5,7 +5,7 @@ # Configure Inference Routing -This page covers the managed local inference endpoint (`https://inference.local`). External inference endpoints go through sandbox `network_policies` — see [Network Access Rules](/sandboxes/index.md#network-access-rules) for details. +This page covers the managed local inference endpoint (`https://inference.local`). External inference endpoints go through sandbox `network_policies` — refer to [Network Access Rules](/sandboxes/index.md#network-access-rules) for details. The configuration consists of two values: @@ -68,6 +68,8 @@ $ openshell inference set \ ## Step 3: Verify the Active Config +Confirm that the provider and model are set correctly: + ```console $ openshell inference get provider: nvidia-prod @@ -91,7 +93,7 @@ $ openshell inference update --provider openai-prod ## Use It from a Sandbox -Once inference is configured, code inside any sandbox can call `https://inference.local` directly: +After inference is configured, code inside any sandbox can call `https://inference.local` directly: ```python from openai import OpenAI @@ -130,7 +132,9 @@ A successful response confirms the privacy router can reach the configured backe ## Next Steps -- **How does inference routing work?** See {doc}`index` for the interception flow and supported API patterns. -- **Need to control external endpoints?** See [Network Access Rules](/sandboxes/index.md#network-access-rules). -- **Managing provider records?** See {doc}`../sandboxes/providers`. -- **CLI reference?** See {doc}`../reference/cli` for `openshell inference` commands. +Explore related topics: + +- To understand the inference routing flow and supported API patterns, refer to {doc}`index`. +- To control external endpoints, refer to [Network Access Rules](/sandboxes/index.md#network-access-rules). +- To manage provider records, refer to {doc}`../sandboxes/providers`. +- To view `openshell inference` commands, refer to {doc}`../reference/cli`. diff --git a/docs/inference/index.md b/docs/inference/index.md index 531cdf4f..4ed4553e 100644 --- a/docs/inference/index.md +++ b/docs/inference/index.md @@ -9,7 +9,7 @@ OpenShell handles inference in two ways: | Path | How It Works | |---|---| -| **External endpoints** | Traffic to hosts like `api.openai.com` or `api.anthropic.com` is treated like any other outbound request — allowed or denied by `network_policies`. See [Network Access Rules](/sandboxes/index.md#network-access-rules). | +| **External endpoints** | Traffic to hosts like `api.openai.com` or `api.anthropic.com` is treated like any other outbound request — allowed or denied by `network_policies`. Refer to [Network Access Rules](/sandboxes/index.md#network-access-rules). | | **`inference.local`** | A special endpoint exposed inside every sandbox for inference that should stay local to the host for privacy and security. The {doc}`privacy router ` strips the original credentials, injects the configured backend credentials, and forwards to the managed model endpoint. | ## How `inference.local` Works @@ -57,5 +57,7 @@ Requests to `inference.local` that do not match the configured provider's suppor ## Next Steps -- **Ready to configure?** Set up the backend behind `inference.local` in {doc}`configure`. -- **Need to control external endpoints?** See [Network Access Rules](/sandboxes/index.md#network-access-rules). +Continue with one of the following: + +- To set up the backend behind `inference.local`, refer to {doc}`configure`. +- To control external endpoints, refer to [Network Access Rules](/sandboxes/index.md#network-access-rules). diff --git a/docs/reference/cli.md b/docs/reference/cli.md index 345bbee7..691c6e4c 100644 --- a/docs/reference/cli.md +++ b/docs/reference/cli.md @@ -9,6 +9,8 @@ Complete command reference for the `openshell` CLI. Every subcommand, flag, and ## Command Tree +The full hierarchy of `openshell` subcommands: + ```text openshell ├── status @@ -23,6 +25,7 @@ openshell │ ├── stop │ ├── destroy │ ├── info +│ ├── add │ ├── tunnel │ └── select [name] ├── sandbox @@ -57,6 +60,8 @@ Commands that accept an optional `[name]` argument — such as `get`, `connect`, ## Status, Logs, and Terminal +Check gateway health, stream sandbox logs, and launch the terminal dashboard: + | Command | Description | |---|---| | `openshell status` | Show the health and status of the active gateway. | @@ -75,6 +80,7 @@ Manage the OpenShell runtime cluster. | `openshell gateway stop` | Stop the active cluster, preserving state. | | `openshell gateway destroy` | Permanently remove the cluster and all its data. | | `openshell gateway info` | Show detailed information about the cluster. | +| `openshell gateway add ` | Register an existing remote gateway by URL. | | `openshell gateway tunnel` | Set up a kubectl tunnel to a remote cluster. | | `openshell gateway select ` | Set the active cluster. All subsequent commands target this cluster. | | `openshell gateway select` | List all registered clusters (when called without a name). | @@ -85,7 +91,7 @@ Create and manage isolated agent execution environments. | Command | Description | |---|---| -| `openshell sandbox create` | Create a new sandbox. See flag reference below. | +| `openshell sandbox create` | Create a new sandbox. Refer to the flag reference below. | | `openshell sandbox get [name]` | Show detailed information about a sandbox. | | `openshell sandbox list` | List all sandboxes in the active cluster. | | `openshell sandbox delete ` | Delete one or more sandboxes by name. | @@ -96,6 +102,8 @@ Create and manage isolated agent execution environments. ### Sandbox Create Flags +The following flags control sandbox creation: + | Flag | Description | |---|---| | `--name` | Assign a human-readable name to the sandbox. Auto-generated if omitted. | @@ -133,7 +141,7 @@ Manage credential providers that inject secrets into sandboxes. | Command | Description | |---|---| -| `openshell provider create` | Create a new credential provider. See flag reference below. | +| `openshell provider create` | Create a new credential provider. Refer to the flag reference below. | | `openshell provider get ` | Show details of a provider. | | `openshell provider list` | List all providers in the active cluster. | | `openshell provider update ` | Update a provider's credentials or configuration. | @@ -141,6 +149,8 @@ Manage credential providers that inject secrets into sandboxes. ### Provider Create Flags +The following flags control provider creation: + | Flag | Description | |---|---| | `--name` | Name for the provider. | @@ -177,6 +187,8 @@ Show the current inference configuration, including provider, model, and version ## Environment Variables +The following environment variables override CLI defaults: + | Variable | Description | |---|---| | `OPENSHELL_CLUSTER` | Name of the cluster to operate on. Overrides the active cluster set by `openshell gateway select`. | diff --git a/docs/reference/default-policy.md b/docs/reference/default-policy.md index 5b476242..94c4a0ec 100644 --- a/docs/reference/default-policy.md +++ b/docs/reference/default-policy.md @@ -1,3 +1,17 @@ +--- +title: + page: "Default Policy Reference" + nav: "Default Policy" +description: "Breakdown of the built-in default policy applied when you create an OpenShell sandbox without a custom policy." +keywords: ["openshell default policy", "sandbox policy", "agent compatibility"] +topics: ["generative_ai", "cybersecurity"] +tags: ["ai_agents", "sandboxing", "security", "policy"] +content: + type: reference + difficulty: technical_beginner + audience: [engineer, data_scientist] +--- + # Default Policy Reference The default policy is the policy applied when you create an OpenShell sandbox without `--policy`. It is defined in the [`deploy/docker/sandbox/dev-sandbox-policy.yaml`](https://github.com/NVIDIA/OpenShell/blob/main/deploy/docker/sandbox/dev-sandbox-policy.yaml) file. diff --git a/docs/reference/policy-schema.md b/docs/reference/policy-schema.md index 2f388ed1..1def55ed 100644 --- a/docs/reference/policy-schema.md +++ b/docs/reference/policy-schema.md @@ -9,6 +9,8 @@ Complete field reference for the sandbox policy YAML. Each field is documented w ## Top-Level Structure +A policy YAML file contains the following top-level fields: + ```yaml version: 1 filesystem_policy: { ... } @@ -29,6 +31,8 @@ Static fields are set at sandbox creation time. Changing them requires destroyin ## Version +The version field identifies which schema the policy uses: + | Field | Type | Required | Description | |---|---|---|---| | `version` | integer | Yes | Schema version number. Currently must be `1`. | @@ -118,6 +122,8 @@ A map of named network policy entries. Each entry declares a set of endpoints an ### Network Policy Entry +Each entry in the `network_policies` map has the following fields: + | Field | Type | Required | Description | |---|---|---|---| | `name` | string | No | Display name for the policy entry. Used in log output. Defaults to the map key. | @@ -140,6 +146,8 @@ Each endpoint defines a reachable destination and optional inspection rules. #### Access Levels +The `access` field accepts one of the following values: + | Value | Allowed HTTP Methods | |---|---| | `full` | All methods and paths. | @@ -177,6 +185,8 @@ Identifies an executable that is permitted to use the associated endpoints. ### Full Example +The following policy grants read-only GitHub API access and npm registry access: + ```yaml network_policies: github_rest_api: diff --git a/docs/reference/support-matrix.md b/docs/reference/support-matrix.md new file mode 100644 index 00000000..71fad0b0 --- /dev/null +++ b/docs/reference/support-matrix.md @@ -0,0 +1,80 @@ + + +# Support Matrix + +This page lists the platform, software, runtime, and kernel requirements for running OpenShell. + +## Supported Platforms + +OpenShell publishes multi-architecture container images for `linux/amd64` and `linux/arm64`. The CLI is supported on the following host platforms: + +| Platform | Architecture | Status | +|---|---|---| +| Linux (Debian/Ubuntu) | x86_64 (amd64) | Supported | +| Linux (Debian/Ubuntu) | aarch64 (arm64) | Supported | +| macOS (Docker Desktop) | Apple Silicon (arm64) | Supported | +| macOS (Docker Desktop) | Intel (amd64) | Supported | +| Windows (WSL 2 + Docker Desktop) | x86_64 | Untested | + +## Software Prerequisites + +The following software must be installed on the host before using the OpenShell CLI: + +| Component | Minimum Version | Notes | +|---|---|---| +| Python | 3.12 | Python 3.12 and 3.13 are supported. | +| [uv](https://docs.astral.sh/uv/) | 0.9 | Used to install the CLI (`uv pip install openshell`). | +| Docker Desktop or Docker Engine | — | Must be running before any `openshell` command. No minimum version is enforced. | + +## Sandbox Runtime Versions + +The base sandbox container image ships the following components. These versions apply to sandboxes created with the default image (`ghcr.io/nvidia/openshell/sandbox`). + +| Component | Version | +|---|---| +| Base OS | Debian Bookworm | +| Python | 3.12.13 | +| Node.js | 22.22.1 | +| npm | 11.11.0 | +| uv | 0.10.8 | +| Claude Code | Latest (installed at image build time) | +| OpenCode | 1.2.18 | +| Codex | 0.111.0 | + +## Container Images + +OpenShell uses several container images that are pulled automatically during gateway startup and sandbox creation. All images are published for `linux/amd64` and `linux/arm64`. + +| Image | Registry | Reference | Pulled When | +|---|---|---|---| +| Cluster | ghcr.io | `ghcr.io/nvidia/openshell/cluster:latest` | `openshell gateway start` | +| Server | ghcr.io | `ghcr.io/nvidia/openshell/server:latest` | Cluster startup (via Helm chart) | +| Sandbox | ghcr.io | `ghcr.io/nvidia/openshell/sandbox:latest` | First sandbox creation (via Helm chart) | +| Community sandboxes | CloudFront CDN | `d1i0nduu2f6qxk.cloudfront.net/openshell-community/sandboxes/{name}:latest` | `openshell sandbox create --from ` | + +The cluster image is based on `rancher/k3s:v1.35.2-k3s1` and bundles the Helm charts and Kubernetes manifests required to bootstrap the control plane. The server and sandbox images are pulled separately at runtime. + +To override the default image references, set the following environment variables: + +| Variable | Purpose | +|---|---| +| `OPENSHELL_CLUSTER_IMAGE` | Override the cluster image reference. | +| `OPENSHELL_COMMUNITY_REGISTRY` | Override the registry for community sandbox images. | + +## Kernel Requirements + +OpenShell enforces sandbox isolation through two Linux kernel security modules: + +| Module | Requirement | Details | +|---|---|---| +| [Landlock LSM](https://docs.kernel.org/security/landlock.html) | Recommended | Enforces filesystem access restrictions at the kernel level. The `best_effort` compatibility mode uses the highest Landlock ABI the host kernel supports. The `hard_requirement` mode fails sandbox creation if the required ABI is unavailable. | +| seccomp | Required | Filters dangerous system calls. Available on all modern Linux kernels (3.17+). | + +On macOS, these kernel modules run inside the Docker Desktop Linux VM, not on the host kernel. + +## Agent Compatibility + +For the full list of supported agents and their default policy coverage, refer to the [Supported Agents](../sandboxes/index.md#supported-agents) table. diff --git a/docs/sandboxes/community-sandboxes.md b/docs/sandboxes/community-sandboxes.md index 3c09ff9c..4a979de4 100644 --- a/docs/sandboxes/community-sandboxes.md +++ b/docs/sandboxes/community-sandboxes.md @@ -90,5 +90,7 @@ or anything else), consider contributing it back so others can use it. ## Next Steps +Explore related topics: + - **Need to supply API keys or tokens?** Set up {doc}`providers` for credential management. - **Want to customize the sandbox policy?** Write custom rules in {doc}`policies`. diff --git a/docs/sandboxes/create-and-manage.md b/docs/sandboxes/create-and-manage.md index 4b21a8a8..824e7cb5 100644 --- a/docs/sandboxes/create-and-manage.md +++ b/docs/sandboxes/create-and-manage.md @@ -8,18 +8,20 @@ This page walks you through the full sandbox lifecycle: creating, inspecting, connecting to, monitoring, and deleting sandboxes. For background on what sandboxes are and how the runtime works, refer to [About Sandboxes](index.md). :::{warning} -Docker must be running before you create a sandbox. If it isn't, the CLI +Docker must be running before you create a sandbox. If it is not, the CLI returns a connection-refused error (`os error 61`) without explaining the cause. Start Docker and try again. ::: ## Create a Sandbox +Run a single command to create a sandbox and launch your agent: + ```console $ openshell sandbox create -- claude ``` -If you have an existing gateway, a sandbox will be created within that gateway or if you don't have one, one will be created for you. +If you have an existing gateway, the sandbox is created in it. Otherwise, a gateway is created automatically. A fully specified creation command might look like: @@ -104,7 +106,7 @@ Use flags to filter and follow output: | `--level` | Filter by severity | `--level warn` | | `--since` | Show logs from a time window | `--since 5m` | -## Monitor your Sandbox +## Monitor Your Sandbox OpenShell Terminal is a real-time dashboard that combines sandbox status and live logs in a single view. @@ -112,10 +114,10 @@ OpenShell Terminal is a real-time dashboard that combines sandbox status and liv $ openshell term ``` -The dashboard shows: +The dashboard shows the following information. -- **Sandbox status** — name, phase, image, attached providers, age, and active port forwards. -- **Live log stream** — outbound connections, policy decisions, and inference interceptions as they happen. Logs are labeled by source: `sandbox` (proxy and policy events) or `gateway` (lifecycle events). +- **Sandbox status**: Name, phase, image, attached providers, age, and active port forwards. +- **Live log stream**: Omutbound connections, policy decisions, and inference interceptions as they happen. Logs are labeled by source: `sandbox` (proxy and policy events) or `gateway` (lifecycle events). Use the terminal to spot blocked connections (`action=deny` entries) and inference interceptions (`action=inspect_for_inference` entries). If a connection is blocked unexpectedly, add the host to your network policy — refer to {doc}`policies` for the workflow. @@ -153,7 +155,9 @@ $ openshell sandbox delete my-sandbox ## Next Steps -- **Want a complete end-to-end example?** Follow the {doc}`/tutorials/github-sandbox` tutorial. -- **Need to supply API keys or tokens?** Set up {doc}`providers` for credential management. -- **Want to control what the agent can access?** Write a custom policy in {doc}`policies`. -- **Want a pre-built environment?** Browse the {doc}`community-sandboxes` catalog. \ No newline at end of file +Explore related topics: + +- To follow a complete end-to-end example, refer to the {doc}`/tutorials/github-sandbox` tutorial. +- To supply API keys or tokens, refer to {doc}`providers`. +- To control what the agent can access, refer to {doc}`policies`. +- To use a pre-built environment, refer to the {doc}`community-sandboxes` catalog. \ No newline at end of file diff --git a/docs/sandboxes/index.md b/docs/sandboxes/index.md index 5861a46d..248ec162 100644 --- a/docs/sandboxes/index.md +++ b/docs/sandboxes/index.md @@ -18,6 +18,19 @@ Every sandbox moves through a defined set of phases: | Error | Something went wrong during provisioning or execution. Check logs with `openshell logs` for details. | | Deleting | The sandbox is being torn down. The system releases resources and purges credentials. | +## Supported Agents + +The following table summarizes the agents that run in OpenShell sandboxes. Built-in agents are pre-installed in the OpenShell base sandbox image and auto-configured when passed as the trailing command to `openshell sandbox create`. More community agent sandboxes are available in the {doc}`community-sandboxes` catalog. + +| Agent | Source | Default Policy | Notes | +|---|---|---|---| +| [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | Built-in | Full coverage | Works out of the box. Requires `ANTHROPIC_API_KEY`. | +| [OpenCode](https://opencode.ai/) | Built-in | Partial coverage | Pre-installed. Add `opencode.ai` endpoint and OpenCode binary paths to the policy for full functionality. | +| [Codex](https://developers.openai.com/codex) | Built-in | No coverage | Pre-installed. Requires a custom policy with OpenAI endpoints and Codex binary paths. Requires `OPENAI_API_KEY`. | +| [OpenClaw](https://openclaw.ai/) | [OpenShell Community](https://github.com/NVIDIA/OpenShell-Community/tree/main/sandboxes/openclaw) | Bundled | Agent orchestration layer. Launch with `openshell sandbox create --from openclaw`. | + + + ## Built-in Default Policy OpenShell ships a built-in policy that covers common agent workflows out of the box. @@ -29,7 +42,7 @@ When you create a sandbox without `--policy`, the default policy is applied. It | Network | What the agent can reach on the network | Each policy block pairs allowed destinations (host and port) with allowed binaries (executable paths). The proxy matches every outbound connection to the binary that opened it. Both must match or the connection is denied. | | Process | What privileges the agent has | The agent runs as an unprivileged user with seccomp filters that block dangerous system calls. No `sudo`, no `setuid`, no path to elevated privileges. | -For the full breakdown of each default policy block and agent compatibility details, see {doc}`../reference/default-policy`. +For the full breakdown of each default policy block and agent compatibility details, refer to {doc}`../reference/default-policy`. ## Policy Structure @@ -71,22 +84,24 @@ inference: allowed_routes: [local] ``` -For the complete structure and every field, see the [Policy Schema Reference](../reference/policy-schema.md). +For the complete structure and every field, refer to the [Policy Schema Reference](../reference/policy-schema.md). ## Network Access Rules -Network access is controlled by policy blocks under `network_policies`. Each block has a **name**, a list of **endpoints** (host, port, protocol, and optional rules), and a list of **binaries** that are allowed to use those endpoints. +Network access is controlled by policy blocks under `network_policies`. Each block has a name, a list of endpoints (host, port, protocol, and optional rules), and a list of binaries that are allowed to use those endpoints. Every outbound connection from the sandbox goes through the proxy: -- The proxy queries the {doc}`policy engine <../about/architecture>` with the **destination** (host and port) and the **calling binary**. A connection is allowed only when both match an entry in the same policy block. +- The proxy queries the {doc}`policy engine <../about/architecture>` with the destination (host and port) and the calling binary. A connection is allowed only when both match an entry in the same policy block. - For endpoints with `protocol: rest` and `tls: terminate`, each HTTP request is checked against that endpoint's `rules` (method and path). - If no endpoint matches and inference routes are configured, the request may be rerouted for inference. - Otherwise the connection is denied. Endpoints without `protocol` or `tls` allow the TCP stream through without inspecting payloads. ## Next Steps -- **Ready to create your first sandbox?** Start with {doc}`create-and-manage`. -- **Need to supply API keys or tokens?** Set up {doc}`providers` before creating. -- **Want to control what the agent can access?** Write a custom policy in {doc}`policies`. -- **Want a pre-built environment?** Browse the {doc}`community-sandboxes` catalog. +Continue with one of the following: + +- To create your first sandbox, refer to {doc}`create-and-manage`. +- To supply API keys or tokens, refer to {doc}`providers`. +- To control what the agent can access, refer to {doc}`policies`. +- To use a pre-built environment, refer to the {doc}`community-sandboxes` catalog. diff --git a/docs/sandboxes/policies.md b/docs/sandboxes/policies.md index 02530c3d..9b799561 100644 --- a/docs/sandboxes/policies.md +++ b/docs/sandboxes/policies.md @@ -53,7 +53,7 @@ The following steps outline the hot-reload policy update workflow. 1. Create the sandbox with your initial policy by following [Quick Start: Apply a Custom Policy](#quick-start-apply-a-custom-policy) above (or set `OPENSHELL_SANDBOX_POLICY`). -2. Monitor denials — each log entry shows host, port, binary, and reason. Alternatively use `openshell term` for a live dashboard. +2. Monitor denials. Each log entry shows host, port, binary, and reason. Alternatively, use `openshell term` for a live dashboard. ```console $ openshell logs --tail --source sandbox @@ -121,7 +121,7 @@ Endpoints without `protocol` or `tls` use TCP passthrough — the proxy allows t Allow Claude and the GitHub CLI to reach `api.github.com` with per-path rules: read-only (GET, HEAD, OPTIONS) and GraphQL (POST) for all paths; full write access for `alpha-repo`; and create/edit issues only for `bravo-repo`. Replace `` with your GitHub org or username. :::{tip} -For an end-to-end walkthrough that combines this policy with a GitHub credential provider and sandbox creation, see {doc}`/tutorials/github-sandbox`. +For an end-to-end walkthrough that combines this policy with a GitHub credential provider and sandbox creation, refer to {doc}`/tutorials/github-sandbox`. ::: ```yaml @@ -144,8 +144,8 @@ For an end-to-end walkthrough that combines this policy with a GitHub credential method: OPTIONS path: "/**" - allow: - method: POST - path: "/graphql" + method: POST + path: "/graphql" - allow: method: "*" path: "/repos//alpha-repo/**" @@ -167,6 +167,8 @@ Endpoints with `protocol: rest` and `tls: terminate` enable HTTP request inspect ## Next Steps -- **New to policies?** Read about {doc}`policy structure and network access rules ` first. -- **Need the full field reference?** See the [Policy Schema Reference](../reference/policy-schema.md). -- **Looking for the default policy breakdown?** See {doc}`../reference/default-policy`. +Explore related topics: + +- To learn about policy structure and network access rules, refer to {doc}`index`. +- To view the full field-by-field YAML definition, refer to the [Policy Schema Reference](../reference/policy-schema.md). +- To review the default policy breakdown, refer to {doc}`../reference/default-policy`. diff --git a/docs/sandboxes/providers.md b/docs/sandboxes/providers.md index b4c812a8..66d1fad8 100644 --- a/docs/sandboxes/providers.md +++ b/docs/sandboxes/providers.md @@ -111,7 +111,7 @@ The following provider types are supported. | `claude` | `ANTHROPIC_API_KEY`, `CLAUDE_API_KEY` | Claude Code, Anthropic API | | `codex` | `OPENAI_API_KEY` | OpenAI Codex | | `opencode` | `OPENCODE_API_KEY`, `OPENROUTER_API_KEY`, `OPENAI_API_KEY` | opencode tool | -| `github` | `GITHUB_TOKEN`, `GH_TOKEN` | GitHub API, `gh` CLI — see {doc}`/tutorials/github-sandbox` | +| `github` | `GITHUB_TOKEN`, `GH_TOKEN` | GitHub API, `gh` CLI — refer to {doc}`/tutorials/github-sandbox` | | `gitlab` | `GITLAB_TOKEN`, `GLAB_TOKEN`, `CI_JOB_TOKEN` | GitLab API, `glab` CLI | | `nvidia` | `NVIDIA_API_KEY` | NVIDIA API Catalog | | `generic` | User-defined | Any service with custom credentials | @@ -124,6 +124,8 @@ environment variable names and values yourself with `--credential`. ## Next Steps -- **Want to control what the agent can access?** Write a custom policy in {doc}`policies`. -- **Looking for a pre-built environment?** Browse the {doc}`community-sandboxes` catalog. -- [Policy Schema Reference](../reference/policy-schema.md): Complete field reference for the policy YAML. \ No newline at end of file +Explore related topics: + +- To control what the agent can access, refer to {doc}`policies`. +- To use a pre-built environment, refer to the {doc}`community-sandboxes` catalog. +- To view the complete field reference for the policy YAML, refer to the [Policy Schema Reference](../reference/policy-schema.md). \ No newline at end of file diff --git a/docs/tutorials/github-sandbox.md b/docs/tutorials/github-sandbox.md index 2aa39db9..a5ab9516 100644 --- a/docs/tutorials/github-sandbox.md +++ b/docs/tutorials/github-sandbox.md @@ -5,57 +5,61 @@ # Set Up a Sandbox with GitHub Repo Access -Agents often need to work across multiple repositories with different levels of trust. An agent might need full read-write access to a feature repo where it commits code, but only read access to a shared library repo that it references without modifying. OpenShell policies let you express this distinction — the agent can clone and push to one repo while treating another as a read-only dependency. +This tutorial walks through configuring a sandbox that grants different access levels to two GitHub repositories and enforces these rules at the network layer. The sandbox runs Claude Code as the agent. -This tutorial sets up exactly that scenario: +The tutorial uses the following two example repositories for illustration purposes. -- **alpha-repo** — the agent's working repo. Full read-write access: clone, push, create PRs and issues. -- **bravo-repo** — a reference repo. Read-only access: clone and browse, but push and write API calls are denied. +- A `alpha-repo` repository with read-write access. The agent can clone, push, and call mutating GitHub API endpoints such as pull requests, issues, and comments. +- A `bravo-repo` repository with read-only access. The agent can clone and fetch, but push operations and mutating API calls are denied. +- All other GitHub repositories are denied by default. No clone, fetch, or API call to an unlisted repository is allowed. -Access is locked to these two repos. The agent cannot clone, fetch, or call the API for any other repository on GitHub. +After completing this tutorial, the sandbox environment includes the following: -By the end you will have: - -- A GitHub credential provider injecting your token into the sandbox -- A policy that extends the default with scoped GitHub access to exactly two repos -- A running sandbox where Claude Code, OpenCode, and the `gh` CLI can all interact with GitHub +- A GitHub credential provider that injects your GitHub token into the sandbox at runtime. +- A network policy that extends the default policy with per-repository GitHub access rules. +- A running sandbox in which Claude Code operates under the defined access constraints. ## Prerequisites -Before you begin, make sure you have: +This tutorial requires the following: + +- Completed the {doc}`Quickstart ` tutorial. +- A GitHub personal access token (PAT) with `repo` scope, exported as `GITHUB_TOKEN`. +- An agent API key configured in the environment. For example, `ANTHROPIC_API_KEY` for Claude Code. -- Completed the {doc}`Quickstart ` (CLI installed, Docker running) -- A GitHub personal access token (PAT) with `repo` scope, exported as `GITHUB_TOKEN` -- Your agent's API key set (e.g., `ANTHROPIC_API_KEY` for Claude Code) +## Create a GitHub Provider -## Step 1: Create a GitHub Provider +In this section, you learn how to create a GitHub provider that injects your token into the sandbox at runtime. :::{admonition} Already have a sandbox running? :class: tip -If you followed the Quickstart and already have a sandbox without a GitHub provider, you have two options: +If you completed the Quickstart tutorial and have the default sandbox without a GitHub provider, there are two options to add the provider. -1. **Add a provider to a new sandbox** — delete the existing sandbox, create the provider below, and recreate the sandbox with `--provider my-github` in Step 3. -2. **Set the token inside the sandbox** — connect with `openshell sandbox connect ` and run `export GITHUB_TOKEN=`. This skips the provider workflow but the token is not persisted across sandbox recreations. +- **Option 1**: Recreate with a provider. Delete the existing sandbox, create the provider below, then recreate the sandbox with `--provider my-github`. +- **Option 2**: Inject the token manually. Connect with `openshell sandbox connect ` and run `export GITHUB_TOKEN=`. This bypasses the provider workflow. Note that the token does not persist across sandbox recreations. ::: -Create a provider that reads your GitHub token from the environment: +Create a provider that sources your GitHub token from the host environment: ```console $ openshell provider create --name my-github --type github --from-existing ``` -This reads `GITHUB_TOKEN` (and `GH_TOKEN` if set) from your shell and stores them in the provider. The sandbox receives these as environment variables at runtime. +This command reads `GITHUB_TOKEN` (and `GH_TOKEN` if set) from the current shell session and stores them in the provider configuration. At sandbox startup, the provider injects these values as environment variables into the container. -For more on provider types, see {doc}`/sandboxes/providers`. +For additional provider types, refer to {doc}`/sandboxes/providers`. -## Step 2: Write the Policy +## Write the Policy -Create a file called `github-policy.yaml`. This policy starts from the {doc}`default policy ` and replaces the GitHub blocks with scoped rules that grant read-write access to `alpha-repo` and read-only access to `bravo-repo`. +In this section, you learn how to write a policy that extends the default policy with per-repository GitHub access rules. -Replace `` throughout with your GitHub organization or username. +Run the following command to create a file named `github-policy.yaml` with policy blocks. This policy extends the {doc}`default policy ` and overrides the GitHub network blocks with per-repository rules. The `alpha-repo` receives read-write access, the `bravo-repo` receives read-only access, and all other repositories are denied by default. -```yaml +Replace every occurrence of `` with your GitHub organization or username. + +```console +$ cat << 'EOF' > github-policy.yaml version: 1 # ── Static (locked at sandbox creation) ────────────────────────── @@ -211,22 +215,23 @@ network_policies: - { path: /usr/bin/wget } - { path: "/sandbox/.vscode-server/**" } - { path: "/sandbox/.vscode-remote-containers/**" } +EOF ``` -**What the GitHub blocks do:** +The following table summarizes the behavior of the GitHub policy blocks. -| Block | Endpoint | Access | +| Block | Endpoint | Behavior | |---|---|---| -| `github_git` | `github.com:443` | Git Smart HTTP with TLS termination. Clone and fetch allowed for both repos. Push (`git-receive-pack`) allowed only for `alpha-repo`. All other repos are denied. | -| `github_api` | `api.github.com:443` | REST API with TLS termination. Full read-write for `alpha-repo`. Read-only (GET, HEAD, OPTIONS) for `bravo-repo`. All other repos are denied. | +| `github_git` | `github.com:443` | Git Smart HTTP protocol with TLS termination. Permits `info/refs` (clone/fetch) for both repositories. Permits `git-receive-pack` (push) for `alpha-repo` only. Denies all operations on unlisted repositories. | +| `github_api` | `api.github.com:443` | REST API with TLS termination. Permits all HTTP methods for `alpha-repo`. Restricts `bravo-repo` to GET, HEAD, and OPTIONS (read-only). Denies API access to unlisted repositories. | -The remaining blocks (`claude_code`, `nvidia_inference`, `pypi`, `vscode`) match the {doc}`default policy ` so the sandbox behaves the same as a standard sandbox for everything outside of GitHub. +The remaining blocks (`claude_code`, `nvidia_inference`, `pypi`, `vscode`) are identical to the {doc}`default policy `. Sandbox behavior outside of GitHub operations is unchanged. -For background on how network policy blocks work, see [Network Access Rules](/sandboxes/index.md#network-access-rules). +For details on network policy block structure, refer to [Network Access Rules](/sandboxes/index.md#network-access-rules). -## Step 3: Create the Sandbox +## Create the Sandbox -Create the sandbox with both the GitHub provider and your policy: +Run the following command to create the sandbox with the GitHub provider, the custom policy applied, and Claude Code running inside the sandbox: ```console $ openshell sandbox create \ @@ -236,54 +241,62 @@ $ openshell sandbox create \ -- claude ``` -The `--keep` flag keeps the sandbox running after Claude Code exits, so you can reconnect or iterate on the policy. +The `--keep` flag keeps the sandbox running after Claude Code exits. With this flag, you can reconnect to the same sandbox or apply policy updates without recreating the environment. -## Step 4: Verify Access +## Verify Access -Once Claude Code is running inside the sandbox, ask it to exercise both repos. The policy should allow writes to `alpha-repo` and block writes to `bravo-repo`. +With Claude Code running inside the sandbox, validate that the policy enforces the expected access levels for each repository. -**Test read-write access** — ask Claude to clone, commit, and push to `alpha-repo`: +### Verify Read-Write Access + +Instruct Claude to clone, commit, and push to `alpha-repo`: ```text Clone https://github.com//alpha-repo.git, add a blank line to the -README, commit, and push. +README.md file, commit, and push. ``` -Claude clones the repo, makes the edit, and pushes. The sandbox logs show `action=allow` for both `github.com` (git push) and `api.github.com` (any API calls Claude makes along the way). +The clone, commit, and push operations should complete successfully. Verify that the sandbox logs contain `action=allow` entries for `github.com` (the git push) and `api.github.com` (any associated API calls). + +### Verify Read-Only Enforcement -**Test read-only enforcement** — ask Claude to try the same thing with `bravo-repo`: +Instruct Claude to perform the same operations on `bravo-repo`: ```text Clone https://github.com//bravo-repo.git, add a blank line to the -README, commit, and push. +README.md file, commit, and push. ``` -Claude clones successfully (read is allowed), but the push fails. The proxy denies `git-receive-pack` for `bravo-repo` and Claude reports the error. You can confirm in the logs: +The clone operation succeeds because the policy permits read access. The push operation fails because the proxy denies `git-receive-pack` for `bravo-repo`. Verify the denial by inspecting the sandbox logs: ```console $ openshell logs --tail --source sandbox ``` -Look for an `action=deny` entry showing `host=github.com` and `path=//bravo-repo.git/git-receive-pack`. +The output contains an `action=deny` entry with `host=github.com` and `path=//bravo-repo.git/git-receive-pack`. + +### Verify API Scoping -**Test API scoping** — ask Claude to create an issue on each repo: +Instruct Claude to create a GitHub issue on each repository: ```text Create a GitHub issue titled "Test from sandbox" on /alpha-repo. Then try to create the same issue on /bravo-repo. ``` -The first issue is created. The second is denied — the policy only allows GET/HEAD/OPTIONS for `bravo-repo`, so the POST to create an issue is blocked. +Expected result is that the issue is created on `alpha-repo`. The request to `bravo-repo` is denied because the policy restricts that repository to GET, HEAD, and OPTIONS methods. The POST required to create an issue is blocked by the proxy. -## Step 5: Iterate on the Policy +## Iterate on the Policy -To grant access to additional repos or change access levels, edit `github-policy.yaml` and push the update to the running sandbox: +In this section, you learn how to iterate on the policy to modify repository access or add new repositories. + +Network policies support hot-reloading. To modify repository access or add new repositories, edit `github-policy.yaml` and run the following command to apply the updated policy to the running sandbox: ```console $ openshell policy set --policy github-policy.yaml --wait ``` -For example, to grant write access to `bravo-repo` as well, add another rule under `github_api`: +For example, to change the access level of `bravo-repo` from read-only to read-write, add the following rule under `github_api`: ```yaml - allow: @@ -291,7 +304,7 @@ For example, to grant write access to `bravo-repo` as well, add another rule und path: "/repos//bravo-repo/**" ``` -And add a push rule under `github_git`: +Then add the corresponding push rule under `github_git`: ```yaml - allow: @@ -299,10 +312,12 @@ And add a push rule under `github_git`: path: "//bravo-repo.git/git-receive-pack" ``` -For the full iterate workflow (pull current policy, edit, push, verify), see {doc}`/sandboxes/policies`. +For the complete policy iteration workflow (pull, edit, push, verify), refer to {doc}`/sandboxes/policies`. ## Next Steps -- **Need other credentials?** See {doc}`/sandboxes/providers` for all supported provider types. -- **Want finer policy control?** See {doc}`/sandboxes/policies` for more examples and the iterate workflow. -- **Looking for the full YAML reference?** See the [Policy Schema Reference](/reference/policy-schema.md). +The following resources cover related topics in greater depth: + +- To configure additional credential types, refer to {doc}`/sandboxes/providers`. +- To iterate on policy configuration, refer to {doc}`/sandboxes/policies`. +- To view the policy YAML specification, refer to the [Policy Schema Reference](/reference/policy-schema.md). diff --git a/docs/tutorials/index.md b/docs/tutorials/index.md deleted file mode 100644 index 5421ee61..00000000 --- a/docs/tutorials/index.md +++ /dev/null @@ -1,29 +0,0 @@ - - -# Tutorials - -Step-by-step guides that walk through complete workflows from start to finish. - -::::{grid} 1 1 2 2 -:gutter: 3 - -:::{grid-item-card} GitHub Repo Access -:link: github-sandbox -:link-type: doc - -Create a sandbox with scoped GitHub access — read-write to one repo, read-only to another. - -+++ -{bdg-secondary}`Sandbox` {bdg-secondary}`Policy` {bdg-secondary}`Provider` -::: - -:::: - -```{toctree} -:hidden: - -github-sandbox -```