From 777413101ea8ba912ea22de73672143e68898de4 Mon Sep 17 00:00:00 2001
From: pimlock <pimlock@users.noreply.github.com>
Date: Thu, 12 Mar 2026 23:38:45 +0000
Subject: [PATCH] =?UTF-8?q?Deploy=20preview=20for=20PR=20257=20?=
 =?UTF-8?q?=F0=9F=9B=AB?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 pr-preview/pr-257/about/architecture.html     |   2 +-
 pr-preview/pr-257/about/architecture.json     |   2 +-
 pr-preview/pr-257/about/overview.html         |   2 +-
 pr-preview/pr-257/about/overview.json         |   2 +-
 pr-preview/pr-257/about/release-notes.html    |   2 +-
 pr-preview/pr-257/about/release-notes.json    |   2 +-
 pr-preview/pr-257/get-started/quickstart.html |   2 +-
 pr-preview/pr-257/get-started/quickstart.json |   2 +-
 pr-preview/pr-257/index.html                  |   2 +-
 pr-preview/pr-257/index.json                  |   2 +-
 pr-preview/pr-257/inference/configure.html    |   2 +-
 pr-preview/pr-257/inference/configure.json    |   2 +-
 pr-preview/pr-257/inference/index.html        |   2 +-
 pr-preview/pr-257/inference/index.json        |   2 +-
 pr-preview/pr-257/reference/cli.html          |   2 +-
 pr-preview/pr-257/reference/cli.json          |   2 +-
 .../pr-257/reference/default-policy.html      |  31 ++-
 .../pr-257/reference/default-policy.json      |   2 +-
 .../pr-257/reference/policy-schema.html       |   2 +-
 .../pr-257/reference/policy-schema.json       |   2 +-
 .../pr-257/reference/support-matrix.html      |   2 +-
 .../pr-257/reference/support-matrix.json      |   2 +-
 pr-preview/pr-257/resources/eula.html         |   2 +-
 pr-preview/pr-257/resources/eula.json         |   2 +-
 .../pr-257/sandboxes/community-sandboxes.html |   2 +-
 .../pr-257/sandboxes/community-sandboxes.json |   2 +-
 .../pr-257/sandboxes/create-and-manage.html   |   2 +-
 .../pr-257/sandboxes/create-and-manage.json   |   2 +-
 pr-preview/pr-257/sandboxes/index.html        |   2 +-
 pr-preview/pr-257/sandboxes/index.json        |   2 +-
 pr-preview/pr-257/sandboxes/policies.html     |   2 +-
 pr-preview/pr-257/sandboxes/policies.json     |   2 +-
 pr-preview/pr-257/sandboxes/providers.html    |   2 +-
 pr-preview/pr-257/sandboxes/providers.json    |   2 +-
 pr-preview/pr-257/search.html                 |   2 +-
 pr-preview/pr-257/searchindex.js              |   2 +-
 .../pr-257/tutorials/github-sandbox.html      | 247 ++++++++++--------
 .../pr-257/tutorials/github-sandbox.json      |   2 +-
 38 files changed, 208 insertions(+), 142 deletions(-)

diff --git a/pr-preview/pr-257/about/architecture.html b/pr-preview/pr-257/about/architecture.html
index 203a58017..d8a8cac8f 100644
--- a/pr-preview/pr-257/about/architecture.html
+++ b/pr-preview/pr-257/about/architecture.html
@@ -387,7 +387,7 @@
 <p aria-level="2" class="caption" role="heading"><span class="caption-text">Get Started</span></p>
 <ul class="nav bd-sidenav">
 <li class="toctree-l1"><a class="reference internal" href="../get-started/quickstart.html">Quickstart</a></li>
-<li class="toctree-l1"><a class="reference internal" href="../tutorials/github-sandbox.html">Tutorial: GitHub Policy Iteration</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../tutorials/github-sandbox.html">GitHub Policy Tutorial</a></li>
 </ul>
 <p aria-level="2" class="caption" role="heading"><span class="caption-text">Sandboxes</span></p>
 <ul class="nav bd-sidenav">
diff --git a/pr-preview/pr-257/about/architecture.json b/pr-preview/pr-257/about/architecture.json
index 7e8c19c88..768524a90 100644
--- a/pr-preview/pr-257/about/architecture.json
+++ b/pr-preview/pr-257/about/architecture.json
@@ -1 +1 @@
-{"id":"about/architecture","title":"How OpenShell Works","url":"about/architecture.html","last_modified":"2026-03-12T09:12:26.557006+00:00","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.1.0"},"product":{"name":"OpenShell","version":"0.1.0"},"description":"OpenShell architecture overview covering the gateway, sandbox, policy engine, and privacy router.","tags":["AI Agents","Sandboxing","Security","Architecture"],"topics":["Generative AI","Cybersecurity"],"content_type":"concept","learning_level":"technical_beginner","audience":["engineer","data_scientist"],"content":"How OpenShell Works OpenShell runs as a K3s 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. 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. Sandbox Isolated runtime that includes container supervision and policy-enforced egress routing. Policy Engine Policy definition and enforcement layer for filesystem, network, and process constraints. Defense in depth enforces policies from the application layer down to infrastructure and kernel layers. Privacy Router Privacy-aware LLM routing layer that keeps sensitive context on sandbox compute and routes based on cost and privacy policy. How a Request Flows Every outbound connection from agent code passes through the same decision path: The agent process opens an outbound connection (API call, package install, git clone, and so on). The proxy inside the sandbox intercepts the connection and identifies which binary opened it. The proxy queries the policy engine with the destination, port, and calling binary. The policy engine returns one of three decisions: Allow — the destination and binary match a policy block. Traffic flows directly to the external service. Route for inference — no policy block matched, but inference routing is configured. The privacy router intercepts the request, strips the original credentials, injects the configured backend credentials, and forwards to the managed model endpoint. Deny — no match and no inference route. The connection is blocked and logged. For REST endpoints with TLS termination enabled, the proxy also decrypts TLS and checks each HTTP request against per-method, per-path rules before allowing it through. Deployment Modes 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. $ openshell gateway start --remote <username>@<spark-ssid>.local\nopenshell status\nNext Steps Continue with one of the following: To create your first sandbox, refer to the Quickstart . To learn how OpenShell enforces isolation across all protection layers, refer to Sandboxes","format":"text","summary":"OpenShell runs as a K3s 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.","headings":[{"text":"How OpenShell Works","level":1},{"text":"Components","level":2},{"text":"How a Request Flows","level":2},{"text":"Deployment Modes","level":2},{"text":"Next Steps","level":2}]}
\ No newline at end of file
+{"id":"about/architecture","title":"How OpenShell Works","url":"about/architecture.html","last_modified":"2026-03-12T23:38:42.336639+00:00","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.1.0"},"product":{"name":"OpenShell","version":"0.1.0"},"description":"OpenShell architecture overview covering the gateway, sandbox, policy engine, and privacy router.","tags":["AI Agents","Sandboxing","Security","Architecture"],"topics":["Generative AI","Cybersecurity"],"content_type":"concept","learning_level":"technical_beginner","audience":["engineer","data_scientist"],"content":"How OpenShell Works OpenShell runs as a K3s 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. 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. Sandbox Isolated runtime that includes container supervision and policy-enforced egress routing. Policy Engine Policy definition and enforcement layer for filesystem, network, and process constraints. Defense in depth enforces policies from the application layer down to infrastructure and kernel layers. Privacy Router Privacy-aware LLM routing layer that keeps sensitive context on sandbox compute and routes based on cost and privacy policy. How a Request Flows Every outbound connection from agent code passes through the same decision path: The agent process opens an outbound connection (API call, package install, git clone, and so on). The proxy inside the sandbox intercepts the connection and identifies which binary opened it. The proxy queries the policy engine with the destination, port, and calling binary. The policy engine returns one of three decisions: Allow — the destination and binary match a policy block. Traffic flows directly to the external service. Route for inference — no policy block matched, but inference routing is configured. The privacy router intercepts the request, strips the original credentials, injects the configured backend credentials, and forwards to the managed model endpoint. Deny — no match and no inference route. The connection is blocked and logged. For REST endpoints with TLS termination enabled, the proxy also decrypts TLS and checks each HTTP request against per-method, per-path rules before allowing it through. Deployment Modes 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. $ openshell gateway start --remote <username>@<spark-ssid>.local\nopenshell status\nNext Steps Continue with one of the following: To create your first sandbox, refer to the Quickstart . To learn how OpenShell enforces isolation across all protection layers, refer to Sandboxes","format":"text","summary":"OpenShell runs as a K3s 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.","headings":[{"text":"How OpenShell Works","level":1},{"text":"Components","level":2},{"text":"How a Request Flows","level":2},{"text":"Deployment Modes","level":2},{"text":"Next Steps","level":2}]}
\ No newline at end of file
diff --git a/pr-preview/pr-257/about/overview.html b/pr-preview/pr-257/about/overview.html
index 8da03b952..a5cc581d4 100644
--- a/pr-preview/pr-257/about/overview.html
+++ b/pr-preview/pr-257/about/overview.html
@@ -387,7 +387,7 @@
 <p aria-level="2" class="caption" role="heading"><span class="caption-text">Get Started</span></p>
 <ul class="nav bd-sidenav">
 <li class="toctree-l1"><a class="reference internal" href="../get-started/quickstart.html">Quickstart</a></li>
-<li class="toctree-l1"><a class="reference internal" href="../tutorials/github-sandbox.html">Tutorial: GitHub Policy Iteration</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../tutorials/github-sandbox.html">GitHub Policy Tutorial</a></li>
 </ul>
 <p aria-level="2" class="caption" role="heading"><span class="caption-text">Sandboxes</span></p>
 <ul class="nav bd-sidenav">
diff --git a/pr-preview/pr-257/about/overview.json b/pr-preview/pr-257/about/overview.json
index b1db89de1..afd463cc6 100644
--- a/pr-preview/pr-257/about/overview.json
+++ b/pr-preview/pr-257/about/overview.json
@@ -1 +1 @@
-{"id":"about/overview","title":"Overview of NVIDIA OpenShell","url":"about/overview.html","last_modified":"2026-03-12T09:12:26.562681+00:00","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.1.0"},"product":{"name":"OpenShell","version":"0.1.0"},"description":"OpenShell is the safe, private runtime for autonomous AI agents. Run agents in sandboxed environments that protect your data, credentials, and infrastructure.","tags":["AI Agents","Sandboxing","Security","Privacy","Inference Routing"],"topics":["Generative AI","Cybersecurity"],"content_type":"concept","learning_level":"technical_beginner","audience":["engineer","data_scientist"],"content":"Overview of NVIDIA OpenShell 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. 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. Common Risks and Controls The table below summarizes common failure modes and how OpenShell mitigates them. Threat Without controls With OpenShell Data exfiltration Agent uploads source code or internal files to unauthorized endpoints. Network policies allow only approved destinations; other outbound traffic is denied. Credential theft Agent reads local secrets such as SSH keys or cloud credentials. Filesystem restrictions (Landlock) confine access to declared paths only. Unauthorized API usage Agent sends prompts or data to unapproved model providers. Privacy routing and network policies control where inference traffic can go. Privilege escalation Agent attempts sudo , setuid paths, or dangerous syscall behavior. Unprivileged process identity and seccomp restrictions block escalation paths. Protection Layers at a Glance OpenShell applies defense in depth across the following policy domains. Layer What it protects When it applies Filesystem Prevents reads/writes outside allowed paths. Locked at sandbox creation. Network Blocks unauthorized outbound connections. Hot-reloadable at runtime. Process Blocks privilege escalation and dangerous syscalls. Locked at sandbox creation. Inference Reroutes model API calls to controlled backends. Hot-reloadable at runtime. For details, refer to Built-in Default Policy and Customize Sandbox Policies . Common Use Cases 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 Explore these topics to go deeper: To understand the components that make up the OpenShell runtime, refer to the Architecture Overview . To install the CLI and create your first sandbox, refer to the Quickstart . To learn how OpenShell enforces isolation across all protection layers, refer to Sandboxes","format":"text","summary":"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 ...","headings":[{"text":"Overview of NVIDIA OpenShell","level":1},{"text":"Why OpenShell Exists","level":2},{"text":"Common Risks and Controls","level":2},{"text":"Protection Layers at a Glance","level":2},{"text":"Common Use Cases","level":2},{"text":"Next Steps","level":2}]}
\ No newline at end of file
+{"id":"about/overview","title":"Overview of NVIDIA OpenShell","url":"about/overview.html","last_modified":"2026-03-12T23:38:42.323972+00:00","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.1.0"},"product":{"name":"OpenShell","version":"0.1.0"},"description":"OpenShell is the safe, private runtime for autonomous AI agents. Run agents in sandboxed environments that protect your data, credentials, and infrastructure.","tags":["AI Agents","Sandboxing","Security","Privacy","Inference Routing"],"topics":["Generative AI","Cybersecurity"],"content_type":"concept","learning_level":"technical_beginner","audience":["engineer","data_scientist"],"content":"Overview of NVIDIA OpenShell 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. 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. Common Risks and Controls The table below summarizes common failure modes and how OpenShell mitigates them. Threat Without controls With OpenShell Data exfiltration Agent uploads source code or internal files to unauthorized endpoints. Network policies allow only approved destinations; other outbound traffic is denied. Credential theft Agent reads local secrets such as SSH keys or cloud credentials. Filesystem restrictions (Landlock) confine access to declared paths only. Unauthorized API usage Agent sends prompts or data to unapproved model providers. Privacy routing and network policies control where inference traffic can go. Privilege escalation Agent attempts sudo , setuid paths, or dangerous syscall behavior. Unprivileged process identity and seccomp restrictions block escalation paths. Protection Layers at a Glance OpenShell applies defense in depth across the following policy domains. Layer What it protects When it applies Filesystem Prevents reads/writes outside allowed paths. Locked at sandbox creation. Network Blocks unauthorized outbound connections. Hot-reloadable at runtime. Process Blocks privilege escalation and dangerous syscalls. Locked at sandbox creation. Inference Reroutes model API calls to controlled backends. Hot-reloadable at runtime. For details, refer to Built-in Default Policy and Customize Sandbox Policies . Common Use Cases 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 Explore these topics to go deeper: To understand the components that make up the OpenShell runtime, refer to the Architecture Overview . To install the CLI and create your first sandbox, refer to the Quickstart . To learn how OpenShell enforces isolation across all protection layers, refer to Sandboxes","format":"text","summary":"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 ...","headings":[{"text":"Overview of NVIDIA OpenShell","level":1},{"text":"Why OpenShell Exists","level":2},{"text":"Common Risks and Controls","level":2},{"text":"Protection Layers at a Glance","level":2},{"text":"Common Use Cases","level":2},{"text":"Next Steps","level":2}]}
\ No newline at end of file
diff --git a/pr-preview/pr-257/about/release-notes.html b/pr-preview/pr-257/about/release-notes.html
index 7b8827514..334422165 100644
--- a/pr-preview/pr-257/about/release-notes.html
+++ b/pr-preview/pr-257/about/release-notes.html
@@ -387,7 +387,7 @@
 <p aria-level="2" class="caption" role="heading"><span class="caption-text">Get Started</span></p>
 <ul class="nav bd-sidenav">
 <li class="toctree-l1"><a class="reference internal" href="../get-started/quickstart.html">Quickstart</a></li>
-<li class="toctree-l1"><a class="reference internal" href="../tutorials/github-sandbox.html">Tutorial: GitHub Policy Iteration</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../tutorials/github-sandbox.html">GitHub Policy Tutorial</a></li>
 </ul>
 <p aria-level="2" class="caption" role="heading"><span class="caption-text">Sandboxes</span></p>
 <ul class="nav bd-sidenav">
diff --git a/pr-preview/pr-257/about/release-notes.json b/pr-preview/pr-257/about/release-notes.json
index 6b6c93d12..31f462ee9 100644
--- a/pr-preview/pr-257/about/release-notes.json
+++ b/pr-preview/pr-257/about/release-notes.json
@@ -1 +1 @@
-{"id":"about/release-notes","title":"NVIDIA OpenShell Release Notes","url":"about/release-notes.html","last_modified":"2026-03-12T09:12:26.578386+00:00","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.1.0"},"product":{"name":"OpenShell","version":"0.1.0"},"description":"Track the latest changes and improvements to NVIDIA OpenShell.","tags":["Release Notes","Changelog","AI Agents"],"topics":["Generative AI","Cybersecurity"],"content_type":"reference","learning_level":"technical_beginner","audience":["engineer","data_scientist"],"content":"NVIDIA OpenShell Release Notes Track the latest changes and improvements to NVIDIA OpenShell\nThis page covers the highlights of the release\nFor more details, refer to the OpenShell GitHub 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","format":"text","summary":"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.","headings":[{"text":"NVIDIA OpenShell Release Notes","level":1},{"text":"0.1.0","level":2},{"text":"Highlights","level":3}]}
\ No newline at end of file
+{"id":"about/release-notes","title":"NVIDIA OpenShell Release Notes","url":"about/release-notes.html","last_modified":"2026-03-12T23:38:42.327741+00:00","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.1.0"},"product":{"name":"OpenShell","version":"0.1.0"},"description":"Track the latest changes and improvements to NVIDIA OpenShell.","tags":["Release Notes","Changelog","AI Agents"],"topics":["Generative AI","Cybersecurity"],"content_type":"reference","learning_level":"technical_beginner","audience":["engineer","data_scientist"],"content":"NVIDIA OpenShell Release Notes Track the latest changes and improvements to NVIDIA OpenShell\nThis page covers the highlights of the release\nFor more details, refer to the OpenShell GitHub 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","format":"text","summary":"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.","headings":[{"text":"NVIDIA OpenShell Release Notes","level":1},{"text":"0.1.0","level":2},{"text":"Highlights","level":3}]}
\ No newline at end of file
diff --git a/pr-preview/pr-257/get-started/quickstart.html b/pr-preview/pr-257/get-started/quickstart.html
index bfb0cf3a8..fa5d6030d 100644
--- a/pr-preview/pr-257/get-started/quickstart.html
+++ b/pr-preview/pr-257/get-started/quickstart.html
@@ -387,7 +387,7 @@
 <p aria-level="2" class="caption" role="heading"><span class="caption-text">Get Started</span></p>
 <ul class="current nav bd-sidenav">
 <li class="toctree-l1 current active"><a class="current reference internal" href="#">Quickstart</a></li>
-<li class="toctree-l1"><a class="reference internal" href="../tutorials/github-sandbox.html">Tutorial: GitHub Policy Iteration</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../tutorials/github-sandbox.html">GitHub Policy Tutorial</a></li>
 </ul>
 <p aria-level="2" class="caption" role="heading"><span class="caption-text">Sandboxes</span></p>
 <ul class="nav bd-sidenav">
diff --git a/pr-preview/pr-257/get-started/quickstart.json b/pr-preview/pr-257/get-started/quickstart.json
index d8910a135..ad02af0ab 100644
--- a/pr-preview/pr-257/get-started/quickstart.json
+++ b/pr-preview/pr-257/get-started/quickstart.json
@@ -1 +1 @@
-{"id":"get-started/quickstart","title":"Quickstart","url":"get-started/quickstart.html","last_modified":"2026-03-12T09:12:26.567481+00:00","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.1.0"},"product":{"name":"OpenShell","version":"0.1.0"},"description":"Install the OpenShell CLI and create your first sandboxed AI agent in two commands.","tags":["AI Agents","Sandboxing","Installation","Quickstart"],"topics":["Generative AI","Cybersecurity"],"content_type":"get_started","learning_level":"technical_beginner","audience":["engineer","data_scientist"],"content":"Quickstart This page gets you from zero to a running, policy-enforced sandbox in two commands. Prerequisites Before you begin, make sure you have: Python 3.12 or later uv installed Docker Desktop running on your machine Install the OpenShell CLI Install the openshell package into a virtual environment. Activate your virtual environment: uv venv && source .venv/bin/activate\nInstall the CLI: uv pip install openshell\nConnect to a Remote Gateway (Optional) If you’re running locally, skip this step. The OpenShell CLI creates a gateway automatically when you create your first sandbox. Brev Deploy an OpenShell gateway on Brev by hitting Deploy on the OpenShell Launchable . 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. $ openshell gateway add https://<your-port-8080-url>.brevlab.com\nopenshell status\nDGX Spark 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: $ openshell gateway start --remote <username>@<spark-ssid>.local\nopenshell status\nAfter openshell status shows the gateway as healthy, all subsequent commands route through the SSH tunnel. Create Your First OpenShell Sandbox Choose the tab that matches your agent: Claude Code Run the following command to create a sandbox with Claude Code: $ openshell sandbox create -- claude\nThe CLI prompts you to create a provider from local credentials — type yes to continue. If ANTHROPIC_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. OpenCode Run the following command to create a sandbox with OpenCode: $ openshell sandbox create -- opencode\nThe 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. Codex Run the following command to create a sandbox with Codex: $ openshell sandbox create -- codex\nThe 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. OpenClaw Run the following command to create a sandbox with OpenClaw: $ openshell sandbox create --from openclaw\nThe --from flag pulls a pre-built sandbox definition from the OpenShell Community catalog. Each definition bundles a container image, a tailored policy, and optional skills into a single package. Community Sandbox You can use the --from flag to pull other OpenShell sandbox images from the NVIDIA Container Registry . For example, to pull the base image, run the following command: $ openshell sandbox create --from base","format":"text","summary":"This page gets you from zero to a running, policy-enforced sandbox in two commands.","headings":[{"text":"Quickstart","level":1},{"text":"Prerequisites","level":2},{"text":"Install the OpenShell CLI","level":2},{"text":"Connect to a Remote Gateway (Optional)","level":2},{"text":"Create Your First OpenShell Sandbox","level":2}]}
\ No newline at end of file
+{"id":"get-started/quickstart","title":"Quickstart","url":"get-started/quickstart.html","last_modified":"2026-03-12T23:38:42.392461+00:00","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.1.0"},"product":{"name":"OpenShell","version":"0.1.0"},"description":"Install the OpenShell CLI and create your first sandboxed AI agent in two commands.","tags":["AI Agents","Sandboxing","Installation","Quickstart"],"topics":["Generative AI","Cybersecurity"],"content_type":"get_started","learning_level":"technical_beginner","audience":["engineer","data_scientist"],"content":"Quickstart This page gets you from zero to a running, policy-enforced sandbox in two commands. Prerequisites Before you begin, make sure you have: Python 3.12 or later uv installed Docker Desktop running on your machine Install the OpenShell CLI Install the openshell package into a virtual environment. Activate your virtual environment: uv venv && source .venv/bin/activate\nInstall the CLI: uv pip install openshell\nConnect to a Remote Gateway (Optional) If you’re running locally, skip this step. The OpenShell CLI creates a gateway automatically when you create your first sandbox. Brev Deploy an OpenShell gateway on Brev by hitting Deploy on the OpenShell Launchable . 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. $ openshell gateway add https://<your-port-8080-url>.brevlab.com\nopenshell status\nDGX Spark 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: $ openshell gateway start --remote <username>@<spark-ssid>.local\nopenshell status\nAfter openshell status shows the gateway as healthy, all subsequent commands route through the SSH tunnel. Create Your First OpenShell Sandbox Choose the tab that matches your agent: Claude Code Run the following command to create a sandbox with Claude Code: $ openshell sandbox create -- claude\nThe CLI prompts you to create a provider from local credentials — type yes to continue. If ANTHROPIC_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. OpenCode Run the following command to create a sandbox with OpenCode: $ openshell sandbox create -- opencode\nThe 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. Codex Run the following command to create a sandbox with Codex: $ openshell sandbox create -- codex\nThe 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. OpenClaw Run the following command to create a sandbox with OpenClaw: $ openshell sandbox create --from openclaw\nThe --from flag pulls a pre-built sandbox definition from the OpenShell Community catalog. Each definition bundles a container image, a tailored policy, and optional skills into a single package. Community Sandbox You can use the --from flag to pull other OpenShell sandbox images from the NVIDIA Container Registry . For example, to pull the base image, run the following command: $ openshell sandbox create --from base","format":"text","summary":"This page gets you from zero to a running, policy-enforced sandbox in two commands.","headings":[{"text":"Quickstart","level":1},{"text":"Prerequisites","level":2},{"text":"Install the OpenShell CLI","level":2},{"text":"Connect to a Remote Gateway (Optional)","level":2},{"text":"Create Your First OpenShell Sandbox","level":2}]}
\ No newline at end of file
diff --git a/pr-preview/pr-257/index.html b/pr-preview/pr-257/index.html
index 466720955..242e001ce 100644
--- a/pr-preview/pr-257/index.html
+++ b/pr-preview/pr-257/index.html
@@ -386,7 +386,7 @@
 <p aria-level="2" class="caption" role="heading"><span class="caption-text">Get Started</span></p>
 <ul class="nav bd-sidenav">
 <li class="toctree-l1"><a class="reference internal" href="get-started/quickstart.html">Quickstart</a></li>
-<li class="toctree-l1"><a class="reference internal" href="tutorials/github-sandbox.html">Tutorial: GitHub Policy Iteration</a></li>
+<li class="toctree-l1"><a class="reference internal" href="tutorials/github-sandbox.html">GitHub Policy Tutorial</a></li>
 </ul>
 <p aria-level="2" class="caption" role="heading"><span class="caption-text">Sandboxes</span></p>
 <ul class="nav bd-sidenav">
diff --git a/pr-preview/pr-257/index.json b/pr-preview/pr-257/index.json
index 96a785260..38f01698c 100644
--- a/pr-preview/pr-257/index.json
+++ b/pr-preview/pr-257/index.json
@@ -1 +1 @@
-[{"id":"about/architecture","title":"How OpenShell Works","url":"about/architecture.html","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.1.0"},"product":{"name":"OpenShell","version":"0.1.0"},"description":"OpenShell architecture overview covering the gateway, sandbox, policy engine, and privacy router.","tags":["AI Agents","Sandboxing","Security","Architecture"],"topics":["Generative AI","Cybersecurity"],"content_type":"concept","learning_level":"technical_beginner","audience":["engineer","data_scientist"],"content":"How OpenShell Works OpenShell runs as a K3s 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. 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. Sandbox Isolated runtime that includes container supervision and policy-enforced egress routing. Policy Engine Policy definition and enforcement layer for filesystem, network, and process constraints. Defense in depth enforces policies from the application layer down to infrastructure and kernel layers. Privacy Router Privacy-aware LLM routing layer that keeps sensitive context on sandbox compute and routes based on cost and privacy policy. How a Request Flows Every outbound connection from agent code passes through the same decision path: The agent process opens an outbound connection (API call, package install, git clone, and so on). The proxy inside the sandbox intercepts the connection and identifies which binary opened it. The proxy queries the policy engine with the destination, port, and calling binary. The policy engine returns one of three decisions: Allow — the destination and binary match a policy block. Traffic flows directly to the external service. Route for inference — no policy block matched, but inference routing is configured. The privacy router intercepts the request, strips the original credentials, injects the configured backend credentials, and forwards to the managed model endpoint. Deny — no match and no inference route. The connection is blocked and logged. For REST endpoints with TLS termination enabled, the proxy also decrypts TLS and checks each HTTP request against per-method, per-path rules before allowing it through. Deployment Modes 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. $ openshell gateway start --remote <username>@<spark-ssid>.local\nopenshell status\nNext Steps Continue with one of the following: To create your first sandbox, refer to the Quickstart . To learn how OpenShell enforces isolation across all protection layers, refer to Sandboxes","format":"text","content_length":2611,"word_count":393,"summary":"OpenShell runs as a K3s 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.","headings":[{"text":"How OpenShell Works","level":1,"id":"how-openshell-works"},{"text":"Components","level":2,"id":"components"},{"text":"How a Request Flows","level":2,"id":"how-a-request-flows"},{"text":"Deployment Modes","level":2,"id":"deployment-modes"},{"text":"Next Steps","level":2,"id":"next-steps"}],"headings_text":"How OpenShell Works Components How a Request Flows Deployment Modes Next Steps","keywords":["allow","component","components","continue","control","decisions","defense","deny","deploy","deployment","docker","each","engine","every","flows","following","four","gateway","isolated","k3s","kubernetes","local","modes","next","openshell","path","policy","privacy","quickstart","remote","request","role","route","router","sandbox","sandboxes","spark","steps","system","traffic","works"],"code_blocks":[{"content":"$ openshell gateway start --remote <username>@<spark-ssid>.local\n$ openshell status","language":"text"}],"links":[{"text":"K3s","type":"external","url":"https://k3s.io/"},{"text":"OpenShell architecture diagram showing the component layout","type":"internal","url":"about/../_images/architecture.svg"}],"images":[{"src":"about/architecture.svg","alt":"OpenShell architecture diagram showing the component layout"},{"src":"about/architecture.svg","alt":"OpenShell architecture diagram showing the component layout"}],"doc_type":"documentation","section_path":["About","Architecture"]},{"id":"about/overview","title":"Overview of NVIDIA OpenShell","url":"about/overview.html","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.1.0"},"product":{"name":"OpenShell","version":"0.1.0"},"description":"OpenShell is the safe, private runtime for autonomous AI agents. Run agents in sandboxed environments that protect your data, credentials, and infrastructure.","tags":["AI Agents","Sandboxing","Security","Privacy","Inference Routing"],"topics":["Generative AI","Cybersecurity"],"content_type":"concept","learning_level":"technical_beginner","audience":["engineer","data_scientist"],"content":"Overview of NVIDIA OpenShell 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. 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. Common Risks and Controls The table below summarizes common failure modes and how OpenShell mitigates them. Threat Without controls With OpenShell Data exfiltration Agent uploads source code or internal files to unauthorized endpoints. Network policies allow only approved destinations; other outbound traffic is denied. Credential theft Agent reads local secrets such as SSH keys or cloud credentials. Filesystem restrictions (Landlock) confine access to declared paths only. Unauthorized API usage Agent sends prompts or data to unapproved model providers. Privacy routing and network policies control where inference traffic can go. Privilege escalation Agent attempts sudo , setuid paths, or dangerous syscall behavior. Unprivileged process identity and seccomp restrictions block escalation paths. Protection Layers at a Glance OpenShell applies defense in depth across the following policy domains. Layer What it protects When it applies Filesystem Prevents reads/writes outside allowed paths. Locked at sandbox creation. Network Blocks unauthorized outbound connections. Hot-reloadable at runtime. Process Blocks privilege escalation and dangerous syscalls. Locked at sandbox creation. Inference Reroutes model API calls to controlled backends. Hot-reloadable at runtime. For details, refer to Built-in Default Policy and Customize Sandbox Policies . Common Use Cases 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 Explore these topics to go deeper: To understand the components that make up the OpenShell runtime, refer to the Architecture Overview . To install the CLI and create your first sandbox, refer to the Quickstart . To learn how OpenShell enforces isolation across all protection layers, refer to Sandboxes","format":"text","content_length":2852,"word_count":403,"summary":"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 ...","headings":[{"text":"Overview of NVIDIA OpenShell","level":1,"id":"overview-of-nvidia-openshell"},{"text":"Why OpenShell Exists","level":2,"id":"why-openshell-exists"},{"text":"Common Risks and Controls","level":2,"id":"common-risks-and-controls"},{"text":"Protection Layers at a Glance","level":2,"id":"protection-layers-at-a-glance"},{"text":"Common Use Cases","level":2,"id":"common-use-cases"},{"text":"Next Steps","level":2,"id":"next-steps"}],"headings_text":"Overview of NVIDIA OpenShell Why OpenShell Exists Common Risks and Controls Protection Layers at a Glance Common Use Cases Next Steps","keywords":["agent","apis","architecture","blocks","built","case","cases","claude","code","common","compliance","controls","credential","customize","data","deeper","default","description","exists","explore","filesystem","glance","hot","inference","landlock","layer","layers","locked","network","next","nvidia","openclaw","opencode","openshell","overview","policies","policy","prevents","privacy","private","privilege","process","protection","quickstart","reroutes","reusable","risks","route","run","sandbox"],"code_blocks":[],"links":[],"images":[],"doc_type":"documentation","section_path":["About","Overview"]},{"id":"about/release-notes","title":"NVIDIA OpenShell Release Notes","url":"about/release-notes.html","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.1.0"},"product":{"name":"OpenShell","version":"0.1.0"},"description":"Track the latest changes and improvements to NVIDIA OpenShell.","tags":["Release Notes","Changelog","AI Agents"],"topics":["Generative AI","Cybersecurity"],"content_type":"reference","learning_level":"technical_beginner","audience":["engineer","data_scientist"],"content":"NVIDIA OpenShell Release Notes Track the latest changes and improvements to NVIDIA OpenShell\nThis page covers the highlights of the release\nFor more details, refer to the OpenShell GitHub 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","format":"text","content_length":731,"word_count":97,"summary":"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.","headings":[{"text":"NVIDIA OpenShell Release Notes","level":1,"id":"nvidia-openshell-release-notes"},{"text":"0.1.0","level":2,"id":"010"},{"text":"Highlights","level":3,"id":"highlights"}],"headings_text":"NVIDIA OpenShell Release Notes 0.1.0 Highlights","keywords":["github","highlights","introduces","notes","nvidia","openshell","release","releases","this","track"],"code_blocks":[],"links":[{"text":"OpenShell GitHub Releases","type":"external","url":"https://github.com/NVIDIA/OpenShell/releases"}],"images":[],"doc_type":"documentation","section_path":["About","Release Notes"]},{"id":"get-started/quickstart","title":"Quickstart","url":"get-started/quickstart.html","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.1.0"},"product":{"name":"OpenShell","version":"0.1.0"},"description":"Install the OpenShell CLI and create your first sandboxed AI agent in two commands.","tags":["AI Agents","Sandboxing","Installation","Quickstart"],"topics":["Generative AI","Cybersecurity"],"content_type":"get_started","learning_level":"technical_beginner","audience":["engineer","data_scientist"],"content":"Quickstart This page gets you from zero to a running, policy-enforced sandbox in two commands. Prerequisites Before you begin, make sure you have: Python 3.12 or later uv installed Docker Desktop running on your machine Install the OpenShell CLI Install the openshell package into a virtual environment. Activate your virtual environment: uv venv && source .venv/bin/activate\nInstall the CLI: uv pip install openshell\nConnect to a Remote Gateway (Optional) If you’re running locally, skip this step. The OpenShell CLI creates a gateway automatically when you create your first sandbox. Brev Deploy an OpenShell gateway on Brev by hitting Deploy on the OpenShell Launchable . 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. $ openshell gateway add https://<your-port-8080-url>.brevlab.com\nopenshell status\nDGX Spark 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: $ openshell gateway start --remote <username>@<spark-ssid>.local\nopenshell status\nAfter openshell status shows the gateway as healthy, all subsequent commands route through the SSH tunnel. Create Your First OpenShell Sandbox Choose the tab that matches your agent: Claude Code Run the following command to create a sandbox with Claude Code: $ openshell sandbox create -- claude\nThe CLI prompts you to create a provider from local credentials — type yes to continue. If ANTHROPIC_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. OpenCode Run the following command to create a sandbox with OpenCode: $ openshell sandbox create -- opencode\nThe 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. Codex Run the following command to create a sandbox with Codex: $ openshell sandbox create -- codex\nThe 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. OpenClaw Run the following command to create a sandbox with OpenClaw: $ openshell sandbox create --from openclaw\nThe --from flag pulls a pre-built sandbox definition from the OpenShell Community catalog. Each definition bundles a container image, a tailored policy, and optional skills into a single package. Community Sandbox You can use the --from flag to pull other OpenShell sandbox images from the NVIDIA Container Registry . For example, to pull the base image, run the following command: $ openshell sandbox create --from base","format":"text","content_length":2947,"word_count":470,"summary":"This page gets you from zero to a running, policy-enforced sandbox in two commands.","headings":[{"text":"Quickstart","level":1,"id":"quickstart"},{"text":"Prerequisites","level":2,"id":"prerequisites"},{"text":"Install the OpenShell CLI","level":2,"id":"install-the-openshell-cli"},{"text":"Connect to a Remote Gateway (Optional)","level":2,"id":"connect-to-a-remote-gateway-optional"},{"text":"Create Your First OpenShell Sandbox","level":2,"id":"create-your-first-openshell-sandbox"}],"headings_text":"Quickstart Prerequisites Install the OpenShell CLI Connect to a Remote Gateway (Optional) Create Your First OpenShell Sandbox","keywords":["activate","after","agent","before","brev","choose","claude","cli","code","codex","com","command","community","connect","container","copy","create","deploy","desktop","docker","each","environment","first","gateway","have","https","install","launchable","links","openclaw","opencode","openshell","optional","prerequisites","python","quickstart","registry","remote","run","sandbox","secure","set","spark","sync","this","type","using","venv","your"],"code_blocks":[{"content":"uv venv && source .venv/bin/activate","language":"text"},{"content":"uv pip install openshell","language":"text"},{"content":"$ openshell gateway add https://<your-port-8080-url>.brevlab.com\n$ openshell status","language":"text"},{"content":"$ openshell gateway start --remote <username>@<spark-ssid>.local\n$ openshell status","language":"text"},{"content":"$ openshell sandbox create -- claude","language":"text"},{"content":"$ openshell sandbox create -- opencode","language":"text"},{"content":"$ openshell sandbox create -- codex","language":"text"},{"content":"$ openshell sandbox create --from openclaw","language":"text"},{"content":"$ openshell sandbox create --from base","language":"text"}],"links":[{"text":"Uv","type":"external","url":"https://docs.astral.sh/uv/","original_text":"uv"},{"text":"OpenShell Launchable","type":"external","url":"https://brev.nvidia.com/launchable/deploy/now?launchableID=env-3AaK9NmCzWp3pVyUDNNFBt805FT"},{"text":"OpenShell Community","type":"external","url":"https://github.com/NVIDIA/OpenShell-Community"},{"text":"NVIDIA Container Registry","type":"external","url":"https://registry.nvidia.com/"}],"images":[],"doc_type":"tutorial","section_path":["Get Started","Quickstart"]},{"id":"inference/configure","title":"Configure Inference Routing","url":"inference/configure.html","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.1.0"},"product":{"name":"OpenShell","version":"0.1.0"},"description":"Set up the managed local inference endpoint with provider credentials and model configuration.","tags":["Inference Routing","Configuration","Privacy","LLM","Provider"],"topics":["Generative AI","Cybersecurity"],"content_type":"how_to","learning_level":"technical_intermediate","audience":["engineer"],"content":"Configure Inference Routing This page covers the managed local inference endpoint ( https://inference.local ). External inference endpoints go through sandbox network_policies — refer to Network Access Rules for details. The configuration consists of two values: Value Description Provider record The credential backend OpenShell uses to authenticate with the upstream model host. Model ID The model to use for generation requests. Step 1: Create a Provider Create a provider that holds the backend credentials you want OpenShell to use. NVIDIA API Catalog $ openshell provider create --name nvidia-prod --type nvidia --from-existing\nThis reads NVIDIA_API_KEY from your environment. Local / self-hosted endpoint $ openshell provider create\nname my-local-model\ntype openai\ncredential OPENAI_API_KEY=empty-if-not-required\nconfig OPENAI_BASE_URL=http://192.168.10.15/v1\nUse --config OPENAI_BASE_URL to point to any OpenAI-compatible server running on your network. Set OPENAI_API_KEY to a dummy value if the server does not require authentication. Anthropic $ openshell provider create --name anthropic-prod --type anthropic --from-existing\nThis reads ANTHROPIC_API_KEY from your environment. Step 2: Set Inference Routing Point inference.local at that provider and choose the model to use: $ openshell inference set\nprovider nvidia-prod\nmodel nvidia/nemotron-3-nano-30b-a3b\nStep 3: Verify the Active Config Confirm that the provider and model are set correctly: $ openshell inference get\nGateway inference\nProvider: nvidia-prod\nModel: nvidia/nemotron-3-nano-30b-a3b\nVersion: 1\nStep 4: Update Part of the Config Use update when you want to change only one field: $ openshell inference update --model nvidia/nemotron-3-nano-30b-a3b\nOr switch providers without repeating the current model: $ openshell inference update --provider openai-prod\nUse It from a Sandbox After inference is configured, code inside any sandbox can call https://inference.local directly: from openai import OpenAI\nclient = OpenAI(base_url=\"https://inference.local/v1\", api_key=\"dummy\nresponse = client.chat.completions.create\nmodel=\"anything\nmessages=[{\"role\": \"user\", \"content\": \"Hello\nThe client-supplied model is ignored for generation requests. OpenShell rewrites it to the configured model before forwarding upstream. Use this endpoint when inference should stay local to the host for privacy and security reasons. External providers that should be reached directly belong in network_policies instead. Verify the Endpoint from a Sandbox openshell inference get confirms the configuration was saved, but does not verify the upstream endpoint is reachable. To confirm end-to-end connectivity, connect to a sandbox and run: curl https://inference.local/v1/responses\nH \"Content-Type: application/json\"\nd\ninstructions\": \"You are a helpful assistant\ninput\": \"Hello\nA successful response confirms the privacy router can reach the configured backend and the model is serving requests. Gateway-scoped — every sandbox on the active gateway sees the same inference.local backend. HTTPS only — inference.local is intercepted only for HTTPS traffic. Next Steps Explore related topics: To understand the inference routing flow and supported API patterns, refer to index . To control external endpoints, refer to Network Access Rules . To manage provider records, refer to ../sandboxes/providers . To view openshell inference commands, refer to ../reference/cli","format":"text","content_length":3420,"word_count":453,"summary":"This page covers the managed local inference endpoint (https://inference.local). External inference endpoints go through sandbox network_policies — refer to Network Access Rules for details.","headings":[{"text":"Configure Inference Routing","level":1,"id":"configure-inference-routing"},{"text":"Step 1: Create a Provider","level":2,"id":"step-1-create-a-provider"},{"text":"Step 2: Set Inference Routing","level":2,"id":"step-2-set-inference-routing"},{"text":"Step 3: Verify the Active Config","level":2,"id":"step-3-verify-the-active-config"},{"text":"Step 4: Update Part of the Config","level":2,"id":"step-4-update-part-of-the-config"},{"text":"Use It from a Sandbox","level":2,"id":"use-it-from-a-sandbox"},{"text":"Verify the Endpoint from a Sandbox","level":3,"id":"verify-the-endpoint-from-a-sandbox"},{"text":"Next Steps","level":2,"id":"next-steps"}],"headings_text":"Configure Inference Routing Step 1: Create a Provider Step 2: Set Inference Routing Step 3: Verify the Active Config Step 4: Update Part of the Config Use It from a Sandbox Verify the Endpoint from a Sandbox Next Steps","keywords":["access","active","after","anthropic","api_key","base_url","catalog","chat","client","config","configure","confirm","content","correctly","create","description","directly","endpoint","explore","external","field","from","gateway","hello","http","https","inference","local","messages","model","network","next","openai","openshell","part","point","provider","response","routing","rules","run","sandbox","set","step","steps","this","topics","type","update","user"],"code_blocks":[{"content":"$ openshell provider create --name nvidia-prod --type nvidia --from-existing","language":"text"},{"content":"$ openshell provider create \\\n    --name my-local-model \\\n    --type openai \\\n    --credential OPENAI_API_KEY=empty-if-not-required \\\n    --config OPENAI_BASE_URL=http://192.168.10.15/v1","language":"text"},{"content":"$ openshell provider create --name anthropic-prod --type anthropic --from-existing","language":"text"},{"content":"$ openshell inference set \\\n    --provider nvidia-prod \\\n    --model nvidia/nemotron-3-nano-30b-a3b","language":"text"},{"content":"$ openshell inference get\nGateway inference:\n\n  Provider: nvidia-prod\n  Model: nvidia/nemotron-3-nano-30b-a3b\n  Version: 1","language":"text"},{"content":"$ openshell inference update --model nvidia/nemotron-3-nano-30b-a3b","language":"text"},{"content":"$ openshell inference update --provider openai-prod","language":"text"},{"content":"from openai import OpenAI\n\nclient = OpenAI(base_url=\"https://inference.local/v1\", api_key=\"dummy\")\n\nresponse = client.chat.completions.create(\n    model=\"anything\",\n    messages=[{\"role\": \"user\", \"content\": \"Hello\"}],\n)","language":"text"},{"content":"curl https://inference.local/v1/responses \\\n    -H \"Content-Type: application/json\" \\\n    -d '{\n      \"instructions\": \"You are a helpful assistant.\",\n      \"input\": \"Hello!\"\n    }'","language":"text"}],"links":[],"images":[],"doc_type":"tutorial","section_path":["Inference","Configure"]},{"id":"inference/index","title":"About Inference Routing","url":"inference/index.html","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.1.0"},"product":{"name":"OpenShell","version":"0.1.0"},"description":"Understand how OpenShell routes inference traffic through external endpoints and the local privacy router.","tags":["Inference Routing","Privacy","AI Agents","LLM"],"topics":["Generative AI","Cybersecurity"],"content_type":"concept","learning_level":"technical_beginner","audience":["engineer","data_scientist"],"content":"About Inference Routing 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 . Refer to 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 privacy router strips the original credentials, injects the configured backend credentials, and forwards to the managed model endpoint. How inference.local Works When code inside a sandbox calls https://inference.local , the privacy router routes the request to the configured backend for that gateway. The configured model is applied to generation requests, and provider credentials are supplied by OpenShell rather than by code inside the sandbox. If code calls an external inference host directly, that traffic is evaluated only by network_policies . Property Detail Credentials No sandbox API keys needed — credentials come from the configured provider record. Configuration One provider and one model define sandbox inference. Provider support OpenAI, Anthropic, and NVIDIA providers all work through the same endpoint. Hot-refresh Provider credential changes and inference updates are picked up without recreating sandboxes. Supported API Patterns Supported request patterns depend on the provider configured for inference.local . OpenAI-compatible Pattern Method Path Chat Completions POST /v1/chat/completions Completions POST /v1/completions Responses POST /v1/responses Model Discovery GET /v1/models Model Discovery GET /v1/models/* Anthropic-compatible Pattern Method Path Messages POST /v1/messages Requests to inference.local that do not match the configured provider’s supported patterns are denied. Next Steps Continue with one of the following: To set up the backend behind inference.local , refer to configure . To control external endpoints, refer to Network Access Rules","format":"text","content_length":2010,"word_count":281,"summary":"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.","headings":[{"text":"About Inference Routing","level":1,"id":"about-inference-routing"},{"text":"How inference.local Works","level":2,"id":"how-inferencelocal-works"},{"text":"Supported API Patterns","level":2,"id":"supported-api-patterns"},{"text":"Next Steps","level":2,"id":"next-steps"}],"headings_text":"About Inference Routing How inference.local Works Supported API Patterns Next Steps","keywords":["about","access","anthropic","api","chat","com","completions","configuration","continue","credentials","detail","discovery","external","following","hot","https","inference","local","messages","method","model","network","next","openai","openshell","path","pattern","patterns","property","provider","refer","requests","responses","routing","rules","steps","supported","traffic","ways","works"],"code_blocks":[],"links":[],"images":[],"doc_type":"overview","section_path":["Inference"]},{"id":"reference/cli","title":"CLI Reference","url":"reference/cli.html","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.1.0"},"product":{"name":"OpenShell","version":"0.1.0"},"description":"Complete command reference for the openshell CLI including all subcommands, flags, and environment variables.","tags":["CLI","Reference","Commands","AI Agents"],"topics":["Generative AI","Cybersecurity"],"content_type":"reference","learning_level":"technical_beginner","audience":["engineer","data_scientist"],"content":"CLI Reference Complete command reference for the openshell CLI. Every subcommand, flag, and option is documented here. Command Tree The full hierarchy of openshell subcommands: openshell\nstatus\nlogs [name\nterm\nforward\n├── start <port> <name\n├── stop <port> <name\n└── list\ngateway\n├── start\n├── stop\n├── destroy\n├── info\n├── add <url\n└── select [name\nsandbox\n├── create\n├── get [name\n├── list\n├── delete <name...> [--all\n├── connect [name\n├── upload [name\n├── download [name\n└── ssh-config <name\npolicy\n├── set <name\n├── get <name\n└── list <name\nprovider\n├── create\n├── get <name\n├── list\n├── update <name\n└── delete <name\ninference\n├── set\n├── update\n└── get\ndoctor\n├── logs\n└── exec\ncompletions <shell\nCommands that accept an optional [name] argument — such as get , connect , upload , download , and logs — fall back to the last-used sandbox when the name is omitted. The CLI records the sandbox name each time you create or connect, and prints a hint showing which sandbox was selected. 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. openshell logs [name] View sandbox logs. Use --tail for streaming, --source and --level to filter. openshell term Launch the OpenShell Terminal — a dashboard showing sandbox status, live logs, and policy decisions in a single view. Navigate with j / k , press f to follow live output, s to filter by source, and q to quit. Refer to /sandboxes/create-and-manage for more on monitoring sandboxes and reading log entries. Gateway Commands Manage the OpenShell runtime cluster. Command Description openshell gateway start Deploy a new cluster. Add --remote user@host for remote deployment. 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 <url> Register an existing remote gateway by URL. openshell gateway select <name> Set the active cluster. All subsequent commands target this cluster. openshell gateway select List all registered clusters (when called without a name). Diagnostic Commands Troubleshoot gateway issues. Command Description openshell doctor logs Fetch logs from the gateway Docker container. Use --tail for streaming, -n to limit line count. openshell doctor exec -- <command> Run a command inside the gateway container (e.g., kubectl get pods -A , k9s , sh ). Sandbox Commands Create and manage isolated agent execution environments. Command Description 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 <name...> Delete one or more sandboxes by name. Use --all to delete every sandbox in the active gateway. openshell sandbox connect [name] Open an interactive SSH session into a running sandbox. openshell sandbox upload [name] Upload files from the host into a sandbox. openshell sandbox download [name] Download files from a sandbox to the host. openshell sandbox ssh-config <name> Print the generated SSH config block for a sandbox. Sandbox Create Flags The following flags control sandbox creation: Flag Description --name Assign a human-readable name to the sandbox. Auto-generated if omitted. --provider Attach a credential provider. Repeatable for multiple providers. --policy Path to a policy YAML file to apply at creation time. --upload Upload local files into the sandbox before running. --keep Keep the sandbox alive after the trailing command exits. --editor Launch vscode or cursor into /sandbox ; installs OpenShell-managed SSH config and implies --keep . --gpu Request a GPU-enabled sandbox. If no gateway is running, auto-bootstrap starts a GPU-enabled gateway. --editor Launch vscode or cursor into /sandbox ; installs OpenShell-managed SSH config and implies --keep . --forward Forward a local port into the sandbox at startup. --from Build from a community sandbox name, local Dockerfile directory, or container image reference. -- <command> The command to run inside the sandbox. Everything after -- is passed as the agent command. Policy Commands Apply and inspect sandbox policies at runtime. Command Description openshell policy set <name> Apply or update a policy on a running sandbox. Pass --policy <file> . openshell policy get <name> Show the active policy for a sandbox. Add --full for the complete policy with metadata. openshell policy list <name> List all policy versions applied to a sandbox, with status. Port Forwarding Commands Forward sandbox ports to the host for local access. Command Description openshell forward start <port> <name> Forward a sandbox port to the host. Add -d for background mode. openshell forward stop <port> <name> Stop an active port forward. openshell forward list List all active port forwards. Provider Commands Manage credential providers that inject secrets into sandboxes. Command Description openshell provider create Create a new credential provider. Refer to the flag reference below. openshell provider get <name> Show details of a provider. openshell provider list List all providers in the active cluster. openshell provider update <name> Update a provider’s credentials or configuration. openshell provider delete <name> Delete a provider. Provider Create Flags The following flags control provider creation: Flag Description --name Name for the provider. --type Provider type: claude , codex , opencode , github , gitlab , nvidia , generic , outlook . --from-existing Discover credentials from your current shell environment variables. --credential Set a credential explicitly. Format: KEY=VALUE or bare KEY to read from env. Repeatable. --config Set a configuration value. Format: KEY=VALUE . Repeatable. Inference Commands Configure the backend used by https://inference.local . openshell inference set Set the provider and model for managed inference. Both flags are required. Flag Description --provider Provider record name to use for injected credentials. --model Model identifier to force on generation requests. openshell inference update Update only the fields you specify. Flag Description --provider Replace the current provider record. --model Replace the current model ID. openshell inference get Show the current inference configuration, including provider, model, and version. Environment Variables The following environment variables override CLI defaults: Variable Description OPENSHELL_GATEWAY Name of the gateway to operate on. Overrides the active gateway set by openshell gateway select . OPENSHELL_SANDBOX_POLICY Default path to a policy YAML file. When set, openshell sandbox create uses this policy if no --policy flag is provided. Shell Completions Generate shell completion scripts for tab completion: $ openshell completions bash\nopenshell completions zsh\nopenshell completions fish\nPipe the output to your shell’s config file: $ openshell completions zsh >> ~/.zshrc\nsource ~/.zshrc\nBuilt-in Help Every command and subcommand includes built-in help. Use --help at any level to see available subcommands, flags, and usage examples: $ openshell --help\nopenshell sandbox --help\nopenshell sandbox create --help\nopenshell gateway --help\nHelp output groups flags under distinct headings: FLAGS for command-specific options, GATEWAY FLAGS for --gateway and --gateway-endpoint , and GLOBAL FLAGS for --verbose , --help , and --version","format":"text","content_length":7605,"word_count":1138,"summary":"Complete command reference for the openshell CLI. Every subcommand, flag, and option is documented here.","headings":[{"text":"CLI Reference","level":1,"id":"cli-reference"},{"text":"Command Tree","level":2,"id":"command-tree"},{"text":"Status, Logs, and Terminal","level":2,"id":"status-logs-and-terminal"},{"text":"Gateway Commands","level":2,"id":"gateway-commands"},{"text":"Diagnostic Commands","level":2,"id":"diagnostic-commands"},{"text":"Sandbox Commands","level":2,"id":"sandbox-commands"},{"text":"Sandbox Create Flags","level":3,"id":"sandbox-create-flags"},{"text":"Policy Commands","level":2,"id":"policy-commands"},{"text":"Port Forwarding Commands","level":2,"id":"port-forwarding-commands"},{"text":"Provider Commands","level":2,"id":"provider-commands"},{"text":"Provider Create Flags","level":3,"id":"provider-create-flags"},{"text":"Inference Commands","level":2,"id":"inference-commands"},{"text":"openshell inference set","level":3,"id":"openshell-inference-set"},{"text":"openshell inference update","level":3,"id":"openshell-inference-update"},{"text":"openshell inference get","level":3,"id":"openshell-inference-get"},{"text":"Environment Variables","level":2,"id":"environment-variables"},{"text":"Shell Completions","level":2,"id":"shell-completions"},{"text":"Built-in Help","level":2,"id":"built-in-help"}],"headings_text":"CLI Reference Command Tree Status, Logs, and Terminal Gateway Commands Diagnostic Commands Sandbox Commands Sandbox Create Flags Policy Commands Port Forwarding Commands Provider Commands Provider Create Flags Inference Commands openshell inference set openshell inference update openshell inference get Environment Variables Shell Completions Built-in Help","keywords":["add","apply","assign","attach","auto","both","build","built","check","cli","command","commands","complete","completion","completions","configure","create","creation","dashboard","default","defaults","delete","deploy","description","diagnostic","discover","docker","dockerfile","download","environment","every","everything","examples","fetch","file","flag","flags","format","forward","forwarding","gateway","generate","headings","help","https","inference","keep","launch","list","logs"],"code_blocks":[{"content":"openshell\n├── status\n├── logs [name]\n├── term\n├── forward\n│   ├── start <port> <name>\n│   ├── stop <port> <name>\n│   └── list\n├── gateway\n│   ├── start\n│   ├── stop\n│   ├── destroy\n│   ├── info\n│   ├── add <url>\n│   └── select [name]\n├── sandbox\n│   ├── create\n│   ├── get [name]\n│   ├── list\n│   ├── delete <name...> [--all]\n│   ├── connect [name]\n│   ├── upload [name]\n│   ├── download [name]\n│   └── ssh-config <name>\n├── policy\n│   ├── set <name>\n│   ├── get <name>\n│   └── list <name>\n├── provider\n│   ├── create\n│   ├── get <name>\n│   ├── list\n│   ├── update <name>\n│   └── delete <name>\n├── inference\n│   ├── set\n│   ├── update\n│   └── get\n├── doctor\n│   ├── logs\n│   └── exec\n└── completions <shell>","language":"text"},{"content":"$ openshell completions bash\n$ openshell completions zsh\n$ openshell completions fish","language":"text"},{"content":"$ openshell completions zsh >> ~/.zshrc\n$ source ~/.zshrc","language":"text"},{"content":"$ openshell --help\n$ openshell sandbox --help\n$ openshell sandbox create --help\n$ openshell gateway --help","language":"text"}],"links":[],"images":[],"doc_type":"reference","section_path":["Reference","Cli"]},{"id":"reference/default-policy","title":"Default Policy Reference","url":"reference/default-policy.html","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.1.0"},"product":{"name":"OpenShell","version":"0.1.0"},"description":"Breakdown of the built-in default policy applied when you create an OpenShell sandbox without a custom policy.","tags":["ai_agents","sandboxing","security","policy"],"topics":["generative_ai","cybersecurity"],"content_type":"reference","learning_level":"technical_beginner","audience":["engineer","data_scientist"],"keywords":["openshell default policy","sandbox policy","agent compatibility"],"content":"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 file. Agent Compatibility The following table shows the coverage of the default policy for common agents. Agent Coverage Action Required Claude Code Full None. Works out of the box. OpenCode Partial Add opencode.ai endpoint and OpenCode binary paths. Codex None Provide a complete custom policy with OpenAI endpoints and Codex binary paths. If you run a non-Claude agent without a custom policy, the agent’s API calls are denied by the proxy. You must provide a policy that declares the agent’s endpoints and binaries. Default Policy Blocks The following tables show the default policy blocks pre-configured in the file. <h2>Filesystem, Landlock, and Process</h2\nSection Setting Value Filesystem Read-only /usr , /lib , /proc , /dev/urandom , /app , /etc , /var/log Read-write /sandbox , /tmp , /dev/null Workdir included Yes Landlock Compatibility best_effort (uses the highest ABI the host kernel supports) Process User / Group sandbox / sandbox <h2>Network Policy Blocks</h2\nEach block pairs a set of endpoints (host and port) with a set of binaries (executable paths inside the sandbox). The proxy identifies the calling binary by resolving the socket to a PID through /proc/net/tcp and reading /proc/{pid}/exe . A connection is allowed only when both the destination and the calling binary match an entry in the same block. All other outbound traffic is denied. <h3>Anthropic API and Telemetry</h3\nAllows Claude Code to reach its API, feature-flagging (Statsig), error reporting (Sentry), release notes, and the Claude platform dashboard. Endpoint Port TLS Access api.anthropic.com 443 terminate full statsig.anthropic.com 443 — L4 passthrough sentry.io 443 — L4 passthrough raw.githubusercontent.com 443 — L4 passthrough platform.claude.com 443 — L4 passthrough Only the following binaries can use these endpoints: /usr/local/bin/claude , /usr/bin/node . <h3>Git Clone and Fetch</h3\nAllows git clone , git fetch , and git pull over HTTPS via Git Smart HTTP. Push ( git-receive-pack ) is disabled by default. Endpoint Port TLS Rules github.com 443 terminate GET /**/info/refs* , POST /**/git-upload-pack Only the following binaries can use these endpoints: /usr/bin/git . <h3>NVIDIA API Catalog</h3\nAllows outbound calls to the NVIDIA hosted inference API. Used by agents that route LLM requests through integrate.api.nvidia.com . Endpoint Port TLS Access integrate.api.nvidia.com 443 — L4 passthrough Only the following binaries can use these endpoints: /usr/bin/curl , /bin/bash , /usr/local/bin/opencode . <h3>GitHub API (Read-Only)</h3\nGrants read-only access to the GitHub REST API. Enables issue reads, PR listing, and repository metadata lookups without allowing mutations. Endpoint Port TLS Access api.github.com 443 terminate read-only Only the following binaries can use these endpoints: /usr/local/bin/claude , /usr/bin/gh . <h3>Python Package Installation</h3\nAllows pip install and uv pip install to reach PyPI, python-build-standalone releases on GitHub, and downloads.python.org . Endpoint Port TLS Access pypi.org 443 — L4 passthrough files.pythonhosted.org 443 — L4 passthrough github.com 443 — L4 passthrough objects.githubusercontent.com 443 — L4 passthrough api.github.com 443 — L4 passthrough downloads.python.org 443 — L4 passthrough Only the following binaries can use these endpoints: /sandbox/.venv/bin/python , /sandbox/.venv/bin/python3 , /sandbox/.venv/bin/pip , /app/.venv/bin/python , /app/.venv/bin/python3 , /app/.venv/bin/pip , /usr/local/bin/uv , /sandbox/.uv/python/** . <h3>VS Code Remote and Marketplace</h3\nAllows VS Code Server, Remote Containers, and extension marketplace traffic so remote development sessions can download updates and extensions. Endpoint Port TLS Access update.code.visualstudio.com 443 — L4 passthrough az764295.vo.msecnd.net 443 — L4 passthrough vscode.download.prss.microsoft.com 443 — L4 passthrough marketplace.visualstudio.com 443 — L4 passthrough gallerycdn.vsassets.io 443 — L4 passthrough Only the following binaries can use these endpoints: /usr/bin/curl , /usr/bin/wget , /sandbox/.vscode-server/** , /sandbox/.vscode-remote-containers/** . <h3>cursor</h3\nEndpoint Port TLS Access cursor.blob.core.windows.net 443 — L4 passthrough api2.cursor.sh 443 — L4 passthrough repo.cursor.sh 443 — L4 passthrough download.cursor.sh 443 — L4 passthrough cursor.download.prss.microsoft.com 443 — L4 passthrough Only the following binaries can use these endpoints: /usr/bin/curl , /usr/bin/wget , /sandbox/.cursor-server/**","format":"text","content_length":4675,"word_count":631,"summary":"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 file.","headings":[{"text":"Default Policy Reference","level":1,"id":"default-policy-reference"},{"text":"Agent Compatibility","level":2,"id":"agent-compatibility"},{"text":"Default Policy Blocks","level":2,"id":"default-policy-blocks"}],"headings_text":"Default Policy Reference Agent Compatibility Default Policy Blocks","code_blocks":[],"links":[{"text":"Dev Sandbox Policy.Yaml","type":"external","url":"https://github.com/NVIDIA/OpenShell/blob/main/deploy/docker/sandbox/dev-sandbox-policy.yaml","original_text":"deploy/docker/sandbox/dev-sandbox-policy.yaml"}],"images":[],"doc_type":"reference","section_path":["Reference","Default Policy"]},{"id":"reference/policy-schema","title":"Policy Schema Reference","url":"reference/policy-schema.html","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.1.0"},"product":{"name":"OpenShell","version":"0.1.0"},"description":"Complete field reference for the sandbox policy YAML including static and dynamic sections.","tags":["Policy","Schema","YAML","Reference","Security"],"topics":["Generative AI","Cybersecurity"],"content_type":"reference","learning_level":"technical_advanced","audience":["engineer"],"content":"Policy Schema Reference Complete field reference for the sandbox policy YAML. Each field is documented with its type, whether it is required, and whether it is static (locked at sandbox creation) or dynamic (hot-reloadable on a running sandbox). Top-Level Structure A policy YAML file contains the following top-level fields: version: 1\nfilesystem_policy: { ...\nlandlock: { ...\nprocess: { ...\nnetwork_policies: { ...\nField Type Required Category Description version integer Yes – Policy schema version. Must be 1 . filesystem_policy object No Static Controls which directories the agent can read and write. landlock object No Static Configures Landlock LSM enforcement behavior. process object No Static Sets the user and group the agent process runs as. network_policies map No Dynamic Declares which binaries can reach which network endpoints. Static fields are set at sandbox creation time. Changing them requires destroying and recreating the sandbox. Dynamic fields can be updated on a running sandbox with openshell policy set and take effect without restarting. Version The version field identifies which schema the policy uses: Field Type Required Description version integer Yes Schema version number. Currently must be 1 . Filesystem Policy Category: Static Controls filesystem access inside the sandbox. Paths not listed in either read_only or read_write are inaccessible. Field Type Required Description include_workdir bool No When true , automatically adds the agent’s working directory to read_write . read_only list of strings No Paths the agent can read but not modify. Typically system directories like /usr , /lib , /etc . read_write list of strings No Paths the agent can read and write. Typically /sandbox (working directory) and /tmp . Validation constraints: Every path must be absolute (start with / ). Paths must not contain .. traversal components. The server normalizes paths before storage, but rejects policies where traversal would escape the intended scope. Read-write paths must not be overly broad (for example, / alone is rejected). Each individual path must not exceed 4096 characters. The combined total of read_only and read_write paths must not exceed 256. Policies that violate these constraints are rejected with INVALID_ARGUMENT at creation or update time. Disk-loaded YAML policies that fail validation fall back to a restrictive default. Example: filesystem_policy\ninclude_workdir: true\nread_only\n/usr\n/lib\n/proc\n/dev/urandom\n/etc\nread_write\n/sandbox\n/tmp\n/dev/null\nLandlock Category: Static Configures Landlock LSM enforcement at the kernel level. Landlock provides mandatory filesystem access control below what UNIX permissions allow. Field Type Required Values Description compatibility string No best_effort , hard_requirement How OpenShell handles kernel ABI differences. best_effort uses the highest Landlock ABI the host kernel supports. hard_requirement fails if the required ABI is unavailable. Example: landlock\ncompatibility: best_effort\nProcess Category: Static Sets the OS-level identity for the agent process inside the sandbox. Field Type Required Description run_as_user string No The user name or UID the agent process runs as. Default: sandbox . run_as_group string No The group name or GID the agent process runs as. Default: sandbox . Validation constraint: Neither run_as_user nor run_as_group may be set to root or 0 . Policies that request root process identity are rejected at creation or update time. Example: process\nrun_as_user: sandbox\nrun_as_group: sandbox\nNetwork Policies Category: Dynamic A map of named network policy entries. Each entry declares a set of endpoints and a set of binaries. Only the listed binaries are permitted to connect to the listed endpoints. The map key is a logical identifier. The name field inside the entry is the display name used in logs. 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. endpoints list of endpoint objects Yes Hosts and ports this entry permits. binaries list of binary objects Yes Executables allowed to connect to these endpoints. Endpoint Object Each endpoint defines a reachable destination and optional inspection rules. Field Type Required Description host string Yes Hostname or IP address. Supports wildcards: *.example.com matches any subdomain. port integer Yes TCP port number. protocol string No Set to rest to enable HTTP request inspection. Omit for TCP passthrough. tls string No TLS handling mode. terminate decrypts TLS at the proxy for inspection. passthrough forwards encrypted traffic without inspection. Only relevant when protocol is rest . enforcement string No enforce actively blocks disallowed requests. audit logs violations but allows traffic through. access string No HTTP access level. One of read-only , read-write , or full . Mutually exclusive with rules . rules list of rule objects No Fine-grained per-method, per-path allow rules. Mutually exclusive with access . Access Levels The access field accepts one of the following values: Value Allowed HTTP Methods full All methods and paths. read-only GET , HEAD , OPTIONS . read-write GET , HEAD , OPTIONS , POST , PUT , PATCH . Rule Object Used when access is not set. Each rule explicitly allows a method and path combination. Field Type Required Description allow.method string Yes HTTP method to allow (for example, GET , POST ). allow.path string Yes URL path pattern. Supports * and ** glob syntax. Example with rules: rules\nallow\nmethod: GET\npath: /**/info/refs\nallow\nmethod: POST\npath: /**/git-upload-pack\nBinary Object Identifies an executable that is permitted to use the associated endpoints. Field Type Required Description path string Yes Filesystem path to the executable. Supports glob patterns with * and ** . For example, /sandbox/.vscode-server/** matches any executable under that directory tree. Full Example The following policy grants read-only GitHub API access and npm registry access: network_policies\ngithub_rest_api\nname: github-rest-api\nendpoints\nhost: api.github.com\nport: 443\nprotocol: rest\ntls: terminate\nenforcement: enforce\naccess: read-only\nbinaries\npath: /usr/local/bin/claude\npath: /usr/bin/node\npath: /usr/bin/gh\nnpm_registry\nname: npm-registry\nendpoints\nhost: registry.npmjs.org\nport: 443\nbinaries\npath: /usr/bin/npm\npath: /usr/bin/node","format":"text","content_length":6442,"word_count":955,"summary":"Complete field reference for the sandbox policy YAML. Each field is documented with its type, whether it is required, and whether it is static (locked at sandbox creation) or dynamic (hot-reloadable on a running sandbox).","headings":[{"text":"Policy Schema Reference","level":1,"id":"policy-schema-reference"},{"text":"Top-Level Structure","level":2,"id":"top-level-structure"},{"text":"Version","level":2,"id":"version"},{"text":"Filesystem Policy","level":2,"id":"filesystem-policy"},{"text":"Landlock","level":2,"id":"landlock"},{"text":"Process","level":2,"id":"process"},{"text":"Network Policies","level":2,"id":"network-policies"},{"text":"Network Policy Entry","level":3,"id":"network-policy-entry"},{"text":"Endpoint Object","level":3,"id":"endpoint-object"},{"text":"Access Levels","level":4,"id":"access-levels"},{"text":"Rule Object","level":4,"id":"rule-object"},{"text":"Binary Object","level":3,"id":"binary-object"},{"text":"Full Example","level":3,"id":"full-example"}],"headings_text":"Policy Schema Reference Top-Level Structure Version Filesystem Policy Landlock Process Network Policies Network Policy Entry Endpoint Object Access Levels Rule Object Binary Object Full Example","keywords":["access","allowed","binary","category","changing","com","compatibility","complete","configures","constraint","constraints","controls","currently","declares","default","defaults","description","disk","display","dynamic","each","endpoint","enforcement","entry","every","example","executables","field","fields","filesystem","filesystem_policy","fine","full","github","host","hostname","hosts","identifies","include_workdir","landlock","level","levels","method","methods","must","mutually","name","neither","network","network_policies"],"code_blocks":[{"content":"version: 1\nfilesystem_policy: { ... }\nlandlock: { ... }\nprocess: { ... }\nnetwork_policies: { ... }","language":"text"},{"content":"filesystem_policy:\n  include_workdir: true\n  read_only:\n    - /usr\n    - /lib\n    - /proc\n    - /dev/urandom\n    - /etc\n  read_write:\n    - /sandbox\n    - /tmp\n    - /dev/null","language":"text"},{"content":"landlock:\n  compatibility: best_effort","language":"text"},{"content":"process:\n  run_as_user: sandbox\n  run_as_group: sandbox","language":"text"},{"content":"rules:\n  - allow:\n      method: GET\n      path: /**/info/refs*\n  - allow:\n      method: POST\n      path: /**/git-upload-pack","language":"text"},{"content":"network_policies:\n  github_rest_api:\n    name: github-rest-api\n    endpoints:\n      - host: api.github.com\n        port: 443\n        protocol: rest\n        tls: terminate\n        enforcement: enforce\n        access: read-only\n    binaries:\n      - path: /usr/local/bin/claude\n      - path: /usr/bin/node\n      - path: /usr/bin/gh\n  npm_registry:\n    name: npm-registry\n    endpoints:\n      - host: registry.npmjs.org\n        port: 443\n    binaries:\n      - path: /usr/bin/npm\n      - path: /usr/bin/node","language":"text"}],"links":[{"text":"Landlock LSM","type":"external","url":"https://docs.kernel.org/security/landlock.html"}],"images":[],"doc_type":"reference","section_path":["Reference","Policy Schema"]},{"id":"reference/support-matrix","title":"Support Matrix","url":"reference/support-matrix.html","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.1.0"},"product":{"name":"OpenShell","version":"0.1.0"},"content":"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 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 Gateway ghcr.io ghcr.io/nvidia/openshell/gateway:latest Cluster startup (via Helm chart) Sandbox ghcr.io ghcr.io/nvidia/openshell/sandbox:latest First sandbox creation (via Helm chart) Community sandboxes GHCR ghcr.io/nvidia/openshell-community/sandboxes/{name}:latest openshell sandbox create --from <name> 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 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 table","format":"text","content_length":3060,"word_count":402,"summary":"This page lists the platform, software, runtime, and kernel requirements for running OpenShell.","headings":[{"text":"Support Matrix","level":1,"id":"support-matrix"},{"text":"Supported Platforms","level":2,"id":"supported-platforms"},{"text":"Software Prerequisites","level":2,"id":"software-prerequisites"},{"text":"Sandbox Runtime Versions","level":2,"id":"sandbox-runtime-versions"},{"text":"Container Images","level":2,"id":"container-images"},{"text":"Kernel Requirements","level":2,"id":"kernel-requirements"},{"text":"Agent Compatibility","level":2,"id":"agent-compatibility"}],"headings_text":"Support Matrix Supported Platforms Software Prerequisites Sandbox Runtime Versions Container Images Kernel Requirements Agent Compatibility","keywords":["agent","agents","apple","architecture","available","base","bookworm","claude","cluster","code","codex","community","compatibility","component","container","debian","desktop","details","docker","enforces","engine","filters","first","gateway","helm","image","images","intel","k3s","kernel","kubernetes","landlock","latest","linux","matrix","minimum","module","modules","must","node","notes","opencode","openshell","override","platform","platforms","prerequisites","pulled","purpose","python"],"code_blocks":[],"links":[{"text":"Uv","type":"external","url":"https://docs.astral.sh/uv/","original_text":"uv"},{"text":"Landlock LSM","type":"external","url":"https://docs.kernel.org/security/landlock.html"}],"images":[],"doc_type":"reference","section_path":["Reference","Support Matrix"]},{"id":"resources/eula","title":"License","url":"resources/eula.html","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.1.0"},"product":{"name":"OpenShell","version":"0.1.0"},"description":"NVIDIA OpenShell license agreement and terms of use.","tags":["License","EULA"],"topics":["Legal"],"content_type":"reference","learning_level":"technical_beginner","audience":["engineer","data_scientist"],"content":"License","format":"text","content_length":7,"word_count":1,"summary":"<!-- SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. SPDX-License-Identifier: Apache-2.0 --> License","headings":[{"text":"License","level":1,"id":"license"}],"headings_text":"License","keywords":["license"],"code_blocks":[],"links":[],"images":[],"doc_type":"documentation","section_path":["Resources","Eula"]},{"id":"sandboxes/community-sandboxes","title":"Community Sandboxes","url":"sandboxes/community-sandboxes.html","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.1.0"},"product":{"name":"OpenShell","version":"0.1.0"},"description":"Use pre-built sandboxes from the OpenShell Community catalog or contribute your own.","tags":["Community","Sandbox","Container Image","Open Source"],"topics":["Generative AI","Cybersecurity"],"content_type":"concept","learning_level":"technical_beginner","audience":["engineer","data_scientist"],"content":"Community Sandboxes Use pre-built sandboxes from the OpenShell Community catalog, or contribute your\nown. What Are Community Sandboxes Community sandboxes are ready-to-use environments published in the\nOpenShell Community repository\nEach sandbox bundles a Dockerfile, policy, optional skills, and startup scripts\ninto a single package that you can launch with one command. Current Catalog The following community sandboxes are available in the catalog. Sandbox Description base Foundational image with system tools and dev environment openclaw Open agent manipulation and control sdg Synthetic data generation workflows simulation General-purpose simulation sandboxes Use a Community Sandbox Launch a community sandbox by name with the --from flag: $ openshell sandbox create --from openclaw\nWhen you pass --from with a community sandbox name, the CLI: Resolves the name against the\nOpenShell Community repository. Pulls the Dockerfile, policy, skills, and any startup scripts. Builds the container image locally. Creates the sandbox with the bundled configuration applied. You end up with a running sandbox whose image, policy, and tooling are all\npreconfigured by the community package. Other Sources The --from flag also accepts: Local directory paths: Point to a directory on disk that contains a\nDockerfile and optional policy/skills: $ openshell sandbox create --from ./my-sandbox-dir\nContainer image references: Use an existing container image directly: $ openshell sandbox create --from my-registry.example.com/my-image:latest\nContribute a Community Sandbox Each community sandbox is a directory under sandboxes/ in the\nOpenShell Community repository\nAt minimum, a sandbox directory must contain: Dockerfile : Defines the container image README.md : Describes the sandbox and how to use it Optional files: policy.yaml : Default policy applied when the sandbox launches skills/ : Agent skill definitions bundled with the sandbox Startup scripts: Any scripts the Dockerfile or entrypoint invokes To contribute, fork the repository, add your sandbox directory, and open a pull\nrequest. Refer to the repository’s\nCONTRIBUTING.md\nfor submission guidelines. The community catalog is designed to grow. If you have built a sandbox that\nsupports a particular workflow (data processing, simulation, code review\nor 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 providers for credential management. Want to customize the sandbox policy? Write custom rules in policies","format":"text","content_length":2562,"word_count":367,"summary":"Use pre-built sandboxes from the OpenShell Community catalog, or contribute your own.","headings":[{"text":"Community Sandboxes","level":1,"id":"community-sandboxes"},{"text":"What Are Community Sandboxes","level":2,"id":"what-are-community-sandboxes"},{"text":"Current Catalog","level":2,"id":"current-catalog"},{"text":"Use a Community Sandbox","level":2,"id":"use-a-community-sandbox"},{"text":"Other Sources","level":3,"id":"other-sources"},{"text":"Contribute a Community Sandbox","level":2,"id":"contribute-a-community-sandbox"},{"text":"Next Steps","level":2,"id":"next-steps"}],"headings_text":"Community Sandboxes What Are Community Sandboxes Current Catalog Use a Community Sandbox Other Sources Contribute a Community Sandbox Next Steps","keywords":["accepts","agent","any","builds","catalog","com","community","contain","container","contribute","creates","current","default","defines","describes","description","directly","dockerfile","each","explore","files","flag","foundational","general","image","launch","local","need","next","open","openshell","optional","other","paths","point","pulls","refer","references","resolves","sandbox","sandboxes","scripts","set","skills","sources","startup","steps","synthetic","topics","want"],"code_blocks":[{"content":"$ openshell sandbox create --from openclaw","language":"text"},{"content":"$ openshell sandbox create --from ./my-sandbox-dir","language":"text"},{"content":"$ openshell sandbox create --from my-registry.example.com/my-image:latest","language":"text"}],"links":[{"text":"OpenShell Community","type":"external","url":"https://github.com/NVIDIA/OpenShell-Community"},{"text":"OpenShell Community","type":"external","url":"https://github.com/NVIDIA/OpenShell-Community"},{"text":"OpenShell Community","type":"external","url":"https://github.com/NVIDIA/OpenShell-Community"},{"text":"Contributing","type":"external","url":"https://github.com/NVIDIA/OpenShell-Community/blob/main/CONTRIBUTING.md","original_text":"CONTRIBUTING.md"}],"images":[],"doc_type":"tutorial","section_path":["Sandboxes","Community Sandboxes"]},{"id":"sandboxes/create-and-manage","title":"Create and Manage Sandboxes","url":"sandboxes/create-and-manage.html","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.1.0"},"product":{"name":"OpenShell","version":"0.1.0"},"description":"Create, inspect, connect to, monitor, transfer files, and delete OpenShell sandboxes.","tags":["Sandboxing","AI Agents","Sandbox Management","CLI"],"topics":["Generative AI","Cybersecurity"],"content_type":"how_to","learning_level":"technical_beginner","audience":["engineer","data_scientist"],"content":"Create and Manage Sandboxes 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 . Docker must be running before you create a sandbox. If it is not, the CLI\nreturns a connection-refused error ( os error 61 ) without explaining\nthe cause. Start Docker and try again. Create a Sandbox Run a single command to create a sandbox and launch your agent: $ openshell sandbox create -- claude\nIf you have an existing gateway, the sandbox is created in it. Otherwise, a gateway is created automatically. To request GPU resources explicitly, add --gpu : $ openshell sandbox create --gpu -- claude\nIf no gateway is running, the auto-bootstrap path starts a GPU-enabled gateway first. A fully specified creation command might look like: $ openshell sandbox create\nname dev\nprovider my-claude\npolicy policy.yaml\nupload\nkeep\nclaude\nUse --keep to keep the sandbox running after the trailing command exits\nThis is especially useful when you are iterating on a policy or want to\nreconnect later from another terminal or VS Code. Create from a Community Sandbox or Custom Image Use --from to create a sandbox from a pre-built community package, a local directory, or a container image: $ openshell sandbox create --from openclaw\nThe CLI resolves the name against the OpenShell Community catalog, pulls the bundled Dockerfile and policy, builds the image locally, and creates the sandbox. For the full catalog and how to contribute your own, refer to community-sandboxes . You can also point --from at a local directory or a container image reference: $ openshell sandbox create --from ./my-sandbox-dir\nopenshell sandbox create --from my-registry.example.com/my-image:latest\nImages whose final name component contains gpu also trigger GPU sandbox requests automatically. For example, --from nvidia-gpu behaves like a GPU sandbox request even without --gpu . List and Inspect Sandboxes Check the status of your sandboxes and retrieve detailed information about individual ones. List all sandboxes: $ openshell sandbox list\nGet detailed information about a specific sandbox: $ openshell sandbox get my-sandbox\nConnect to a Sandbox Access a running sandbox through an interactive SSH session or VS Code Remote-SSH. Interactive SSH Open an SSH session into a running sandbox: $ openshell sandbox connect my-sandbox\nOpen in a remote editor Launch VS Code or Cursor directly into the sandbox workspace: $ openshell sandbox create --editor vscode --name my-sandbox\nopenshell sandbox connect my-sandbox --editor cursor\nWhen --editor is used, OpenShell keeps the sandbox alive and installs an\nOpenShell-managed SSH include file instead of cluttering your main\nssh/config with generated host blocks. View Logs Stream and filter sandbox logs to monitor agent activity and diagnose policy decisions. Stream sandbox logs: $ openshell logs my-sandbox\nUse flags to filter and follow output: Flag Purpose Example --tail Stream logs in real time openshell logs my-sandbox --tail --source Filter by log source --source sandbox --level Filter by severity --level warn --since Show logs from a time window --since 5m Monitor Your Sandbox OpenShell Terminal is a real-time dashboard that combines sandbox status and live logs in a single view. $ openshell term\nThe dashboard shows the following information. 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 policies for the workflow. Transfer Files Transfer files between your host machine and a running sandbox. Upload files from your host into the sandbox: $ openshell sandbox upload my-sandbox ./src /sandbox/src\nDownload files from the sandbox to your host: $ openshell sandbox download my-sandbox /sandbox/output ./local\nYou can also upload files at creation time with the --upload flag on\nopenshell sandbox create . Delete Sandboxes Remove sandboxes when they are no longer needed. Deleting a sandbox stops all processes, releases cluster resources, and purges injected credentials. Delete a sandbox by name: $ openshell sandbox delete my-sandbox\nDelete all sandboxes in the active gateway: $ openshell sandbox delete --all\nNext Steps Explore related topics: To follow a complete end-to-end example, refer to the /tutorials/github-sandbox tutorial. To supply API keys or tokens, refer to providers . To control what the agent can access, refer to policies . To use a pre-built environment, refer to the community-sandboxes catalog","format":"text","content_length":4970,"word_count":758,"summary":"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.","headings":[{"text":"Create and Manage Sandboxes","level":1,"id":"create-and-manage-sandboxes"},{"text":"Create a Sandbox","level":2,"id":"create-a-sandbox"},{"text":"Create from a Community Sandbox or Custom Image","level":2,"id":"create-from-a-community-sandbox-or-custom-image"},{"text":"List and Inspect Sandboxes","level":2,"id":"list-and-inspect-sandboxes"},{"text":"Connect to a Sandbox","level":2,"id":"connect-to-a-sandbox"},{"text":"Interactive SSH","level":3,"id":"interactive-ssh"},{"text":"Open in a remote editor","level":3,"id":"open-in-a-remote-editor"},{"text":"View Logs","level":2,"id":"view-logs"},{"text":"Monitor Your Sandbox","level":2,"id":"monitor-your-sandbox"},{"text":"Transfer Files","level":2,"id":"transfer-files"},{"text":"Delete Sandboxes","level":2,"id":"delete-sandboxes"},{"text":"Next Steps","level":2,"id":"next-steps"}],"headings_text":"Create and Manage Sandboxes Create a Sandbox Create from a Community Sandbox or Custom Image List and Inspect Sandboxes Connect to a Sandbox Interactive SSH Open in a remote editor View Logs Monitor Your Sandbox Transfer Files Delete Sandboxes Next Steps","keywords":["about","access","action","agent","check","code","com","community","connect","create","cursor","custom","delete","deleting","docker","dockerfile","download","editor","example","explore","files","filter","flag","from","gateway","gpu","host","image","images","inspect","interactive","launch","lifecycle","like","list","live","logs","manage","monitor","name","next","omutbound","open","openshell","otherwise","output","purpose","reference","remote","remove"],"code_blocks":[{"content":"$ openshell sandbox create -- claude","language":"text"},{"content":"$ openshell sandbox create --gpu -- claude","language":"text"},{"content":"$ openshell sandbox create \\\n    --name dev \\\n    --provider my-claude \\\n    --policy policy.yaml \\\n    --upload \\\n    --keep \\\n    -- claude","language":"text"},{"content":"$ openshell sandbox create --from openclaw","language":"text"},{"content":"$ openshell sandbox create --from ./my-sandbox-dir\n$ openshell sandbox create --from my-registry.example.com/my-image:latest","language":"text"},{"content":"$ openshell sandbox list","language":"text"},{"content":"$ openshell sandbox get my-sandbox","language":"text"},{"content":"$ openshell sandbox connect my-sandbox","language":"text"},{"content":"$ openshell sandbox create --editor vscode --name my-sandbox\n$ openshell sandbox connect my-sandbox --editor cursor","language":"text"},{"content":"$ openshell logs my-sandbox","language":"text"},{"content":"$ openshell term","language":"text"},{"content":"$ openshell sandbox upload my-sandbox ./src /sandbox/src","language":"text"},{"content":"$ openshell sandbox download my-sandbox /sandbox/output ./local","language":"text"},{"content":"$ openshell sandbox delete my-sandbox","language":"text"},{"content":"$ openshell sandbox delete --all","language":"text"}],"links":[{"text":"OpenShell Community","type":"external","url":"https://github.com/NVIDIA/OpenShell-Community"}],"images":[],"doc_type":"tutorial","section_path":["Sandboxes","Create And Manage"]},{"id":"sandboxes/index","title":"About Sandboxes","url":"sandboxes/index.html","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.1.0"},"product":{"name":"OpenShell","version":"0.1.0"},"description":"Understand sandbox lifecycle, supported agents, built-in default policy, and network access rules in OpenShell.","tags":["Sandboxing","AI Agents","Security","Policy","Isolation"],"topics":["Generative AI","Cybersecurity"],"content_type":"concept","learning_level":"technical_beginner","audience":["engineer","data_scientist"],"content":"About Sandboxes An OpenShell sandbox is a safe, private execution environment for an AI agent. Each sandbox runs with multiple layers of protection that prevent unauthorized data access, credential exposure, and network exfiltration. Protection layers include filesystem restrictions (Landlock), system call filtering (seccomp), network namespace isolation, and a privacy-enforcing HTTP CONNECT proxy. Sandbox Lifecycle Every sandbox moves through a defined set of phases: Phase Description Provisioning The runtime is setting up the sandbox environment, injecting credentials, and applying your policy. Ready The sandbox is running. The agent process is active and all isolation layers are enforced. You can connect, sync files, and view logs. 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 community-sandboxes catalog. Agent Source Default Policy Notes Claude Code Built-in Full coverage Works out of the box. Requires ANTHROPIC_API_KEY . OpenCode Built-in Partial coverage Pre-installed. Add opencode.ai endpoint and OpenCode binary paths to the policy for full functionality. Codex Built-in No coverage Pre-installed. Requires a custom policy with OpenAI endpoints and Codex binary paths. Requires OPENAI_API_KEY . OpenClaw OpenShell Community Bundled Agent orchestration layer. Launch with openshell sandbox create --from openclaw\nBuilt-in Default Policy OpenShell ships a built-in policy that covers common agent workflows out of the box\nWhen you create a sandbox without --policy , the default policy is applied. It controls three things: Layer What It Controls How It Works Filesystem What the agent can access on disk Paths are split into read-only and read-write sets. Landlock LSM enforces these restrictions at the kernel level. 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, refer to ../reference/default-policy . Policy Structure A policy has static sections ( filesystem_policy , landlock , process ) that are locked at sandbox creation, and dynamic sections ( network_policies , inference ) that are hot-reloadable on a running sandbox. version: 1\nStatic: locked at sandbox creation. Paths the agent can read vs read/write\nfilesystem_policy\nread_only: [/usr, /lib, /etc\nread_write: [/sandbox, /tmp\nStatic: Landlock LSM kernel enforcement. best_effort uses highest ABI the host supports\nlandlock\ncompatibility: best_effort\nStatic: Unprivileged user/group the agent process runs as\nprocess\nrun_as_user: sandbox\nrun_as_group: sandbox\nDynamic: hot-reloadable. Named blocks of endpoints + binaries allowed to reach them\nnetwork_policies\nmy_api\nname: my-api\nendpoints\nhost: api.example.com\nport: 443\nprotocol: rest\ntls: terminate\nenforcement: enforce\naccess: full\nbinaries\npath: /usr/bin/curl\nDynamic: hot-reloadable. Routing hints this sandbox can use for inference (e.g. local, nvidia\ninference\nallowed_routes: [local\nFor the complete structure and every field, refer to the Policy Schema Reference . 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. Every outbound connection from the sandbox goes through the proxy: The proxy queries the policy engine 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 Continue with one of the following: To create your first sandbox, refer to create-and-manage . To supply API keys or tokens, refer to providers . To control what the agent can access, refer to policies . To use a pre-built environment, refer to the community-sandboxes catalog","format":"text","content_length":4999,"word_count":737,"summary":"An OpenShell sandbox is a safe, private execution environment for an AI agent. Each sandbox runs with multiple layers of protection that prevent unauthorized data access, credential exposure, and network exfiltration. Protection layers include filesystem restrictions (Landlock), system call filte...","headings":[{"text":"About Sandboxes","level":1,"id":"about-sandboxes"},{"text":"Sandbox Lifecycle","level":2,"id":"sandbox-lifecycle"},{"text":"Supported Agents","level":2,"id":"supported-agents"},{"text":"Built-in Default Policy","level":2,"id":"built-in-default-policy"},{"text":"Policy Structure","level":2,"id":"policy-structure"},{"text":"Network Access Rules","level":2,"id":"network-access-rules"},{"text":"Next Steps","level":2,"id":"next-steps"}],"headings_text":"About Sandboxes Sandbox Lifecycle Supported Agents Built-in Default Policy Policy Structure Network Access Rules Next Steps","keywords":["about","access","add","agent","agents","allowed_routes","both","built","bundled","check","claude","code","codex","com","community","compatibility","continue","controls","default","deleting","description","dynamic","each","endpoints","enforcement","error","every","filesystem","following","full","host","landlock","launch","layer","lifecycle","more","name","named","network","next","notes","openai","openclaw","opencode","openshell","otherwise","partial","path","paths","phase"],"code_blocks":[{"content":"version: 1\n\n# Static: locked at sandbox creation. Paths the agent can read vs read/write.\nfilesystem_policy:\n  read_only: [/usr, /lib, /etc]\n  read_write: [/sandbox, /tmp]\n\n# Static: Landlock LSM kernel enforcement. best_effort uses highest ABI the host supports.\nlandlock:\n  compatibility: best_effort\n\n# Static: Unprivileged user/group the agent process runs as.\nprocess:\n  run_as_user: sandbox\n  run_as_group: sandbox\n\n# Dynamic: hot-reloadable. Named blocks of endpoints + binaries allowed to reach them.\nnetwork_policies:\n  my_api:\n    name: my-api\n    endpoints:\n      - host: api.example.com\n        port: 443\n        protocol: rest\n        tls: terminate\n        enforcement: enforce\n        access: full\n    binaries:\n      - path: /usr/bin/curl\n\n# Dynamic: hot-reloadable. Routing hints this sandbox can use for inference (e.g. local, nvidia).\ninference:\n  allowed_routes: [local]","language":"text"}],"links":[{"text":"Claude Code","type":"external","url":"https://docs.anthropic.com/en/docs/claude-code"},{"text":"OpenCode","type":"external","url":"https://opencode.ai/"},{"text":"Codex","type":"external","url":"https://developers.openai.com/codex"},{"text":"OpenClaw","type":"external","url":"https://openclaw.ai/"},{"text":"OpenShell Community","type":"external","url":"https://github.com/NVIDIA/OpenShell-Community/tree/main/sandboxes/openclaw"},{"text":"Landlock LSM","type":"external","url":"https://docs.kernel.org/security/landlock.html"}],"images":[],"doc_type":"overview","section_path":["Sandboxes"]},{"id":"sandboxes/policies","title":"Customize Sandbox Policies","url":"sandboxes/policies.html","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.1.0"},"product":{"name":"OpenShell","version":"0.1.0"},"description":"Apply, iterate, and debug sandbox network policies with hot-reload on running OpenShell sandboxes.","tags":["Policy","Network Policy","Sandbox","Security","Hot Reload"],"topics":["Generative AI","Cybersecurity"],"content_type":"how_to","learning_level":"technical_intermediate","audience":["engineer"],"content":"Customize Sandbox Policies Use this page to apply and iterate policy changes on running sandboxes. For a full field-by-field YAML definition, use the Policy Schema Reference . Quick Start: Apply a Custom Policy Pass a policy YAML file when creating the sandbox: $ openshell sandbox create --policy ./my-policy.yaml --keep -- claude\nThe --keep flag keeps the sandbox running after the initial command exits, which is useful when you plan to iterate on the policy. To avoid passing --policy every time, set a default policy with an environment variable: $ export OPENSHELL_SANDBOX_POLICY=./my-policy.yaml\nopenshell sandbox create --keep -- claude\nThe CLI uses the policy from OPENSHELL_SANDBOX_POLICY whenever --policy is not explicitly provided. Iterate on a Running Sandbox To change what the sandbox can access, pull the current policy, edit the YAML, and push the update. The workflow is iterative: create the sandbox, monitor logs for denied actions, pull the policy, modify it, push, and verify. The following steps outline the hot-reload policy update workflow. Create the sandbox with your initial policy by following Quick Start: Apply a Custom Policy above (or set OPENSHELL_SANDBOX_POLICY ). Monitor denials. Each log entry shows host, port, binary, and reason. Alternatively, use openshell term for a live dashboard. $ openshell logs <name> --tail --source sandbox\nPull the current policy. Strip the metadata header (Version, Hash, Status) before reusing the file. $ openshell policy get <name> --full > current-policy.yaml\nEdit the YAML: add or adjust network_policies entries, binaries, access or rules , or inference.allowed_routes . Push the updated policy. Exit codes: 0 = loaded, 1 = validation failed, 124 = timeout. $ openshell policy set <name> --policy current-policy.yaml --wait\nVerify the new revision. If status is loaded , repeat from step 2 as needed; if failed , fix the policy and repeat from step 4. $ openshell policy list <name\nDebug Denied Requests Check openshell logs <name> --tail --source sandbox for the denied host, path, and binary. When triaging denied requests, check: Destination host and port to confirm which endpoint is missing. Calling binary path to confirm which binaries entry needs to be added or adjusted. HTTP method and path (for REST endpoints) to confirm which rules entry needs to be added or adjusted. Then push the updated policy as described above. Examples Add these blocks to the network_policies section of your sandbox policy. Apply with openshell policy set <name> --policy <file> --wait\nUse Simple endpoint for host-level allowlists and Granular rules for method/path control. Simple endpoint Allow pip install and uv pip install to reach PyPI: pypi\nname: pypi\nendpoints\nhost: pypi.org\nport: 443\nhost: files.pythonhosted.org\nport: 443\nbinaries\n{ path: /usr/bin/pip\n{ path: /usr/local/bin/uv\nEndpoints without protocol or tls use TCP passthrough — the proxy allows the stream without inspecting payloads. Granular rules 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 <org_name> with your GitHub org or username. For an end-to-end walkthrough that combines this policy with a GitHub credential provider and sandbox creation, refer to /tutorials/github-sandbox . github_repos\nname: github_repos\nendpoints\nhost: api.github.com\nport: 443\nprotocol: rest\ntls: terminate\nenforcement: enforce\nrules\nallow\nmethod: GET\npath:\nallow\nmethod: HEAD\npath:\nallow\nmethod: OPTIONS\npath:\nallow\nmethod: POST\npath: \"/graphql\nallow\nmethod:\npath: \"/repos/<org_name>/alpha-repo\nallow\nmethod: POST\npath: \"/repos/<org_name>/bravo-repo/issues\nallow\nmethod: PATCH\npath: \"/repos/<org_name>/bravo-repo/issues\nbinaries\n{ path: /usr/local/bin/claude\n{ path: /usr/bin/gh\nEndpoints with protocol: rest and tls: terminate enable HTTP request inspection — the proxy decrypts TLS and checks each HTTP request against the rules list. Next Steps Explore related topics: To learn about policy structure and network access rules, refer to index . To view the full field-by-field YAML definition, refer to the Policy Schema Reference . To review the default policy breakdown, refer to ../reference/default-policy","format":"text","content_length":4315,"word_count":639,"summary":"Use this page to apply and iterate policy changes on running sandboxes. For a full field-by-field YAML definition, use the Policy Schema Reference.","headings":[{"text":"Customize Sandbox Policies","level":1,"id":"customize-sandbox-policies"},{"text":"Quick Start: Apply a Custom Policy","level":2,"id":"quick-start-apply-a-custom-policy"},{"text":"Iterate on a Running Sandbox","level":2,"id":"iterate-on-a-running-sandbox"},{"text":"Debug Denied Requests","level":2,"id":"debug-denied-requests"},{"text":"Examples","level":2,"id":"examples"},{"text":"Next Steps","level":2,"id":"next-steps"}],"headings_text":"Customize Sandbox Policies Quick Start: Apply a Custom Policy Iterate on a Running Sandbox Debug Denied Requests Examples Next Steps","keywords":["add","allow","alternatively","apply","calling","check","claude","codes","com","create","custom","customize","debug","denied","destination","each","edit","endpoints","enforcement","examples","exit","explore","github","granular","graphql","hash","host","iterate","iterative","method","monitor","name","next","org","pass","path","policies","policy","port","protocol","pull","push","pypi","quick","reference","replace","requests","rules","running","sandbox"],"code_blocks":[{"content":"$ openshell sandbox create --policy ./my-policy.yaml --keep -- claude","language":"text"},{"content":"$ export OPENSHELL_SANDBOX_POLICY=./my-policy.yaml\n$ openshell sandbox create --keep -- claude","language":"text"},{"content":"$ openshell logs <name> --tail --source sandbox","language":"text"},{"content":"$ openshell policy get <name> --full > current-policy.yaml","language":"text"},{"content":"$ openshell policy set <name> --policy current-policy.yaml --wait","language":"text"},{"content":"$ openshell policy list <name>","language":"text"},{"content":"pypi:\n    name: pypi\n    endpoints:\n      - host: pypi.org\n        port: 443\n      - host: files.pythonhosted.org\n        port: 443\n    binaries:\n      - { path: /usr/bin/pip }\n      - { path: /usr/local/bin/uv }","language":"text"},{"content":"github_repos:\n    name: github_repos\n    endpoints:\n      - host: api.github.com\n        port: 443\n        protocol: rest\n        tls: terminate\n        enforcement: enforce\n        rules:\n          - allow:\n              method: GET\n              path: \"/**\"\n          - allow:\n              method: HEAD\n              path: \"/**\"\n          - allow:\n              method: OPTIONS\n              path: \"/**\"\n          - allow:\n              method: POST\n              path: \"/graphql\"\n          - allow:\n              method: \"*\"\n              path: \"/repos/<org_name>/alpha-repo/**\"\n          - allow:\n              method: POST\n              path: \"/repos/<org_name>/bravo-repo/issues\"\n          - allow:\n              method: PATCH\n              path: \"/repos/<org_name>/bravo-repo/issues/*\"\n    binaries:\n      - { path: /usr/local/bin/claude }\n      - { path: /usr/bin/gh }","language":"text"}],"links":[{"text":"Quick Start: Apply a Custom Policy","type":"anchor","url":"#quick-start-apply-a-custom-policy"}],"images":[],"doc_type":"tutorial","section_path":["Sandboxes","Policies"]},{"id":"sandboxes/providers","title":"Providers","url":"sandboxes/providers.html","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.1.0"},"product":{"name":"OpenShell","version":"0.1.0"},"description":"Create and manage credential providers that inject API keys and tokens into OpenShell sandboxes.","tags":["Providers","Credentials","API Keys","Sandbox","Security"],"topics":["Generative AI","Cybersecurity"],"content_type":"how_to","learning_level":"technical_beginner","audience":["engineer","data_scientist"],"content":"Providers AI agents typically need credentials to access external services: an API key for the AI model provider, a token for GitHub or GitLab, and so on. OpenShell manages these credentials as first-class entities called providers . Create and manage providers that supply credentials to sandboxes. Create a Provider Providers can be created from local environment variables or with explicit credential values. From Local Credentials The fastest way to create a provider is to let the CLI discover credentials from\nyour shell environment: $ openshell provider create --name my-claude --type claude --from-existing\nThis reads ANTHROPIC_API_KEY or CLAUDE_API_KEY from your current environment\nand stores them in the provider. With Explicit Credentials Supply a credential value directly: $ openshell provider create --name my-api --type generic --credential API_KEY=sk-abc123\nBare Key Form Pass a key name without a value to read the value from the environment variable\nof that name: $ openshell provider create --name my-api --type generic --credential API_KEY\nThis looks up the current value of $API_KEY in your shell and stores it. Manage Providers List, inspect, update, and delete providers from the active cluster. List all providers: $ openshell provider list\nInspect a provider: $ openshell provider get my-claude\nUpdate a provider’s credentials: $ openshell provider update my-claude --type claude --from-existing\nDelete a provider: $ openshell provider delete my-claude\nAttach Providers to Sandboxes Pass one or more --provider flags when creating a sandbox: $ openshell sandbox create --provider my-claude --provider my-github -- claude\nEach --provider flag attaches one provider. The sandbox receives all\ncredentials from every attached provider at runtime. Providers cannot be added to a running sandbox. If you need to attach an\nadditional provider, delete the sandbox and recreate it with all required\nproviders specified. Auto-Discovery Shortcut When the trailing command in openshell sandbox create is a recognized tool name ( claude , codex , or opencode ), the CLI auto-creates the required\nprovider from your local credentials if one does not already exist. You do not\nneed to create the provider separately: $ openshell sandbox create -- claude\nThis detects claude as a known tool, finds your ANTHROPIC_API_KEY , creates\na provider, attaches it to the sandbox, and launches Claude Code. Supported Provider Types The following provider types are supported. Type Environment Variables Injected Typical Use 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 — refer to /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 outlook (none: no auto-discovery) Microsoft Outlook integration Use the generic type for any service not listed above. You define the\nenvironment variable names and values yourself with --credential . Next Steps Explore related topics: To control what the agent can access, refer to policies . To use a pre-built environment, refer to the community-sandboxes catalog. To view the complete field reference for the policy YAML, refer to the Policy Schema Reference","format":"text","content_length":3421,"word_count":502,"summary":"AI agents typically need credentials to access external services: an API key for the AI model provider, a token for GitHub or GitLab, and so on. OpenShell manages these credentials as first-class entities called providers.","headings":[{"text":"Providers","level":1,"id":"providers"},{"text":"Create a Provider","level":2,"id":"create-a-provider"},{"text":"From Local Credentials","level":3,"id":"from-local-credentials"},{"text":"With Explicit Credentials","level":3,"id":"with-explicit-credentials"},{"text":"Bare Key Form","level":3,"id":"bare-key-form"},{"text":"Manage Providers","level":2,"id":"manage-providers"},{"text":"Attach Providers to Sandboxes","level":2,"id":"attach-providers-to-sandboxes"},{"text":"Auto-Discovery Shortcut","level":3,"id":"auto-discovery-shortcut"},{"text":"Supported Provider Types","level":2,"id":"supported-provider-types"},{"text":"Next Steps","level":2,"id":"next-steps"}],"headings_text":"Providers Create a Provider From Local Credentials With Explicit Credentials Bare Key Form Manage Providers Attach Providers to Sandboxes Auto-Discovery Shortcut Supported Provider Types Next Steps","keywords":["anthropic","any","attach","auto","bare","catalog","claude","code","codex","create","credentials","delete","directly","discovery","each","environment","explicit","explore","form","from","github","gitlab","injected","inspect","key","list","local","manage","microsoft","name","next","none","openai","openshell","outlook","pass","policy","provider","providers","reference","sandbox","sandboxes","schema","separately","services","shortcut","steps","supply","supported","this"],"code_blocks":[{"content":"$ openshell provider create --name my-claude --type claude --from-existing","language":"text"},{"content":"$ openshell provider create --name my-api --type generic --credential API_KEY=sk-abc123","language":"text"},{"content":"$ openshell provider create --name my-api --type generic --credential API_KEY","language":"text"},{"content":"$ openshell provider list","language":"text"},{"content":"$ openshell provider get my-claude","language":"text"},{"content":"$ openshell provider update my-claude --type claude --from-existing","language":"text"},{"content":"$ openshell provider delete my-claude","language":"text"},{"content":"$ openshell sandbox create --provider my-claude --provider my-github -- claude","language":"text"},{"content":"$ openshell sandbox create -- claude","language":"text"}],"links":[],"images":[],"doc_type":"tutorial","section_path":["Sandboxes","Providers"]},{"id":"tutorials/github-sandbox","title":"Set Up a Sandbox of Claude Code with a Custom GitHub Policy","url":"tutorials/github-sandbox.html","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.1.0"},"product":{"name":"OpenShell","version":"0.1.0"},"description":"Learn the iterative policy workflow by launching a sandbox, diagnosing a GitHub access denial, and applying a custom policy to fix it.","tags":["Tutorial","GitHub","Sandbox","Policy","Claude Code"],"topics":["Generative AI","Cybersecurity"],"content_type":"how_to","learning_level":"technical_intermediate","audience":["engineer"],"content":"Set Up a Sandbox of Claude Code with a Custom GitHub Policy This tutorial walks through the iterative policy workflow. You launch a sandbox, ask Claude Code to push code to GitHub, get blocked by the default network policy, diagnose the denial from two angles — the OpenShell Terminal on your laptop and the sandbox logs from inside — and then apply a custom policy to fix it, all without recreating the sandbox. After completing this tutorial, you will 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 may differ between sessions — use the examples as a guide for the type of interaction, not as expected output. Prerequisites This tutorial requires the following: Completed the Quickstart tutorial. A GitHub personal access token (PAT) with repo scope. To create one, go to GitHub Settings > Developer settings > Personal access tokens , select Generate new token (classic) , check the repo scope, and copy the token. Your own Anthropic account for Claude Code. OpenShell provides the sandbox, not the agent — you need your own account to log in to Claude Code. A public GitHub repository you own (used as the push target). A scratch or test repository works well — the tutorial pushes a small file to it. You can create a new repository with a README if you do not have one handy. This tutorial uses two terminals throughout: Terminal 1 (sandbox) — The terminal where you launch the sandbox. Claude Code runs here. You interact with the agent in this terminal. Terminal 2 (laptop) — A separate terminal on your laptop. You use this for openshell term , openshell policy set , and other CLI commands that manage the sandbox from the outside. Each section below indicates which terminal to use. Launch the Sandbox Terminal 1 (sandbox) — Create a sandbox and start Claude Code. No custom policy is needed yet — the default policy is applied automatically. Starting a new sandbox Create a credential provider 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: $ GITHUB_TOKEN=<your-token\nopenshell provider create --name my-github --type github --from-existing\nopenshell sandbox create --provider my-github --keep -- claude\nUsing an existing sandbox Connect to a sandbox that is already running and set your GitHub token as an environment variable: $ openshell sandbox connect <sandbox-name\nexport GITHUB_TOKEN=<your-token\nThe --keep flag keeps the sandbox running after Claude Code exits, so you can apply policy updates later without recreating the environment. Claude Code starts inside the sandbox. Log in through your preferred authentication method and trust the /sandbox workspace when prompted. Push Code to GitHub Terminal 1 (sandbox) — Ask Claude Code to write a simple script and push it to your repository: Write a hello_world.py script and push it to https://github.com/<org>/<repo\nClaude 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 does not permit outbound requests to GitHub, so the proxy blocks the connection before the request reaches GitHub’s servers. Diagnose the Denial View the logs from your laptop Terminal 2 (laptop) — Open a separate terminal on your laptop and launch the OpenShell Terminal: $ openshell term\nThe 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: l7_action: PUT\nl7_target: /repos/<org>/<repo>/contents/hello_world.py\nl7_decision: deny\ndst_host: api.github.com\ndst_port: 443\nl7_protocol: rest\npolicy: github_rest_api\nl7_deny_reason: PUT /repos/<org>/<repo>/contents/hello_world.py not permitted by policy\nThe 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. Ask Claude to check the sandbox logs Terminal 1 (sandbox) — Switch back to Claude Code. Ask it to check the sandbox logs for denied requests: Check the sandbox logs for any denied network requests. What is blocking the push\nClaude 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: The sandbox runs a proxy that enforces policies on outbound traffic. The\ngithub_rest_api policy allows GET requests (used to read the file) but blocks\nPUT/write requests to GitHub. This is a sandbox-level restriction, not a token\nissue — no matter what token you provide, pushes via the API will be blocked\nuntil the policy is updated. 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 will paste it into your laptop agent in the next step. Update the Policy from Your Laptop Terminal 2 (laptop) — Paste the deny reason from the previous step into your coding agent (for example, Claude Code or Cursor running on your laptop) and ask it to update the sandbox policy. The deny reason gives the agent the context it needs to generate the correct policy rules. The agent inspects the deny reasons, writes an updated policy that adds github_git and github_api blocks for your repository, and runs openshell policy set to apply it: $ openshell policy set <sandbox-name> --policy /tmp/sandbox-policy-update.yaml --wait\nYour coding agent generates both the policy file and this command. 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. Full reference policy The following YAML shows a complete policy that extends the default policy with GitHub access for a single repository. This is representative of what a coding agent generates when asked to unblock GitHub pushes. Replace <org> with your GitHub organization or username and <repo> with your repository name. version: 1\n── Static (locked at sandbox creation)\nfilesystem_policy\ninclude_workdir: true\nread_only\n/usr\n/lib\n/proc\n/dev/urandom\n/app\n/etc\n/var/log\nread_write\n/sandbox\n/tmp\n/dev/null\nlandlock\ncompatibility: best_effort\nprocess\nrun_as_user: sandbox\nrun_as_group: sandbox\n── Dynamic (hot-reloadable)\nnetwork_policies\nClaude Code ↔ Anthropic API\nclaude_code\nname: claude-code\nendpoints\n{ host: api.anthropic.com, port: 443, protocol: rest, enforcement: enforce, access: full, tls: terminate\n{ host: statsig.anthropic.com, port: 443\n{ host: sentry.io, port: 443\n{ host: raw.githubusercontent.com, port: 443\n{ host: platform.claude.com, port: 443\nbinaries\n{ path: /usr/local/bin/claude\n{ path: /usr/bin/node\nNVIDIA inference endpoint\nnvidia_inference\nname: nvidia-inference\nendpoints\n{ host: integrate.api.nvidia.com, port: 443\nbinaries\n{ path: /usr/bin/curl\n{ path: /bin/bash\n{ path: /usr/local/bin/opencode\n── GitHub: git operations (clone, fetch, push)\ngithub_git\nname: github-git\nendpoints\nhost: github.com\nport: 443\nprotocol: rest\ntls: terminate\nenforcement: enforce\nrules\nallow\nmethod: GET\npath: \"/<org>/<repo>.git/info/refs\nallow\nmethod: POST\npath: \"/<org>/<repo>.git/git-upload-pack\nallow\nmethod: POST\npath: \"/<org>/<repo>.git/git-receive-pack\nbinaries\n{ path: /usr/bin/git\n── GitHub: REST API\ngithub_api\nname: github-api\nendpoints\nhost: api.github.com\nport: 443\nprotocol: rest\ntls: terminate\nenforcement: enforce\nrules\nGraphQL API (used by gh CLI\nallow\nmethod: POST\npath: \"/graphql\nFull read-write access to the repository\nallow\nmethod:\npath: \"/repos/<org>/<repo\nbinaries\n{ path: /usr/local/bin/claude\n{ path: /usr/local/bin/opencode\n{ path: /usr/bin/gh\n{ path: /usr/bin/curl\n── Package managers\npypi\nname: pypi\nendpoints\n{ host: pypi.org, port: 443\n{ host: files.pythonhosted.org, port: 443\n{ host: github.com, port: 443\n{ host: objects.githubusercontent.com, port: 443\n{ host: api.github.com, port: 443\n{ host: downloads.python.org, port: 443\nbinaries\n{ path: /sandbox/.venv/bin/python\n{ path: /sandbox/.venv/bin/python3\n{ path: /sandbox/.venv/bin/pip\n{ path: /app/.venv/bin/python\n{ path: /app/.venv/bin/python3\n{ path: /app/.venv/bin/pip\n{ path: /usr/local/bin/uv\n{ path: \"/sandbox/.uv/python/**\"\n── VS Code Remote\nvscode\nname: vscode\nendpoints\n{ host: update.code.visualstudio.com, port: 443\n{ host: \"*.vo.msecnd.net\", port: 443\n{ host: vscode.download.prss.microsoft.com, port: 443\n{ host: marketplace.visualstudio.com, port: 443\n{ host: \"*.gallerycdn.vsassets.io\", port: 443\nbinaries\n{ path: /usr/bin/curl\n{ path: /usr/bin/wget\n{ path: \"/sandbox/.vscode-server/**\"\n{ path: \"/sandbox/.vscode-remote-containers/**\"\nThe following table summarizes the two GitHub-specific blocks: Block Endpoint Behavior github_git github.com:443 Git Smart HTTP protocol with TLS termination. 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 with TLS termination. Permits all HTTP methods for the specified repository and GraphQL queries. Denies API access to unlisted repositories. The remaining blocks ( claude_code , nvidia_inference , pypi , vscode ) are identical to the default policy . Sandbox behavior outside of GitHub operations is unchanged. For details on policy block structure, refer to Network Access Rules . Retry the Push Terminal 1 (sandbox) — Switch back to Claude Code and ask it to retry the push: The sandbox policy has been updated. Try pushing to the repository again\nThe 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. 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 . To learn the full policy iteration workflow (pull, edit, push, verify), refer to /sandboxes/policies . To inject credentials automatically instead of pasting tokens, refer to /sandboxes/providers","format":"text","content_length":10877,"word_count":1592,"summary":"This tutorial walks through the iterative policy workflow. You launch a sandbox, ask Claude Code to push code to GitHub, get blocked by the default network policy, diagnose the denial from two angles — the OpenShell Terminal on your laptop and the sandbox logs from inside — and then apply a custo...","headings":[{"text":"Set Up a Sandbox of Claude Code with a Custom GitHub Policy","level":1,"id":"set-up-a-sandbox-of-claude-code-with-a-custom-github-policy"},{"text":"Prerequisites","level":2,"id":"prerequisites"},{"text":"Launch the Sandbox","level":2,"id":"launch-the-sandbox"},{"text":"Push Code to GitHub","level":2,"id":"push-code-to-github"},{"text":"Diagnose the Denial","level":2,"id":"diagnose-the-denial"},{"text":"View the logs from your laptop","level":3,"id":"view-the-logs-from-your-laptop"},{"text":"Ask Claude to check the sandbox logs","level":3,"id":"ask-claude-to-check-the-sandbox-logs"},{"text":"Update the Policy from Your Laptop","level":2,"id":"update-the-policy-from-your-laptop"},{"text":"Retry the Push","level":2,"id":"retry-the-push"},{"text":"Next Steps","level":2,"id":"next-steps"}],"headings_text":"Set Up a Sandbox of Claude Code with a Custom GitHub Policy Prerequisites Launch the Sandbox Push Code to GitHub Diagnose the Denial View the logs from your laptop Ask Claude to check the sandbox logs Update the Policy from Your Laptop Retry the Push Next Steps","keywords":["access","after","anthropic","api","ask","behavior","block","blocks","both","check","claude","code","com","compatibility","completed","connect","copy","create","cursor","custom","denial","denies","depth","detail","developer","diagnose","dst_host","dst_port","dynamic","each","endpoint","enforcement","experience","following","from","full","generate","git","github","graphql","have","host","https","include_workdir","issue","l7_action","l7_decision","l7_deny_reason","l7_protocol","l7_target"],"code_blocks":[{"content":"$ GITHUB_TOKEN=<your-token>\n$ openshell provider create --name my-github --type github --from-existing\n$ openshell sandbox create --provider my-github --keep -- claude","language":"text"},{"content":"$ openshell sandbox connect <sandbox-name>\n$ export GITHUB_TOKEN=<your-token>","language":"text"},{"content":"Write a hello_world.py script and push it to https://github.com/<org>/<repo>.","language":"text"},{"content":"$ openshell term","language":"text"},{"content":"l7_action:      PUT\nl7_target:      /repos/<org>/<repo>/contents/hello_world.py\nl7_decision:    deny\ndst_host:       api.github.com\ndst_port:       443\nl7_protocol:    rest\npolicy:         github_rest_api\nl7_deny_reason: PUT /repos/<org>/<repo>/contents/hello_world.py not permitted by policy","language":"text"},{"content":"Check the sandbox logs for any denied network requests. What is blocking the push?","language":"text"},{"content":"$ openshell policy set <sandbox-name> --policy /tmp/sandbox-policy-update.yaml --wait","language":"text"},{"content":"version: 1\n\n# ── Static (locked at sandbox creation) ──────────────────────────\n\nfilesystem_policy:\n  include_workdir: true\n  read_only:\n    - /usr\n    - /lib\n    - /proc\n    - /dev/urandom\n    - /app\n    - /etc\n    - /var/log\n  read_write:\n    - /sandbox\n    - /tmp\n    - /dev/null\n\nlandlock:\n  compatibility: best_effort\n\nprocess:\n  run_as_user: sandbox\n  run_as_group: sandbox\n\n# ── Dynamic (hot-reloadable) ─────────────────────────────────────\n\nnetwork_policies:\n\n  # Claude Code ↔ Anthropic API\n  claude_code:\n    name: claude-code\n    endpoints:\n      - { host: api.anthropic.com, port: 443, protocol: rest, enforcement: enforce, access: full, tls: terminate }\n      - { host: statsig.anthropic.com, port: 443 }\n      - { host: sentry.io, port: 443 }\n      - { host: raw.githubusercontent.com, port: 443 }\n      - { host: platform.claude.com, port: 443 }\n    binaries:\n      - { path: /usr/local/bin/claude }\n      - { path: /usr/bin/node }\n\n  # NVIDIA inference endpoint\n  nvidia_inference:\n    name: nvidia-inference\n    endpoints:\n      - { host: integrate.api.nvidia.com, port: 443 }\n    binaries:\n      - { path: /usr/bin/curl }\n      - { path: /bin/bash }\n      - { path: /usr/local/bin/opencode }\n\n  # ── GitHub: git operations (clone, fetch, push) ──────────────\n\n  github_git:\n    name: github-git\n    endpoints:\n      - host: github.com\n        port: 443\n        protocol: rest\n        tls: terminate\n        enforcement: enforce\n        rules:\n          - allow:\n              method: GET\n              path: \"/<org>/<repo>.git/info/refs*\"\n          - allow:\n              method: POST\n              path: \"/<org>/<repo>.git/git-upload-pack\"\n          - allow:\n              method: POST\n              path: \"/<org>/<repo>.git/git-receive-pack\"\n    binaries:\n      - { path: /usr/bin/git }\n\n  # ── GitHub: REST API ─────────────────────────────────────────\n\n  github_api:\n    name: github-api\n    endpoints:\n      - host: api.github.com\n        port: 443\n        protocol: rest\n        tls: terminate\n        enforcement: enforce\n        rules:\n          # GraphQL API (used by gh CLI)\n          - allow:\n              method: POST\n              path: \"/graphql\"\n          # Full read-write access to the repository\n          - allow:\n              method: \"*\"\n              path: \"/repos/<org>/<repo>/**\"\n    binaries:\n      - { path: /usr/local/bin/claude }\n      - { path: /usr/local/bin/opencode }\n      - { path: /usr/bin/gh }\n      - { path: /usr/bin/curl }\n\n  # ── Package managers ─────────────────────────────────────────\n\n  pypi:\n    name: pypi\n    endpoints:\n      - { host: pypi.org, port: 443 }\n      - { host: files.pythonhosted.org, port: 443 }\n      - { host: github.com, port: 443 }\n      - { host: objects.githubusercontent.com, port: 443 }\n      - { host: api.github.com, port: 443 }\n      - { host: downloads.python.org, port: 443 }\n    binaries:\n      - { path: /sandbox/.venv/bin/python }\n      - { path: /sandbox/.venv/bin/python3 }\n      - { path: /sandbox/.venv/bin/pip }\n      - { path: /app/.venv/bin/python }\n      - { path: /app/.venv/bin/python3 }\n      - { path: /app/.venv/bin/pip }\n      - { path: /usr/local/bin/uv }\n      - { path: \"/sandbox/.uv/python/**\" }\n\n  # ── VS Code Remote ──────────────────────────────────────────\n\n  vscode:\n    name: vscode\n    endpoints:\n      - { host: update.code.visualstudio.com, port: 443 }\n      - { host: \"*.vo.msecnd.net\", port: 443 }\n      - { host: vscode.download.prss.microsoft.com, port: 443 }\n      - { host: marketplace.visualstudio.com, port: 443 }\n      - { host: \"*.gallerycdn.vsassets.io\", port: 443 }\n    binaries:\n      - { path: /usr/bin/curl }\n      - { path: /usr/bin/wget }\n      - { path: \"/sandbox/.vscode-server/**\" }\n      - { path: \"/sandbox/.vscode-remote-containers/**\" }","language":"text"},{"content":"The sandbox policy has been updated. Try pushing to the repository again.","language":"text"}],"links":[{"text":"GitHub Settings > Developer settings > Personal access tokens","type":"external","url":"https://github.com/settings/tokens"},{"text":"Anthropic account","type":"external","url":"https://console.anthropic.com/"},{"text":"create a new repository","type":"external","url":"https://github.com/new"}],"images":[],"doc_type":"tutorial","section_path":["Tutorials","Github Sandbox"]}]
\ No newline at end of file
+[{"id":"about/architecture","title":"How OpenShell Works","url":"about/architecture.html","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.1.0"},"product":{"name":"OpenShell","version":"0.1.0"},"description":"OpenShell architecture overview covering the gateway, sandbox, policy engine, and privacy router.","tags":["AI Agents","Sandboxing","Security","Architecture"],"topics":["Generative AI","Cybersecurity"],"content_type":"concept","learning_level":"technical_beginner","audience":["engineer","data_scientist"],"content":"How OpenShell Works OpenShell runs as a K3s 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. 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. Sandbox Isolated runtime that includes container supervision and policy-enforced egress routing. Policy Engine Policy definition and enforcement layer for filesystem, network, and process constraints. Defense in depth enforces policies from the application layer down to infrastructure and kernel layers. Privacy Router Privacy-aware LLM routing layer that keeps sensitive context on sandbox compute and routes based on cost and privacy policy. How a Request Flows Every outbound connection from agent code passes through the same decision path: The agent process opens an outbound connection (API call, package install, git clone, and so on). The proxy inside the sandbox intercepts the connection and identifies which binary opened it. The proxy queries the policy engine with the destination, port, and calling binary. The policy engine returns one of three decisions: Allow — the destination and binary match a policy block. Traffic flows directly to the external service. Route for inference — no policy block matched, but inference routing is configured. The privacy router intercepts the request, strips the original credentials, injects the configured backend credentials, and forwards to the managed model endpoint. Deny — no match and no inference route. The connection is blocked and logged. For REST endpoints with TLS termination enabled, the proxy also decrypts TLS and checks each HTTP request against per-method, per-path rules before allowing it through. Deployment Modes 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. $ openshell gateway start --remote <username>@<spark-ssid>.local\nopenshell status\nNext Steps Continue with one of the following: To create your first sandbox, refer to the Quickstart . To learn how OpenShell enforces isolation across all protection layers, refer to Sandboxes","format":"text","content_length":2611,"word_count":393,"summary":"OpenShell runs as a K3s 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.","headings":[{"text":"How OpenShell Works","level":1,"id":"how-openshell-works"},{"text":"Components","level":2,"id":"components"},{"text":"How a Request Flows","level":2,"id":"how-a-request-flows"},{"text":"Deployment Modes","level":2,"id":"deployment-modes"},{"text":"Next Steps","level":2,"id":"next-steps"}],"headings_text":"How OpenShell Works Components How a Request Flows Deployment Modes Next Steps","keywords":["allow","component","components","continue","control","decisions","defense","deny","deploy","deployment","docker","each","engine","every","flows","following","four","gateway","isolated","k3s","kubernetes","local","modes","next","openshell","path","policy","privacy","quickstart","remote","request","role","route","router","sandbox","sandboxes","spark","steps","system","traffic","works"],"code_blocks":[{"content":"$ openshell gateway start --remote <username>@<spark-ssid>.local\n$ openshell status","language":"text"}],"links":[{"text":"K3s","type":"external","url":"https://k3s.io/"},{"text":"OpenShell architecture diagram showing the component layout","type":"internal","url":"about/../_images/architecture.svg"}],"images":[{"src":"about/architecture.svg","alt":"OpenShell architecture diagram showing the component layout"},{"src":"about/architecture.svg","alt":"OpenShell architecture diagram showing the component layout"}],"doc_type":"documentation","section_path":["About","Architecture"]},{"id":"about/overview","title":"Overview of NVIDIA OpenShell","url":"about/overview.html","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.1.0"},"product":{"name":"OpenShell","version":"0.1.0"},"description":"OpenShell is the safe, private runtime for autonomous AI agents. Run agents in sandboxed environments that protect your data, credentials, and infrastructure.","tags":["AI Agents","Sandboxing","Security","Privacy","Inference Routing"],"topics":["Generative AI","Cybersecurity"],"content_type":"concept","learning_level":"technical_beginner","audience":["engineer","data_scientist"],"content":"Overview of NVIDIA OpenShell 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. 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. Common Risks and Controls The table below summarizes common failure modes and how OpenShell mitigates them. Threat Without controls With OpenShell Data exfiltration Agent uploads source code or internal files to unauthorized endpoints. Network policies allow only approved destinations; other outbound traffic is denied. Credential theft Agent reads local secrets such as SSH keys or cloud credentials. Filesystem restrictions (Landlock) confine access to declared paths only. Unauthorized API usage Agent sends prompts or data to unapproved model providers. Privacy routing and network policies control where inference traffic can go. Privilege escalation Agent attempts sudo , setuid paths, or dangerous syscall behavior. Unprivileged process identity and seccomp restrictions block escalation paths. Protection Layers at a Glance OpenShell applies defense in depth across the following policy domains. Layer What it protects When it applies Filesystem Prevents reads/writes outside allowed paths. Locked at sandbox creation. Network Blocks unauthorized outbound connections. Hot-reloadable at runtime. Process Blocks privilege escalation and dangerous syscalls. Locked at sandbox creation. Inference Reroutes model API calls to controlled backends. Hot-reloadable at runtime. For details, refer to Built-in Default Policy and Customize Sandbox Policies . Common Use Cases 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 Explore these topics to go deeper: To understand the components that make up the OpenShell runtime, refer to the Architecture Overview . To install the CLI and create your first sandbox, refer to the Quickstart . To learn how OpenShell enforces isolation across all protection layers, refer to Sandboxes","format":"text","content_length":2852,"word_count":403,"summary":"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 ...","headings":[{"text":"Overview of NVIDIA OpenShell","level":1,"id":"overview-of-nvidia-openshell"},{"text":"Why OpenShell Exists","level":2,"id":"why-openshell-exists"},{"text":"Common Risks and Controls","level":2,"id":"common-risks-and-controls"},{"text":"Protection Layers at a Glance","level":2,"id":"protection-layers-at-a-glance"},{"text":"Common Use Cases","level":2,"id":"common-use-cases"},{"text":"Next Steps","level":2,"id":"next-steps"}],"headings_text":"Overview of NVIDIA OpenShell Why OpenShell Exists Common Risks and Controls Protection Layers at a Glance Common Use Cases Next Steps","keywords":["agent","apis","architecture","blocks","built","case","cases","claude","code","common","compliance","controls","credential","customize","data","deeper","default","description","exists","explore","filesystem","glance","hot","inference","landlock","layer","layers","locked","network","next","nvidia","openclaw","opencode","openshell","overview","policies","policy","prevents","privacy","private","privilege","process","protection","quickstart","reroutes","reusable","risks","route","run","sandbox"],"code_blocks":[],"links":[],"images":[],"doc_type":"documentation","section_path":["About","Overview"]},{"id":"about/release-notes","title":"NVIDIA OpenShell Release Notes","url":"about/release-notes.html","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.1.0"},"product":{"name":"OpenShell","version":"0.1.0"},"description":"Track the latest changes and improvements to NVIDIA OpenShell.","tags":["Release Notes","Changelog","AI Agents"],"topics":["Generative AI","Cybersecurity"],"content_type":"reference","learning_level":"technical_beginner","audience":["engineer","data_scientist"],"content":"NVIDIA OpenShell Release Notes Track the latest changes and improvements to NVIDIA OpenShell\nThis page covers the highlights of the release\nFor more details, refer to the OpenShell GitHub 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","format":"text","content_length":731,"word_count":97,"summary":"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.","headings":[{"text":"NVIDIA OpenShell Release Notes","level":1,"id":"nvidia-openshell-release-notes"},{"text":"0.1.0","level":2,"id":"010"},{"text":"Highlights","level":3,"id":"highlights"}],"headings_text":"NVIDIA OpenShell Release Notes 0.1.0 Highlights","keywords":["github","highlights","introduces","notes","nvidia","openshell","release","releases","this","track"],"code_blocks":[],"links":[{"text":"OpenShell GitHub Releases","type":"external","url":"https://github.com/NVIDIA/OpenShell/releases"}],"images":[],"doc_type":"documentation","section_path":["About","Release Notes"]},{"id":"get-started/quickstart","title":"Quickstart","url":"get-started/quickstart.html","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.1.0"},"product":{"name":"OpenShell","version":"0.1.0"},"description":"Install the OpenShell CLI and create your first sandboxed AI agent in two commands.","tags":["AI Agents","Sandboxing","Installation","Quickstart"],"topics":["Generative AI","Cybersecurity"],"content_type":"get_started","learning_level":"technical_beginner","audience":["engineer","data_scientist"],"content":"Quickstart This page gets you from zero to a running, policy-enforced sandbox in two commands. Prerequisites Before you begin, make sure you have: Python 3.12 or later uv installed Docker Desktop running on your machine Install the OpenShell CLI Install the openshell package into a virtual environment. Activate your virtual environment: uv venv && source .venv/bin/activate\nInstall the CLI: uv pip install openshell\nConnect to a Remote Gateway (Optional) If you’re running locally, skip this step. The OpenShell CLI creates a gateway automatically when you create your first sandbox. Brev Deploy an OpenShell gateway on Brev by hitting Deploy on the OpenShell Launchable . 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. $ openshell gateway add https://<your-port-8080-url>.brevlab.com\nopenshell status\nDGX Spark 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: $ openshell gateway start --remote <username>@<spark-ssid>.local\nopenshell status\nAfter openshell status shows the gateway as healthy, all subsequent commands route through the SSH tunnel. Create Your First OpenShell Sandbox Choose the tab that matches your agent: Claude Code Run the following command to create a sandbox with Claude Code: $ openshell sandbox create -- claude\nThe CLI prompts you to create a provider from local credentials — type yes to continue. If ANTHROPIC_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. OpenCode Run the following command to create a sandbox with OpenCode: $ openshell sandbox create -- opencode\nThe 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. Codex Run the following command to create a sandbox with Codex: $ openshell sandbox create -- codex\nThe 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. OpenClaw Run the following command to create a sandbox with OpenClaw: $ openshell sandbox create --from openclaw\nThe --from flag pulls a pre-built sandbox definition from the OpenShell Community catalog. Each definition bundles a container image, a tailored policy, and optional skills into a single package. Community Sandbox You can use the --from flag to pull other OpenShell sandbox images from the NVIDIA Container Registry . For example, to pull the base image, run the following command: $ openshell sandbox create --from base","format":"text","content_length":2947,"word_count":470,"summary":"This page gets you from zero to a running, policy-enforced sandbox in two commands.","headings":[{"text":"Quickstart","level":1,"id":"quickstart"},{"text":"Prerequisites","level":2,"id":"prerequisites"},{"text":"Install the OpenShell CLI","level":2,"id":"install-the-openshell-cli"},{"text":"Connect to a Remote Gateway (Optional)","level":2,"id":"connect-to-a-remote-gateway-optional"},{"text":"Create Your First OpenShell Sandbox","level":2,"id":"create-your-first-openshell-sandbox"}],"headings_text":"Quickstart Prerequisites Install the OpenShell CLI Connect to a Remote Gateway (Optional) Create Your First OpenShell Sandbox","keywords":["activate","after","agent","before","brev","choose","claude","cli","code","codex","com","command","community","connect","container","copy","create","deploy","desktop","docker","each","environment","first","gateway","have","https","install","launchable","links","openclaw","opencode","openshell","optional","prerequisites","python","quickstart","registry","remote","run","sandbox","secure","set","spark","sync","this","type","using","venv","your"],"code_blocks":[{"content":"uv venv && source .venv/bin/activate","language":"text"},{"content":"uv pip install openshell","language":"text"},{"content":"$ openshell gateway add https://<your-port-8080-url>.brevlab.com\n$ openshell status","language":"text"},{"content":"$ openshell gateway start --remote <username>@<spark-ssid>.local\n$ openshell status","language":"text"},{"content":"$ openshell sandbox create -- claude","language":"text"},{"content":"$ openshell sandbox create -- opencode","language":"text"},{"content":"$ openshell sandbox create -- codex","language":"text"},{"content":"$ openshell sandbox create --from openclaw","language":"text"},{"content":"$ openshell sandbox create --from base","language":"text"}],"links":[{"text":"Uv","type":"external","url":"https://docs.astral.sh/uv/","original_text":"uv"},{"text":"OpenShell Launchable","type":"external","url":"https://brev.nvidia.com/launchable/deploy/now?launchableID=env-3AaK9NmCzWp3pVyUDNNFBt805FT"},{"text":"OpenShell Community","type":"external","url":"https://github.com/NVIDIA/OpenShell-Community"},{"text":"NVIDIA Container Registry","type":"external","url":"https://registry.nvidia.com/"}],"images":[],"doc_type":"tutorial","section_path":["Get Started","Quickstart"]},{"id":"inference/configure","title":"Configure Inference Routing","url":"inference/configure.html","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.1.0"},"product":{"name":"OpenShell","version":"0.1.0"},"description":"Set up the managed local inference endpoint with provider credentials and model configuration.","tags":["Inference Routing","Configuration","Privacy","LLM","Provider"],"topics":["Generative AI","Cybersecurity"],"content_type":"how_to","learning_level":"technical_intermediate","audience":["engineer"],"content":"Configure Inference Routing This page covers the managed local inference endpoint ( https://inference.local ). External inference endpoints go through sandbox network_policies — refer to Network Access Rules for details. The configuration consists of two values: Value Description Provider record The credential backend OpenShell uses to authenticate with the upstream model host. Model ID The model to use for generation requests. Step 1: Create a Provider Create a provider that holds the backend credentials you want OpenShell to use. NVIDIA API Catalog $ openshell provider create --name nvidia-prod --type nvidia --from-existing\nThis reads NVIDIA_API_KEY from your environment. Local / self-hosted endpoint $ openshell provider create\nname my-local-model\ntype openai\ncredential OPENAI_API_KEY=empty-if-not-required\nconfig OPENAI_BASE_URL=http://192.168.10.15/v1\nUse --config OPENAI_BASE_URL to point to any OpenAI-compatible server running on your network. Set OPENAI_API_KEY to a dummy value if the server does not require authentication. Anthropic $ openshell provider create --name anthropic-prod --type anthropic --from-existing\nThis reads ANTHROPIC_API_KEY from your environment. Step 2: Set Inference Routing Point inference.local at that provider and choose the model to use: $ openshell inference set\nprovider nvidia-prod\nmodel nvidia/nemotron-3-nano-30b-a3b\nStep 3: Verify the Active Config Confirm that the provider and model are set correctly: $ openshell inference get\nGateway inference\nProvider: nvidia-prod\nModel: nvidia/nemotron-3-nano-30b-a3b\nVersion: 1\nStep 4: Update Part of the Config Use update when you want to change only one field: $ openshell inference update --model nvidia/nemotron-3-nano-30b-a3b\nOr switch providers without repeating the current model: $ openshell inference update --provider openai-prod\nUse It from a Sandbox After inference is configured, code inside any sandbox can call https://inference.local directly: from openai import OpenAI\nclient = OpenAI(base_url=\"https://inference.local/v1\", api_key=\"dummy\nresponse = client.chat.completions.create\nmodel=\"anything\nmessages=[{\"role\": \"user\", \"content\": \"Hello\nThe client-supplied model is ignored for generation requests. OpenShell rewrites it to the configured model before forwarding upstream. Use this endpoint when inference should stay local to the host for privacy and security reasons. External providers that should be reached directly belong in network_policies instead. Verify the Endpoint from a Sandbox openshell inference get confirms the configuration was saved, but does not verify the upstream endpoint is reachable. To confirm end-to-end connectivity, connect to a sandbox and run: curl https://inference.local/v1/responses\nH \"Content-Type: application/json\"\nd\ninstructions\": \"You are a helpful assistant\ninput\": \"Hello\nA successful response confirms the privacy router can reach the configured backend and the model is serving requests. Gateway-scoped — every sandbox on the active gateway sees the same inference.local backend. HTTPS only — inference.local is intercepted only for HTTPS traffic. Next Steps Explore related topics: To understand the inference routing flow and supported API patterns, refer to index . To control external endpoints, refer to Network Access Rules . To manage provider records, refer to ../sandboxes/providers . To view openshell inference commands, refer to ../reference/cli","format":"text","content_length":3420,"word_count":453,"summary":"This page covers the managed local inference endpoint (https://inference.local). External inference endpoints go through sandbox network_policies — refer to Network Access Rules for details.","headings":[{"text":"Configure Inference Routing","level":1,"id":"configure-inference-routing"},{"text":"Step 1: Create a Provider","level":2,"id":"step-1-create-a-provider"},{"text":"Step 2: Set Inference Routing","level":2,"id":"step-2-set-inference-routing"},{"text":"Step 3: Verify the Active Config","level":2,"id":"step-3-verify-the-active-config"},{"text":"Step 4: Update Part of the Config","level":2,"id":"step-4-update-part-of-the-config"},{"text":"Use It from a Sandbox","level":2,"id":"use-it-from-a-sandbox"},{"text":"Verify the Endpoint from a Sandbox","level":3,"id":"verify-the-endpoint-from-a-sandbox"},{"text":"Next Steps","level":2,"id":"next-steps"}],"headings_text":"Configure Inference Routing Step 1: Create a Provider Step 2: Set Inference Routing Step 3: Verify the Active Config Step 4: Update Part of the Config Use It from a Sandbox Verify the Endpoint from a Sandbox Next Steps","keywords":["access","active","after","anthropic","api_key","base_url","catalog","chat","client","config","configure","confirm","content","correctly","create","description","directly","endpoint","explore","external","field","from","gateway","hello","http","https","inference","local","messages","model","network","next","openai","openshell","part","point","provider","response","routing","rules","run","sandbox","set","step","steps","this","topics","type","update","user"],"code_blocks":[{"content":"$ openshell provider create --name nvidia-prod --type nvidia --from-existing","language":"text"},{"content":"$ openshell provider create \\\n    --name my-local-model \\\n    --type openai \\\n    --credential OPENAI_API_KEY=empty-if-not-required \\\n    --config OPENAI_BASE_URL=http://192.168.10.15/v1","language":"text"},{"content":"$ openshell provider create --name anthropic-prod --type anthropic --from-existing","language":"text"},{"content":"$ openshell inference set \\\n    --provider nvidia-prod \\\n    --model nvidia/nemotron-3-nano-30b-a3b","language":"text"},{"content":"$ openshell inference get\nGateway inference:\n\n  Provider: nvidia-prod\n  Model: nvidia/nemotron-3-nano-30b-a3b\n  Version: 1","language":"text"},{"content":"$ openshell inference update --model nvidia/nemotron-3-nano-30b-a3b","language":"text"},{"content":"$ openshell inference update --provider openai-prod","language":"text"},{"content":"from openai import OpenAI\n\nclient = OpenAI(base_url=\"https://inference.local/v1\", api_key=\"dummy\")\n\nresponse = client.chat.completions.create(\n    model=\"anything\",\n    messages=[{\"role\": \"user\", \"content\": \"Hello\"}],\n)","language":"text"},{"content":"curl https://inference.local/v1/responses \\\n    -H \"Content-Type: application/json\" \\\n    -d '{\n      \"instructions\": \"You are a helpful assistant.\",\n      \"input\": \"Hello!\"\n    }'","language":"text"}],"links":[],"images":[],"doc_type":"tutorial","section_path":["Inference","Configure"]},{"id":"inference/index","title":"About Inference Routing","url":"inference/index.html","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.1.0"},"product":{"name":"OpenShell","version":"0.1.0"},"description":"Understand how OpenShell routes inference traffic through external endpoints and the local privacy router.","tags":["Inference Routing","Privacy","AI Agents","LLM"],"topics":["Generative AI","Cybersecurity"],"content_type":"concept","learning_level":"technical_beginner","audience":["engineer","data_scientist"],"content":"About Inference Routing 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 . Refer to 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 privacy router strips the original credentials, injects the configured backend credentials, and forwards to the managed model endpoint. How inference.local Works When code inside a sandbox calls https://inference.local , the privacy router routes the request to the configured backend for that gateway. The configured model is applied to generation requests, and provider credentials are supplied by OpenShell rather than by code inside the sandbox. If code calls an external inference host directly, that traffic is evaluated only by network_policies . Property Detail Credentials No sandbox API keys needed — credentials come from the configured provider record. Configuration One provider and one model define sandbox inference. Provider support OpenAI, Anthropic, and NVIDIA providers all work through the same endpoint. Hot-refresh Provider credential changes and inference updates are picked up without recreating sandboxes. Supported API Patterns Supported request patterns depend on the provider configured for inference.local . OpenAI-compatible Pattern Method Path Chat Completions POST /v1/chat/completions Completions POST /v1/completions Responses POST /v1/responses Model Discovery GET /v1/models Model Discovery GET /v1/models/* Anthropic-compatible Pattern Method Path Messages POST /v1/messages Requests to inference.local that do not match the configured provider’s supported patterns are denied. Next Steps Continue with one of the following: To set up the backend behind inference.local , refer to configure . To control external endpoints, refer to Network Access Rules","format":"text","content_length":2010,"word_count":281,"summary":"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.","headings":[{"text":"About Inference Routing","level":1,"id":"about-inference-routing"},{"text":"How inference.local Works","level":2,"id":"how-inferencelocal-works"},{"text":"Supported API Patterns","level":2,"id":"supported-api-patterns"},{"text":"Next Steps","level":2,"id":"next-steps"}],"headings_text":"About Inference Routing How inference.local Works Supported API Patterns Next Steps","keywords":["about","access","anthropic","api","chat","com","completions","configuration","continue","credentials","detail","discovery","external","following","hot","https","inference","local","messages","method","model","network","next","openai","openshell","path","pattern","patterns","property","provider","refer","requests","responses","routing","rules","steps","supported","traffic","ways","works"],"code_blocks":[],"links":[],"images":[],"doc_type":"overview","section_path":["Inference"]},{"id":"reference/cli","title":"CLI Reference","url":"reference/cli.html","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.1.0"},"product":{"name":"OpenShell","version":"0.1.0"},"description":"Complete command reference for the openshell CLI including all subcommands, flags, and environment variables.","tags":["CLI","Reference","Commands","AI Agents"],"topics":["Generative AI","Cybersecurity"],"content_type":"reference","learning_level":"technical_beginner","audience":["engineer","data_scientist"],"content":"CLI Reference Complete command reference for the openshell CLI. Every subcommand, flag, and option is documented here. Command Tree The full hierarchy of openshell subcommands: openshell\nstatus\nlogs [name\nterm\nforward\n├── start <port> <name\n├── stop <port> <name\n└── list\ngateway\n├── start\n├── stop\n├── destroy\n├── info\n├── add <url\n└── select [name\nsandbox\n├── create\n├── get [name\n├── list\n├── delete <name...> [--all\n├── connect [name\n├── upload [name\n├── download [name\n└── ssh-config <name\npolicy\n├── set <name\n├── get <name\n└── list <name\nprovider\n├── create\n├── get <name\n├── list\n├── update <name\n└── delete <name\ninference\n├── set\n├── update\n└── get\ndoctor\n├── logs\n└── exec\ncompletions <shell\nCommands that accept an optional [name] argument — such as get , connect , upload , download , and logs — fall back to the last-used sandbox when the name is omitted. The CLI records the sandbox name each time you create or connect, and prints a hint showing which sandbox was selected. 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. openshell logs [name] View sandbox logs. Use --tail for streaming, --source and --level to filter. openshell term Launch the OpenShell Terminal — a dashboard showing sandbox status, live logs, and policy decisions in a single view. Navigate with j / k , press f to follow live output, s to filter by source, and q to quit. Refer to /sandboxes/create-and-manage for more on monitoring sandboxes and reading log entries. Gateway Commands Manage the OpenShell runtime cluster. Command Description openshell gateway start Deploy a new cluster. Add --remote user@host for remote deployment. 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 <url> Register an existing remote gateway by URL. openshell gateway select <name> Set the active cluster. All subsequent commands target this cluster. openshell gateway select List all registered clusters (when called without a name). Diagnostic Commands Troubleshoot gateway issues. Command Description openshell doctor logs Fetch logs from the gateway Docker container. Use --tail for streaming, -n to limit line count. openshell doctor exec -- <command> Run a command inside the gateway container (e.g., kubectl get pods -A , k9s , sh ). Sandbox Commands Create and manage isolated agent execution environments. Command Description 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 <name...> Delete one or more sandboxes by name. Use --all to delete every sandbox in the active gateway. openshell sandbox connect [name] Open an interactive SSH session into a running sandbox. openshell sandbox upload [name] Upload files from the host into a sandbox. openshell sandbox download [name] Download files from a sandbox to the host. openshell sandbox ssh-config <name> Print the generated SSH config block for a sandbox. Sandbox Create Flags The following flags control sandbox creation: Flag Description --name Assign a human-readable name to the sandbox. Auto-generated if omitted. --provider Attach a credential provider. Repeatable for multiple providers. --policy Path to a policy YAML file to apply at creation time. --upload Upload local files into the sandbox before running. --keep Keep the sandbox alive after the trailing command exits. --editor Launch vscode or cursor into /sandbox ; installs OpenShell-managed SSH config and implies --keep . --gpu Request a GPU-enabled sandbox. If no gateway is running, auto-bootstrap starts a GPU-enabled gateway. --editor Launch vscode or cursor into /sandbox ; installs OpenShell-managed SSH config and implies --keep . --forward Forward a local port into the sandbox at startup. --from Build from a community sandbox name, local Dockerfile directory, or container image reference. -- <command> The command to run inside the sandbox. Everything after -- is passed as the agent command. Policy Commands Apply and inspect sandbox policies at runtime. Command Description openshell policy set <name> Apply or update a policy on a running sandbox. Pass --policy <file> . openshell policy get <name> Show the active policy for a sandbox. Add --full for the complete policy with metadata. openshell policy list <name> List all policy versions applied to a sandbox, with status. Port Forwarding Commands Forward sandbox ports to the host for local access. Command Description openshell forward start <port> <name> Forward a sandbox port to the host. Add -d for background mode. openshell forward stop <port> <name> Stop an active port forward. openshell forward list List all active port forwards. Provider Commands Manage credential providers that inject secrets into sandboxes. Command Description openshell provider create Create a new credential provider. Refer to the flag reference below. openshell provider get <name> Show details of a provider. openshell provider list List all providers in the active cluster. openshell provider update <name> Update a provider’s credentials or configuration. openshell provider delete <name> Delete a provider. Provider Create Flags The following flags control provider creation: Flag Description --name Name for the provider. --type Provider type: claude , codex , opencode , github , gitlab , nvidia , generic , outlook . --from-existing Discover credentials from your current shell environment variables. --credential Set a credential explicitly. Format: KEY=VALUE or bare KEY to read from env. Repeatable. --config Set a configuration value. Format: KEY=VALUE . Repeatable. Inference Commands Configure the backend used by https://inference.local . openshell inference set Set the provider and model for managed inference. Both flags are required. Flag Description --provider Provider record name to use for injected credentials. --model Model identifier to force on generation requests. openshell inference update Update only the fields you specify. Flag Description --provider Replace the current provider record. --model Replace the current model ID. openshell inference get Show the current inference configuration, including provider, model, and version. Environment Variables The following environment variables override CLI defaults: Variable Description OPENSHELL_GATEWAY Name of the gateway to operate on. Overrides the active gateway set by openshell gateway select . OPENSHELL_SANDBOX_POLICY Default path to a policy YAML file. When set, openshell sandbox create uses this policy if no --policy flag is provided. Shell Completions Generate shell completion scripts for tab completion: $ openshell completions bash\nopenshell completions zsh\nopenshell completions fish\nPipe the output to your shell’s config file: $ openshell completions zsh >> ~/.zshrc\nsource ~/.zshrc\nBuilt-in Help Every command and subcommand includes built-in help. Use --help at any level to see available subcommands, flags, and usage examples: $ openshell --help\nopenshell sandbox --help\nopenshell sandbox create --help\nopenshell gateway --help\nHelp output groups flags under distinct headings: FLAGS for command-specific options, GATEWAY FLAGS for --gateway and --gateway-endpoint , and GLOBAL FLAGS for --verbose , --help , and --version","format":"text","content_length":7605,"word_count":1138,"summary":"Complete command reference for the openshell CLI. Every subcommand, flag, and option is documented here.","headings":[{"text":"CLI Reference","level":1,"id":"cli-reference"},{"text":"Command Tree","level":2,"id":"command-tree"},{"text":"Status, Logs, and Terminal","level":2,"id":"status-logs-and-terminal"},{"text":"Gateway Commands","level":2,"id":"gateway-commands"},{"text":"Diagnostic Commands","level":2,"id":"diagnostic-commands"},{"text":"Sandbox Commands","level":2,"id":"sandbox-commands"},{"text":"Sandbox Create Flags","level":3,"id":"sandbox-create-flags"},{"text":"Policy Commands","level":2,"id":"policy-commands"},{"text":"Port Forwarding Commands","level":2,"id":"port-forwarding-commands"},{"text":"Provider Commands","level":2,"id":"provider-commands"},{"text":"Provider Create Flags","level":3,"id":"provider-create-flags"},{"text":"Inference Commands","level":2,"id":"inference-commands"},{"text":"openshell inference set","level":3,"id":"openshell-inference-set"},{"text":"openshell inference update","level":3,"id":"openshell-inference-update"},{"text":"openshell inference get","level":3,"id":"openshell-inference-get"},{"text":"Environment Variables","level":2,"id":"environment-variables"},{"text":"Shell Completions","level":2,"id":"shell-completions"},{"text":"Built-in Help","level":2,"id":"built-in-help"}],"headings_text":"CLI Reference Command Tree Status, Logs, and Terminal Gateway Commands Diagnostic Commands Sandbox Commands Sandbox Create Flags Policy Commands Port Forwarding Commands Provider Commands Provider Create Flags Inference Commands openshell inference set openshell inference update openshell inference get Environment Variables Shell Completions Built-in Help","keywords":["add","apply","assign","attach","auto","both","build","built","check","cli","command","commands","complete","completion","completions","configure","create","creation","dashboard","default","defaults","delete","deploy","description","diagnostic","discover","docker","dockerfile","download","environment","every","everything","examples","fetch","file","flag","flags","format","forward","forwarding","gateway","generate","headings","help","https","inference","keep","launch","list","logs"],"code_blocks":[{"content":"openshell\n├── status\n├── logs [name]\n├── term\n├── forward\n│   ├── start <port> <name>\n│   ├── stop <port> <name>\n│   └── list\n├── gateway\n│   ├── start\n│   ├── stop\n│   ├── destroy\n│   ├── info\n│   ├── add <url>\n│   └── select [name]\n├── sandbox\n│   ├── create\n│   ├── get [name]\n│   ├── list\n│   ├── delete <name...> [--all]\n│   ├── connect [name]\n│   ├── upload [name]\n│   ├── download [name]\n│   └── ssh-config <name>\n├── policy\n│   ├── set <name>\n│   ├── get <name>\n│   └── list <name>\n├── provider\n│   ├── create\n│   ├── get <name>\n│   ├── list\n│   ├── update <name>\n│   └── delete <name>\n├── inference\n│   ├── set\n│   ├── update\n│   └── get\n├── doctor\n│   ├── logs\n│   └── exec\n└── completions <shell>","language":"text"},{"content":"$ openshell completions bash\n$ openshell completions zsh\n$ openshell completions fish","language":"text"},{"content":"$ openshell completions zsh >> ~/.zshrc\n$ source ~/.zshrc","language":"text"},{"content":"$ openshell --help\n$ openshell sandbox --help\n$ openshell sandbox create --help\n$ openshell gateway --help","language":"text"}],"links":[],"images":[],"doc_type":"reference","section_path":["Reference","Cli"]},{"id":"reference/default-policy","title":"Default Policy Reference","url":"reference/default-policy.html","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.1.0"},"product":{"name":"OpenShell","version":"0.1.0"},"description":"Breakdown of the built-in default policy applied when you create an OpenShell sandbox without a custom policy.","tags":["ai_agents","sandboxing","security","policy"],"topics":["generative_ai","cybersecurity"],"content_type":"reference","learning_level":"technical_beginner","audience":["engineer","data_scientist"],"keywords":["openshell default policy","sandbox policy","agent compatibility"],"content":"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 file. Agent Compatibility The following table shows the coverage of the default policy for common agents. Agent Coverage Action Required Claude Code Full None. Works out of the box. OpenCode Partial Add opencode.ai endpoint and OpenCode binary paths. Codex None Provide a complete custom policy with OpenAI endpoints and Codex binary paths. If you run a non-Claude agent without a custom policy, the agent’s API calls are denied by the proxy. You must provide a policy that declares the agent’s endpoints and binaries. Default Policy Blocks The following tables show the default policy blocks pre-configured in the file. <h2>Filesystem, Landlock, and Process</h2\nSection Setting Value Filesystem Read-only /usr , /lib , /proc , /dev/urandom , /app , /etc , /var/log Read-write /sandbox , /tmp , /dev/null Workdir included Yes Landlock Compatibility best_effort (uses the highest ABI the host kernel supports) Process User / Group sandbox / sandbox <h2>Network Policy Blocks</h2\nEach block pairs a set of endpoints (host and port) with a set of binaries (executable paths inside the sandbox). The proxy identifies the calling binary by resolving the socket to a PID through /proc/net/tcp and reading /proc/{pid}/exe . A connection is allowed only when both the destination and the calling binary match an entry in the same block. All other outbound traffic is denied. <h3>Anthropic API and Telemetry</h3\nAllows Claude Code to reach its API, feature-flagging (Statsig), error reporting (Sentry), release notes, and the Claude platform dashboard. Endpoint Port TLS Access api.anthropic.com 443 terminate full statsig.anthropic.com 443 — L4 passthrough sentry.io 443 — L4 passthrough raw.githubusercontent.com 443 — L4 passthrough platform.claude.com 443 — L4 passthrough Only the following binaries can use these endpoints: /usr/local/bin/claude , /usr/bin/node . <h3>Git Clone and Fetch</h3\nAllows git clone , git fetch , and git pull over HTTPS via Git Smart HTTP. Push ( git-receive-pack ) is disabled by default. Endpoint Port TLS Rules github.com 443 terminate GET /**/info/refs* , POST /**/git-upload-pack Only the following binaries can use these endpoints: /usr/bin/git . <h3>NVIDIA API Catalog</h3\nAllows outbound calls to the NVIDIA hosted inference API. Used by agents that route LLM requests through integrate.api.nvidia.com . Endpoint Port TLS Access integrate.api.nvidia.com 443 — L4 passthrough Only the following binaries can use these endpoints: /usr/bin/curl , /bin/bash , /usr/local/bin/opencode . <h3>GitHub API (Read-Only)</h3\nGrants read-only access to the GitHub REST API. Enables issue reads, PR listing, and repository metadata lookups without allowing mutations. Endpoint Port TLS Access api.github.com 443 terminate read-only Only the following binaries can use these endpoints: /usr/local/bin/claude , /usr/bin/gh . <h3>Python Package Installation</h3\nAllows pip install and uv pip install to reach PyPI, python-build-standalone releases on GitHub, and downloads.python.org . Endpoint Port TLS Access pypi.org 443 — L4 passthrough files.pythonhosted.org 443 — L4 passthrough github.com 443 — L4 passthrough objects.githubusercontent.com 443 — L4 passthrough api.github.com 443 — L4 passthrough downloads.python.org 443 — L4 passthrough Only the following binaries can use these endpoints: /sandbox/.venv/bin/python , /sandbox/.venv/bin/python3 , /sandbox/.venv/bin/pip , /app/.venv/bin/python , /app/.venv/bin/python3 , /app/.venv/bin/pip , /usr/local/bin/uv , /sandbox/.uv/python/** . <h3>VS Code Remote and Marketplace</h3\nAllows VS Code Server, Remote Containers, and extension marketplace traffic so remote development sessions can download updates and extensions. Endpoint Port TLS Access update.code.visualstudio.com 443 — L4 passthrough az764295.vo.msecnd.net 443 — L4 passthrough vscode.download.prss.microsoft.com 443 — L4 passthrough marketplace.visualstudio.com 443 — L4 passthrough gallerycdn.vsassets.io 443 — L4 passthrough Only the following binaries can use these endpoints: /usr/bin/curl , /usr/bin/wget , /sandbox/.vscode-server/** , /sandbox/.vscode-remote-containers/** . <h3>cursor</h3\nEndpoint Port TLS Access cursor.blob.core.windows.net 443 — L4 passthrough api2.cursor.sh 443 — L4 passthrough repo.cursor.sh 443 — L4 passthrough download.cursor.sh 443 — L4 passthrough cursor.download.prss.microsoft.com 443 — L4 passthrough Only the following binaries can use these endpoints: /usr/bin/curl , /usr/bin/wget , /sandbox/.cursor-server/** . <h3>opencode</h3\nEndpoint Port TLS Access registry.npmjs.org 443 — L4 passthrough opencode.ai 443 — L4 passthrough integrate.api.nvidia.com 443 — L4 passthrough Only the following binaries can use these endpoints: /usr/lib/node_modules/opencode-ai/bin/.opencode , /usr/bin/node , /usr/local/bin/opencode","format":"text","content_length":4981,"word_count":665,"summary":"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 file.","headings":[{"text":"Default Policy Reference","level":1,"id":"default-policy-reference"},{"text":"Agent Compatibility","level":2,"id":"agent-compatibility"},{"text":"Default Policy Blocks","level":2,"id":"default-policy-blocks"}],"headings_text":"Default Policy Reference Agent Compatibility Default Policy Blocks","code_blocks":[],"links":[{"text":"Dev Sandbox Policy.Yaml","type":"external","url":"https://github.com/NVIDIA/OpenShell/blob/main/deploy/docker/sandbox/dev-sandbox-policy.yaml","original_text":"deploy/docker/sandbox/dev-sandbox-policy.yaml"}],"images":[],"doc_type":"reference","section_path":["Reference","Default Policy"]},{"id":"reference/policy-schema","title":"Policy Schema Reference","url":"reference/policy-schema.html","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.1.0"},"product":{"name":"OpenShell","version":"0.1.0"},"description":"Complete field reference for the sandbox policy YAML including static and dynamic sections.","tags":["Policy","Schema","YAML","Reference","Security"],"topics":["Generative AI","Cybersecurity"],"content_type":"reference","learning_level":"technical_advanced","audience":["engineer"],"content":"Policy Schema Reference Complete field reference for the sandbox policy YAML. Each field is documented with its type, whether it is required, and whether it is static (locked at sandbox creation) or dynamic (hot-reloadable on a running sandbox). Top-Level Structure A policy YAML file contains the following top-level fields: version: 1\nfilesystem_policy: { ...\nlandlock: { ...\nprocess: { ...\nnetwork_policies: { ...\nField Type Required Category Description version integer Yes – Policy schema version. Must be 1 . filesystem_policy object No Static Controls which directories the agent can read and write. landlock object No Static Configures Landlock LSM enforcement behavior. process object No Static Sets the user and group the agent process runs as. network_policies map No Dynamic Declares which binaries can reach which network endpoints. Static fields are set at sandbox creation time. Changing them requires destroying and recreating the sandbox. Dynamic fields can be updated on a running sandbox with openshell policy set and take effect without restarting. Version The version field identifies which schema the policy uses: Field Type Required Description version integer Yes Schema version number. Currently must be 1 . Filesystem Policy Category: Static Controls filesystem access inside the sandbox. Paths not listed in either read_only or read_write are inaccessible. Field Type Required Description include_workdir bool No When true , automatically adds the agent’s working directory to read_write . read_only list of strings No Paths the agent can read but not modify. Typically system directories like /usr , /lib , /etc . read_write list of strings No Paths the agent can read and write. Typically /sandbox (working directory) and /tmp . Validation constraints: Every path must be absolute (start with / ). Paths must not contain .. traversal components. The server normalizes paths before storage, but rejects policies where traversal would escape the intended scope. Read-write paths must not be overly broad (for example, / alone is rejected). Each individual path must not exceed 4096 characters. The combined total of read_only and read_write paths must not exceed 256. Policies that violate these constraints are rejected with INVALID_ARGUMENT at creation or update time. Disk-loaded YAML policies that fail validation fall back to a restrictive default. Example: filesystem_policy\ninclude_workdir: true\nread_only\n/usr\n/lib\n/proc\n/dev/urandom\n/etc\nread_write\n/sandbox\n/tmp\n/dev/null\nLandlock Category: Static Configures Landlock LSM enforcement at the kernel level. Landlock provides mandatory filesystem access control below what UNIX permissions allow. Field Type Required Values Description compatibility string No best_effort , hard_requirement How OpenShell handles kernel ABI differences. best_effort uses the highest Landlock ABI the host kernel supports. hard_requirement fails if the required ABI is unavailable. Example: landlock\ncompatibility: best_effort\nProcess Category: Static Sets the OS-level identity for the agent process inside the sandbox. Field Type Required Description run_as_user string No The user name or UID the agent process runs as. Default: sandbox . run_as_group string No The group name or GID the agent process runs as. Default: sandbox . Validation constraint: Neither run_as_user nor run_as_group may be set to root or 0 . Policies that request root process identity are rejected at creation or update time. Example: process\nrun_as_user: sandbox\nrun_as_group: sandbox\nNetwork Policies Category: Dynamic A map of named network policy entries. Each entry declares a set of endpoints and a set of binaries. Only the listed binaries are permitted to connect to the listed endpoints. The map key is a logical identifier. The name field inside the entry is the display name used in logs. 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. endpoints list of endpoint objects Yes Hosts and ports this entry permits. binaries list of binary objects Yes Executables allowed to connect to these endpoints. Endpoint Object Each endpoint defines a reachable destination and optional inspection rules. Field Type Required Description host string Yes Hostname or IP address. Supports wildcards: *.example.com matches any subdomain. port integer Yes TCP port number. protocol string No Set to rest to enable HTTP request inspection. Omit for TCP passthrough. tls string No TLS handling mode. terminate decrypts TLS at the proxy for inspection. passthrough forwards encrypted traffic without inspection. Only relevant when protocol is rest . enforcement string No enforce actively blocks disallowed requests. audit logs violations but allows traffic through. access string No HTTP access level. One of read-only , read-write , or full . Mutually exclusive with rules . rules list of rule objects No Fine-grained per-method, per-path allow rules. Mutually exclusive with access . Access Levels The access field accepts one of the following values: Value Allowed HTTP Methods full All methods and paths. read-only GET , HEAD , OPTIONS . read-write GET , HEAD , OPTIONS , POST , PUT , PATCH . Rule Object Used when access is not set. Each rule explicitly allows a method and path combination. Field Type Required Description allow.method string Yes HTTP method to allow (for example, GET , POST ). allow.path string Yes URL path pattern. Supports * and ** glob syntax. Example with rules: rules\nallow\nmethod: GET\npath: /**/info/refs\nallow\nmethod: POST\npath: /**/git-upload-pack\nBinary Object Identifies an executable that is permitted to use the associated endpoints. Field Type Required Description path string Yes Filesystem path to the executable. Supports glob patterns with * and ** . For example, /sandbox/.vscode-server/** matches any executable under that directory tree. Full Example The following policy grants read-only GitHub API access and npm registry access: network_policies\ngithub_rest_api\nname: github-rest-api\nendpoints\nhost: api.github.com\nport: 443\nprotocol: rest\ntls: terminate\nenforcement: enforce\naccess: read-only\nbinaries\npath: /usr/local/bin/claude\npath: /usr/bin/node\npath: /usr/bin/gh\nnpm_registry\nname: npm-registry\nendpoints\nhost: registry.npmjs.org\nport: 443\nbinaries\npath: /usr/bin/npm\npath: /usr/bin/node","format":"text","content_length":6442,"word_count":955,"summary":"Complete field reference for the sandbox policy YAML. Each field is documented with its type, whether it is required, and whether it is static (locked at sandbox creation) or dynamic (hot-reloadable on a running sandbox).","headings":[{"text":"Policy Schema Reference","level":1,"id":"policy-schema-reference"},{"text":"Top-Level Structure","level":2,"id":"top-level-structure"},{"text":"Version","level":2,"id":"version"},{"text":"Filesystem Policy","level":2,"id":"filesystem-policy"},{"text":"Landlock","level":2,"id":"landlock"},{"text":"Process","level":2,"id":"process"},{"text":"Network Policies","level":2,"id":"network-policies"},{"text":"Network Policy Entry","level":3,"id":"network-policy-entry"},{"text":"Endpoint Object","level":3,"id":"endpoint-object"},{"text":"Access Levels","level":4,"id":"access-levels"},{"text":"Rule Object","level":4,"id":"rule-object"},{"text":"Binary Object","level":3,"id":"binary-object"},{"text":"Full Example","level":3,"id":"full-example"}],"headings_text":"Policy Schema Reference Top-Level Structure Version Filesystem Policy Landlock Process Network Policies Network Policy Entry Endpoint Object Access Levels Rule Object Binary Object Full Example","keywords":["access","allowed","binary","category","changing","com","compatibility","complete","configures","constraint","constraints","controls","currently","declares","default","defaults","description","disk","display","dynamic","each","endpoint","enforcement","entry","every","example","executables","field","fields","filesystem","filesystem_policy","fine","full","github","host","hostname","hosts","identifies","include_workdir","landlock","level","levels","method","methods","must","mutually","name","neither","network","network_policies"],"code_blocks":[{"content":"version: 1\nfilesystem_policy: { ... }\nlandlock: { ... }\nprocess: { ... }\nnetwork_policies: { ... }","language":"text"},{"content":"filesystem_policy:\n  include_workdir: true\n  read_only:\n    - /usr\n    - /lib\n    - /proc\n    - /dev/urandom\n    - /etc\n  read_write:\n    - /sandbox\n    - /tmp\n    - /dev/null","language":"text"},{"content":"landlock:\n  compatibility: best_effort","language":"text"},{"content":"process:\n  run_as_user: sandbox\n  run_as_group: sandbox","language":"text"},{"content":"rules:\n  - allow:\n      method: GET\n      path: /**/info/refs*\n  - allow:\n      method: POST\n      path: /**/git-upload-pack","language":"text"},{"content":"network_policies:\n  github_rest_api:\n    name: github-rest-api\n    endpoints:\n      - host: api.github.com\n        port: 443\n        protocol: rest\n        tls: terminate\n        enforcement: enforce\n        access: read-only\n    binaries:\n      - path: /usr/local/bin/claude\n      - path: /usr/bin/node\n      - path: /usr/bin/gh\n  npm_registry:\n    name: npm-registry\n    endpoints:\n      - host: registry.npmjs.org\n        port: 443\n    binaries:\n      - path: /usr/bin/npm\n      - path: /usr/bin/node","language":"text"}],"links":[{"text":"Landlock LSM","type":"external","url":"https://docs.kernel.org/security/landlock.html"}],"images":[],"doc_type":"reference","section_path":["Reference","Policy Schema"]},{"id":"reference/support-matrix","title":"Support Matrix","url":"reference/support-matrix.html","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.1.0"},"product":{"name":"OpenShell","version":"0.1.0"},"content":"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 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 Gateway ghcr.io ghcr.io/nvidia/openshell/gateway:latest Cluster startup (via Helm chart) Sandbox ghcr.io ghcr.io/nvidia/openshell/sandbox:latest First sandbox creation (via Helm chart) Community sandboxes GHCR ghcr.io/nvidia/openshell-community/sandboxes/{name}:latest openshell sandbox create --from <name> 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 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 table","format":"text","content_length":3060,"word_count":402,"summary":"This page lists the platform, software, runtime, and kernel requirements for running OpenShell.","headings":[{"text":"Support Matrix","level":1,"id":"support-matrix"},{"text":"Supported Platforms","level":2,"id":"supported-platforms"},{"text":"Software Prerequisites","level":2,"id":"software-prerequisites"},{"text":"Sandbox Runtime Versions","level":2,"id":"sandbox-runtime-versions"},{"text":"Container Images","level":2,"id":"container-images"},{"text":"Kernel Requirements","level":2,"id":"kernel-requirements"},{"text":"Agent Compatibility","level":2,"id":"agent-compatibility"}],"headings_text":"Support Matrix Supported Platforms Software Prerequisites Sandbox Runtime Versions Container Images Kernel Requirements Agent Compatibility","keywords":["agent","agents","apple","architecture","available","base","bookworm","claude","cluster","code","codex","community","compatibility","component","container","debian","desktop","details","docker","enforces","engine","filters","first","gateway","helm","image","images","intel","k3s","kernel","kubernetes","landlock","latest","linux","matrix","minimum","module","modules","must","node","notes","opencode","openshell","override","platform","platforms","prerequisites","pulled","purpose","python"],"code_blocks":[],"links":[{"text":"Uv","type":"external","url":"https://docs.astral.sh/uv/","original_text":"uv"},{"text":"Landlock LSM","type":"external","url":"https://docs.kernel.org/security/landlock.html"}],"images":[],"doc_type":"reference","section_path":["Reference","Support Matrix"]},{"id":"resources/eula","title":"License","url":"resources/eula.html","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.1.0"},"product":{"name":"OpenShell","version":"0.1.0"},"description":"NVIDIA OpenShell license agreement and terms of use.","tags":["License","EULA"],"topics":["Legal"],"content_type":"reference","learning_level":"technical_beginner","audience":["engineer","data_scientist"],"content":"License","format":"text","content_length":7,"word_count":1,"summary":"<!-- SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. SPDX-License-Identifier: Apache-2.0 --> License","headings":[{"text":"License","level":1,"id":"license"}],"headings_text":"License","keywords":["license"],"code_blocks":[],"links":[],"images":[],"doc_type":"documentation","section_path":["Resources","Eula"]},{"id":"sandboxes/community-sandboxes","title":"Community Sandboxes","url":"sandboxes/community-sandboxes.html","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.1.0"},"product":{"name":"OpenShell","version":"0.1.0"},"description":"Use pre-built sandboxes from the OpenShell Community catalog or contribute your own.","tags":["Community","Sandbox","Container Image","Open Source"],"topics":["Generative AI","Cybersecurity"],"content_type":"concept","learning_level":"technical_beginner","audience":["engineer","data_scientist"],"content":"Community Sandboxes Use pre-built sandboxes from the OpenShell Community catalog, or contribute your\nown. What Are Community Sandboxes Community sandboxes are ready-to-use environments published in the\nOpenShell Community repository\nEach sandbox bundles a Dockerfile, policy, optional skills, and startup scripts\ninto a single package that you can launch with one command. Current Catalog The following community sandboxes are available in the catalog. Sandbox Description base Foundational image with system tools and dev environment openclaw Open agent manipulation and control sdg Synthetic data generation workflows simulation General-purpose simulation sandboxes Use a Community Sandbox Launch a community sandbox by name with the --from flag: $ openshell sandbox create --from openclaw\nWhen you pass --from with a community sandbox name, the CLI: Resolves the name against the\nOpenShell Community repository. Pulls the Dockerfile, policy, skills, and any startup scripts. Builds the container image locally. Creates the sandbox with the bundled configuration applied. You end up with a running sandbox whose image, policy, and tooling are all\npreconfigured by the community package. Other Sources The --from flag also accepts: Local directory paths: Point to a directory on disk that contains a\nDockerfile and optional policy/skills: $ openshell sandbox create --from ./my-sandbox-dir\nContainer image references: Use an existing container image directly: $ openshell sandbox create --from my-registry.example.com/my-image:latest\nContribute a Community Sandbox Each community sandbox is a directory under sandboxes/ in the\nOpenShell Community repository\nAt minimum, a sandbox directory must contain: Dockerfile : Defines the container image README.md : Describes the sandbox and how to use it Optional files: policy.yaml : Default policy applied when the sandbox launches skills/ : Agent skill definitions bundled with the sandbox Startup scripts: Any scripts the Dockerfile or entrypoint invokes To contribute, fork the repository, add your sandbox directory, and open a pull\nrequest. Refer to the repository’s\nCONTRIBUTING.md\nfor submission guidelines. The community catalog is designed to grow. If you have built a sandbox that\nsupports a particular workflow (data processing, simulation, code review\nor 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 providers for credential management. Want to customize the sandbox policy? Write custom rules in policies","format":"text","content_length":2562,"word_count":367,"summary":"Use pre-built sandboxes from the OpenShell Community catalog, or contribute your own.","headings":[{"text":"Community Sandboxes","level":1,"id":"community-sandboxes"},{"text":"What Are Community Sandboxes","level":2,"id":"what-are-community-sandboxes"},{"text":"Current Catalog","level":2,"id":"current-catalog"},{"text":"Use a Community Sandbox","level":2,"id":"use-a-community-sandbox"},{"text":"Other Sources","level":3,"id":"other-sources"},{"text":"Contribute a Community Sandbox","level":2,"id":"contribute-a-community-sandbox"},{"text":"Next Steps","level":2,"id":"next-steps"}],"headings_text":"Community Sandboxes What Are Community Sandboxes Current Catalog Use a Community Sandbox Other Sources Contribute a Community Sandbox Next Steps","keywords":["accepts","agent","any","builds","catalog","com","community","contain","container","contribute","creates","current","default","defines","describes","description","directly","dockerfile","each","explore","files","flag","foundational","general","image","launch","local","need","next","open","openshell","optional","other","paths","point","pulls","refer","references","resolves","sandbox","sandboxes","scripts","set","skills","sources","startup","steps","synthetic","topics","want"],"code_blocks":[{"content":"$ openshell sandbox create --from openclaw","language":"text"},{"content":"$ openshell sandbox create --from ./my-sandbox-dir","language":"text"},{"content":"$ openshell sandbox create --from my-registry.example.com/my-image:latest","language":"text"}],"links":[{"text":"OpenShell Community","type":"external","url":"https://github.com/NVIDIA/OpenShell-Community"},{"text":"OpenShell Community","type":"external","url":"https://github.com/NVIDIA/OpenShell-Community"},{"text":"OpenShell Community","type":"external","url":"https://github.com/NVIDIA/OpenShell-Community"},{"text":"Contributing","type":"external","url":"https://github.com/NVIDIA/OpenShell-Community/blob/main/CONTRIBUTING.md","original_text":"CONTRIBUTING.md"}],"images":[],"doc_type":"tutorial","section_path":["Sandboxes","Community Sandboxes"]},{"id":"sandboxes/create-and-manage","title":"Create and Manage Sandboxes","url":"sandboxes/create-and-manage.html","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.1.0"},"product":{"name":"OpenShell","version":"0.1.0"},"description":"Create, inspect, connect to, monitor, transfer files, and delete OpenShell sandboxes.","tags":["Sandboxing","AI Agents","Sandbox Management","CLI"],"topics":["Generative AI","Cybersecurity"],"content_type":"how_to","learning_level":"technical_beginner","audience":["engineer","data_scientist"],"content":"Create and Manage Sandboxes 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 . Docker must be running before you create a sandbox. If it is not, the CLI\nreturns a connection-refused error ( os error 61 ) without explaining\nthe cause. Start Docker and try again. Create a Sandbox Run a single command to create a sandbox and launch your agent: $ openshell sandbox create -- claude\nIf you have an existing gateway, the sandbox is created in it. Otherwise, a gateway is created automatically. To request GPU resources explicitly, add --gpu : $ openshell sandbox create --gpu -- claude\nIf no gateway is running, the auto-bootstrap path starts a GPU-enabled gateway first. A fully specified creation command might look like: $ openshell sandbox create\nname dev\nprovider my-claude\npolicy policy.yaml\nupload\nkeep\nclaude\nUse --keep to keep the sandbox running after the trailing command exits\nThis is especially useful when you are iterating on a policy or want to\nreconnect later from another terminal or VS Code. Create from a Community Sandbox or Custom Image Use --from to create a sandbox from a pre-built community package, a local directory, or a container image: $ openshell sandbox create --from openclaw\nThe CLI resolves the name against the OpenShell Community catalog, pulls the bundled Dockerfile and policy, builds the image locally, and creates the sandbox. For the full catalog and how to contribute your own, refer to community-sandboxes . You can also point --from at a local directory or a container image reference: $ openshell sandbox create --from ./my-sandbox-dir\nopenshell sandbox create --from my-registry.example.com/my-image:latest\nImages whose final name component contains gpu also trigger GPU sandbox requests automatically. For example, --from nvidia-gpu behaves like a GPU sandbox request even without --gpu . List and Inspect Sandboxes Check the status of your sandboxes and retrieve detailed information about individual ones. List all sandboxes: $ openshell sandbox list\nGet detailed information about a specific sandbox: $ openshell sandbox get my-sandbox\nConnect to a Sandbox Access a running sandbox through an interactive SSH session or VS Code Remote-SSH. Interactive SSH Open an SSH session into a running sandbox: $ openshell sandbox connect my-sandbox\nOpen in a remote editor Launch VS Code or Cursor directly into the sandbox workspace: $ openshell sandbox create --editor vscode --name my-sandbox\nopenshell sandbox connect my-sandbox --editor cursor\nWhen --editor is used, OpenShell keeps the sandbox alive and installs an\nOpenShell-managed SSH include file instead of cluttering your main\nssh/config with generated host blocks. View Logs Stream and filter sandbox logs to monitor agent activity and diagnose policy decisions. Stream sandbox logs: $ openshell logs my-sandbox\nUse flags to filter and follow output: Flag Purpose Example --tail Stream logs in real time openshell logs my-sandbox --tail --source Filter by log source --source sandbox --level Filter by severity --level warn --since Show logs from a time window --since 5m Monitor Your Sandbox OpenShell Terminal is a real-time dashboard that combines sandbox status and live logs in a single view. $ openshell term\nThe dashboard shows the following information. 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 policies for the workflow. Transfer Files Transfer files between your host machine and a running sandbox. Upload files from your host into the sandbox: $ openshell sandbox upload my-sandbox ./src /sandbox/src\nDownload files from the sandbox to your host: $ openshell sandbox download my-sandbox /sandbox/output ./local\nYou can also upload files at creation time with the --upload flag on\nopenshell sandbox create . Delete Sandboxes Remove sandboxes when they are no longer needed. Deleting a sandbox stops all processes, releases cluster resources, and purges injected credentials. Delete a sandbox by name: $ openshell sandbox delete my-sandbox\nDelete all sandboxes in the active gateway: $ openshell sandbox delete --all\nNext Steps Explore related topics: To follow a complete end-to-end example, refer to the /tutorials/github-sandbox tutorial. To supply API keys or tokens, refer to providers . To control what the agent can access, refer to policies . To use a pre-built environment, refer to the community-sandboxes catalog","format":"text","content_length":4970,"word_count":758,"summary":"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.","headings":[{"text":"Create and Manage Sandboxes","level":1,"id":"create-and-manage-sandboxes"},{"text":"Create a Sandbox","level":2,"id":"create-a-sandbox"},{"text":"Create from a Community Sandbox or Custom Image","level":2,"id":"create-from-a-community-sandbox-or-custom-image"},{"text":"List and Inspect Sandboxes","level":2,"id":"list-and-inspect-sandboxes"},{"text":"Connect to a Sandbox","level":2,"id":"connect-to-a-sandbox"},{"text":"Interactive SSH","level":3,"id":"interactive-ssh"},{"text":"Open in a remote editor","level":3,"id":"open-in-a-remote-editor"},{"text":"View Logs","level":2,"id":"view-logs"},{"text":"Monitor Your Sandbox","level":2,"id":"monitor-your-sandbox"},{"text":"Transfer Files","level":2,"id":"transfer-files"},{"text":"Delete Sandboxes","level":2,"id":"delete-sandboxes"},{"text":"Next Steps","level":2,"id":"next-steps"}],"headings_text":"Create and Manage Sandboxes Create a Sandbox Create from a Community Sandbox or Custom Image List and Inspect Sandboxes Connect to a Sandbox Interactive SSH Open in a remote editor View Logs Monitor Your Sandbox Transfer Files Delete Sandboxes Next Steps","keywords":["about","access","action","agent","check","code","com","community","connect","create","cursor","custom","delete","deleting","docker","dockerfile","download","editor","example","explore","files","filter","flag","from","gateway","gpu","host","image","images","inspect","interactive","launch","lifecycle","like","list","live","logs","manage","monitor","name","next","omutbound","open","openshell","otherwise","output","purpose","reference","remote","remove"],"code_blocks":[{"content":"$ openshell sandbox create -- claude","language":"text"},{"content":"$ openshell sandbox create --gpu -- claude","language":"text"},{"content":"$ openshell sandbox create \\\n    --name dev \\\n    --provider my-claude \\\n    --policy policy.yaml \\\n    --upload \\\n    --keep \\\n    -- claude","language":"text"},{"content":"$ openshell sandbox create --from openclaw","language":"text"},{"content":"$ openshell sandbox create --from ./my-sandbox-dir\n$ openshell sandbox create --from my-registry.example.com/my-image:latest","language":"text"},{"content":"$ openshell sandbox list","language":"text"},{"content":"$ openshell sandbox get my-sandbox","language":"text"},{"content":"$ openshell sandbox connect my-sandbox","language":"text"},{"content":"$ openshell sandbox create --editor vscode --name my-sandbox\n$ openshell sandbox connect my-sandbox --editor cursor","language":"text"},{"content":"$ openshell logs my-sandbox","language":"text"},{"content":"$ openshell term","language":"text"},{"content":"$ openshell sandbox upload my-sandbox ./src /sandbox/src","language":"text"},{"content":"$ openshell sandbox download my-sandbox /sandbox/output ./local","language":"text"},{"content":"$ openshell sandbox delete my-sandbox","language":"text"},{"content":"$ openshell sandbox delete --all","language":"text"}],"links":[{"text":"OpenShell Community","type":"external","url":"https://github.com/NVIDIA/OpenShell-Community"}],"images":[],"doc_type":"tutorial","section_path":["Sandboxes","Create And Manage"]},{"id":"sandboxes/index","title":"About Sandboxes","url":"sandboxes/index.html","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.1.0"},"product":{"name":"OpenShell","version":"0.1.0"},"description":"Understand sandbox lifecycle, supported agents, built-in default policy, and network access rules in OpenShell.","tags":["Sandboxing","AI Agents","Security","Policy","Isolation"],"topics":["Generative AI","Cybersecurity"],"content_type":"concept","learning_level":"technical_beginner","audience":["engineer","data_scientist"],"content":"About Sandboxes An OpenShell sandbox is a safe, private execution environment for an AI agent. Each sandbox runs with multiple layers of protection that prevent unauthorized data access, credential exposure, and network exfiltration. Protection layers include filesystem restrictions (Landlock), system call filtering (seccomp), network namespace isolation, and a privacy-enforcing HTTP CONNECT proxy. Sandbox Lifecycle Every sandbox moves through a defined set of phases: Phase Description Provisioning The runtime is setting up the sandbox environment, injecting credentials, and applying your policy. Ready The sandbox is running. The agent process is active and all isolation layers are enforced. You can connect, sync files, and view logs. 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 community-sandboxes catalog. Agent Source Default Policy Notes Claude Code Built-in Full coverage Works out of the box. Requires ANTHROPIC_API_KEY . OpenCode Built-in Partial coverage Pre-installed. Add opencode.ai endpoint and OpenCode binary paths to the policy for full functionality. Codex Built-in No coverage Pre-installed. Requires a custom policy with OpenAI endpoints and Codex binary paths. Requires OPENAI_API_KEY . OpenClaw OpenShell Community Bundled Agent orchestration layer. Launch with openshell sandbox create --from openclaw\nBuilt-in Default Policy OpenShell ships a built-in policy that covers common agent workflows out of the box\nWhen you create a sandbox without --policy , the default policy is applied. It controls three things: Layer What It Controls How It Works Filesystem What the agent can access on disk Paths are split into read-only and read-write sets. Landlock LSM enforces these restrictions at the kernel level. 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, refer to ../reference/default-policy . Policy Structure A policy has static sections ( filesystem_policy , landlock , process ) that are locked at sandbox creation, and dynamic sections ( network_policies , inference ) that are hot-reloadable on a running sandbox. version: 1\nStatic: locked at sandbox creation. Paths the agent can read vs read/write\nfilesystem_policy\nread_only: [/usr, /lib, /etc\nread_write: [/sandbox, /tmp\nStatic: Landlock LSM kernel enforcement. best_effort uses highest ABI the host supports\nlandlock\ncompatibility: best_effort\nStatic: Unprivileged user/group the agent process runs as\nprocess\nrun_as_user: sandbox\nrun_as_group: sandbox\nDynamic: hot-reloadable. Named blocks of endpoints + binaries allowed to reach them\nnetwork_policies\nmy_api\nname: my-api\nendpoints\nhost: api.example.com\nport: 443\nprotocol: rest\ntls: terminate\nenforcement: enforce\naccess: full\nbinaries\npath: /usr/bin/curl\nDynamic: hot-reloadable. Routing hints this sandbox can use for inference (e.g. local, nvidia\ninference\nallowed_routes: [local\nFor the complete structure and every field, refer to the Policy Schema Reference . 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. Every outbound connection from the sandbox goes through the proxy: The proxy queries the policy engine 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 Continue with one of the following: To create your first sandbox, refer to create-and-manage . To supply API keys or tokens, refer to providers . To control what the agent can access, refer to policies . To use a pre-built environment, refer to the community-sandboxes catalog","format":"text","content_length":4999,"word_count":737,"summary":"An OpenShell sandbox is a safe, private execution environment for an AI agent. Each sandbox runs with multiple layers of protection that prevent unauthorized data access, credential exposure, and network exfiltration. Protection layers include filesystem restrictions (Landlock), system call filte...","headings":[{"text":"About Sandboxes","level":1,"id":"about-sandboxes"},{"text":"Sandbox Lifecycle","level":2,"id":"sandbox-lifecycle"},{"text":"Supported Agents","level":2,"id":"supported-agents"},{"text":"Built-in Default Policy","level":2,"id":"built-in-default-policy"},{"text":"Policy Structure","level":2,"id":"policy-structure"},{"text":"Network Access Rules","level":2,"id":"network-access-rules"},{"text":"Next Steps","level":2,"id":"next-steps"}],"headings_text":"About Sandboxes Sandbox Lifecycle Supported Agents Built-in Default Policy Policy Structure Network Access Rules Next Steps","keywords":["about","access","add","agent","agents","allowed_routes","both","built","bundled","check","claude","code","codex","com","community","compatibility","continue","controls","default","deleting","description","dynamic","each","endpoints","enforcement","error","every","filesystem","following","full","host","landlock","launch","layer","lifecycle","more","name","named","network","next","notes","openai","openclaw","opencode","openshell","otherwise","partial","path","paths","phase"],"code_blocks":[{"content":"version: 1\n\n# Static: locked at sandbox creation. Paths the agent can read vs read/write.\nfilesystem_policy:\n  read_only: [/usr, /lib, /etc]\n  read_write: [/sandbox, /tmp]\n\n# Static: Landlock LSM kernel enforcement. best_effort uses highest ABI the host supports.\nlandlock:\n  compatibility: best_effort\n\n# Static: Unprivileged user/group the agent process runs as.\nprocess:\n  run_as_user: sandbox\n  run_as_group: sandbox\n\n# Dynamic: hot-reloadable. Named blocks of endpoints + binaries allowed to reach them.\nnetwork_policies:\n  my_api:\n    name: my-api\n    endpoints:\n      - host: api.example.com\n        port: 443\n        protocol: rest\n        tls: terminate\n        enforcement: enforce\n        access: full\n    binaries:\n      - path: /usr/bin/curl\n\n# Dynamic: hot-reloadable. Routing hints this sandbox can use for inference (e.g. local, nvidia).\ninference:\n  allowed_routes: [local]","language":"text"}],"links":[{"text":"Claude Code","type":"external","url":"https://docs.anthropic.com/en/docs/claude-code"},{"text":"OpenCode","type":"external","url":"https://opencode.ai/"},{"text":"Codex","type":"external","url":"https://developers.openai.com/codex"},{"text":"OpenClaw","type":"external","url":"https://openclaw.ai/"},{"text":"OpenShell Community","type":"external","url":"https://github.com/NVIDIA/OpenShell-Community/tree/main/sandboxes/openclaw"},{"text":"Landlock LSM","type":"external","url":"https://docs.kernel.org/security/landlock.html"}],"images":[],"doc_type":"overview","section_path":["Sandboxes"]},{"id":"sandboxes/policies","title":"Customize Sandbox Policies","url":"sandboxes/policies.html","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.1.0"},"product":{"name":"OpenShell","version":"0.1.0"},"description":"Apply, iterate, and debug sandbox network policies with hot-reload on running OpenShell sandboxes.","tags":["Policy","Network Policy","Sandbox","Security","Hot Reload"],"topics":["Generative AI","Cybersecurity"],"content_type":"how_to","learning_level":"technical_intermediate","audience":["engineer"],"content":"Customize Sandbox Policies Use this page to apply and iterate policy changes on running sandboxes. For a full field-by-field YAML definition, use the Policy Schema Reference . Quick Start: Apply a Custom Policy Pass a policy YAML file when creating the sandbox: $ openshell sandbox create --policy ./my-policy.yaml --keep -- claude\nThe --keep flag keeps the sandbox running after the initial command exits, which is useful when you plan to iterate on the policy. To avoid passing --policy every time, set a default policy with an environment variable: $ export OPENSHELL_SANDBOX_POLICY=./my-policy.yaml\nopenshell sandbox create --keep -- claude\nThe CLI uses the policy from OPENSHELL_SANDBOX_POLICY whenever --policy is not explicitly provided. Iterate on a Running Sandbox To change what the sandbox can access, pull the current policy, edit the YAML, and push the update. The workflow is iterative: create the sandbox, monitor logs for denied actions, pull the policy, modify it, push, and verify. The following steps outline the hot-reload policy update workflow. Create the sandbox with your initial policy by following Quick Start: Apply a Custom Policy above (or set OPENSHELL_SANDBOX_POLICY ). Monitor denials. Each log entry shows host, port, binary, and reason. Alternatively, use openshell term for a live dashboard. $ openshell logs <name> --tail --source sandbox\nPull the current policy. Strip the metadata header (Version, Hash, Status) before reusing the file. $ openshell policy get <name> --full > current-policy.yaml\nEdit the YAML: add or adjust network_policies entries, binaries, access or rules , or inference.allowed_routes . Push the updated policy. Exit codes: 0 = loaded, 1 = validation failed, 124 = timeout. $ openshell policy set <name> --policy current-policy.yaml --wait\nVerify the new revision. If status is loaded , repeat from step 2 as needed; if failed , fix the policy and repeat from step 4. $ openshell policy list <name\nDebug Denied Requests Check openshell logs <name> --tail --source sandbox for the denied host, path, and binary. When triaging denied requests, check: Destination host and port to confirm which endpoint is missing. Calling binary path to confirm which binaries entry needs to be added or adjusted. HTTP method and path (for REST endpoints) to confirm which rules entry needs to be added or adjusted. Then push the updated policy as described above. Examples Add these blocks to the network_policies section of your sandbox policy. Apply with openshell policy set <name> --policy <file> --wait\nUse Simple endpoint for host-level allowlists and Granular rules for method/path control. Simple endpoint Allow pip install and uv pip install to reach PyPI: pypi\nname: pypi\nendpoints\nhost: pypi.org\nport: 443\nhost: files.pythonhosted.org\nport: 443\nbinaries\n{ path: /usr/bin/pip\n{ path: /usr/local/bin/uv\nEndpoints without protocol or tls use TCP passthrough — the proxy allows the stream without inspecting payloads. Granular rules 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 <org_name> with your GitHub org or username. For an end-to-end walkthrough that combines this policy with a GitHub credential provider and sandbox creation, refer to /tutorials/github-sandbox . github_repos\nname: github_repos\nendpoints\nhost: api.github.com\nport: 443\nprotocol: rest\ntls: terminate\nenforcement: enforce\nrules\nallow\nmethod: GET\npath:\nallow\nmethod: HEAD\npath:\nallow\nmethod: OPTIONS\npath:\nallow\nmethod: POST\npath: \"/graphql\nallow\nmethod:\npath: \"/repos/<org_name>/alpha-repo\nallow\nmethod: POST\npath: \"/repos/<org_name>/bravo-repo/issues\nallow\nmethod: PATCH\npath: \"/repos/<org_name>/bravo-repo/issues\nbinaries\n{ path: /usr/local/bin/claude\n{ path: /usr/bin/gh\nEndpoints with protocol: rest and tls: terminate enable HTTP request inspection — the proxy decrypts TLS and checks each HTTP request against the rules list. Next Steps Explore related topics: To learn about policy structure and network access rules, refer to index . To view the full field-by-field YAML definition, refer to the Policy Schema Reference . To review the default policy breakdown, refer to ../reference/default-policy","format":"text","content_length":4315,"word_count":639,"summary":"Use this page to apply and iterate policy changes on running sandboxes. For a full field-by-field YAML definition, use the Policy Schema Reference.","headings":[{"text":"Customize Sandbox Policies","level":1,"id":"customize-sandbox-policies"},{"text":"Quick Start: Apply a Custom Policy","level":2,"id":"quick-start-apply-a-custom-policy"},{"text":"Iterate on a Running Sandbox","level":2,"id":"iterate-on-a-running-sandbox"},{"text":"Debug Denied Requests","level":2,"id":"debug-denied-requests"},{"text":"Examples","level":2,"id":"examples"},{"text":"Next Steps","level":2,"id":"next-steps"}],"headings_text":"Customize Sandbox Policies Quick Start: Apply a Custom Policy Iterate on a Running Sandbox Debug Denied Requests Examples Next Steps","keywords":["add","allow","alternatively","apply","calling","check","claude","codes","com","create","custom","customize","debug","denied","destination","each","edit","endpoints","enforcement","examples","exit","explore","github","granular","graphql","hash","host","iterate","iterative","method","monitor","name","next","org","pass","path","policies","policy","port","protocol","pull","push","pypi","quick","reference","replace","requests","rules","running","sandbox"],"code_blocks":[{"content":"$ openshell sandbox create --policy ./my-policy.yaml --keep -- claude","language":"text"},{"content":"$ export OPENSHELL_SANDBOX_POLICY=./my-policy.yaml\n$ openshell sandbox create --keep -- claude","language":"text"},{"content":"$ openshell logs <name> --tail --source sandbox","language":"text"},{"content":"$ openshell policy get <name> --full > current-policy.yaml","language":"text"},{"content":"$ openshell policy set <name> --policy current-policy.yaml --wait","language":"text"},{"content":"$ openshell policy list <name>","language":"text"},{"content":"pypi:\n    name: pypi\n    endpoints:\n      - host: pypi.org\n        port: 443\n      - host: files.pythonhosted.org\n        port: 443\n    binaries:\n      - { path: /usr/bin/pip }\n      - { path: /usr/local/bin/uv }","language":"text"},{"content":"github_repos:\n    name: github_repos\n    endpoints:\n      - host: api.github.com\n        port: 443\n        protocol: rest\n        tls: terminate\n        enforcement: enforce\n        rules:\n          - allow:\n              method: GET\n              path: \"/**\"\n          - allow:\n              method: HEAD\n              path: \"/**\"\n          - allow:\n              method: OPTIONS\n              path: \"/**\"\n          - allow:\n              method: POST\n              path: \"/graphql\"\n          - allow:\n              method: \"*\"\n              path: \"/repos/<org_name>/alpha-repo/**\"\n          - allow:\n              method: POST\n              path: \"/repos/<org_name>/bravo-repo/issues\"\n          - allow:\n              method: PATCH\n              path: \"/repos/<org_name>/bravo-repo/issues/*\"\n    binaries:\n      - { path: /usr/local/bin/claude }\n      - { path: /usr/bin/gh }","language":"text"}],"links":[{"text":"Quick Start: Apply a Custom Policy","type":"anchor","url":"#quick-start-apply-a-custom-policy"}],"images":[],"doc_type":"tutorial","section_path":["Sandboxes","Policies"]},{"id":"sandboxes/providers","title":"Providers","url":"sandboxes/providers.html","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.1.0"},"product":{"name":"OpenShell","version":"0.1.0"},"description":"Create and manage credential providers that inject API keys and tokens into OpenShell sandboxes.","tags":["Providers","Credentials","API Keys","Sandbox","Security"],"topics":["Generative AI","Cybersecurity"],"content_type":"how_to","learning_level":"technical_beginner","audience":["engineer","data_scientist"],"content":"Providers AI agents typically need credentials to access external services: an API key for the AI model provider, a token for GitHub or GitLab, and so on. OpenShell manages these credentials as first-class entities called providers . Create and manage providers that supply credentials to sandboxes. Create a Provider Providers can be created from local environment variables or with explicit credential values. From Local Credentials The fastest way to create a provider is to let the CLI discover credentials from\nyour shell environment: $ openshell provider create --name my-claude --type claude --from-existing\nThis reads ANTHROPIC_API_KEY or CLAUDE_API_KEY from your current environment\nand stores them in the provider. With Explicit Credentials Supply a credential value directly: $ openshell provider create --name my-api --type generic --credential API_KEY=sk-abc123\nBare Key Form Pass a key name without a value to read the value from the environment variable\nof that name: $ openshell provider create --name my-api --type generic --credential API_KEY\nThis looks up the current value of $API_KEY in your shell and stores it. Manage Providers List, inspect, update, and delete providers from the active cluster. List all providers: $ openshell provider list\nInspect a provider: $ openshell provider get my-claude\nUpdate a provider’s credentials: $ openshell provider update my-claude --type claude --from-existing\nDelete a provider: $ openshell provider delete my-claude\nAttach Providers to Sandboxes Pass one or more --provider flags when creating a sandbox: $ openshell sandbox create --provider my-claude --provider my-github -- claude\nEach --provider flag attaches one provider. The sandbox receives all\ncredentials from every attached provider at runtime. Providers cannot be added to a running sandbox. If you need to attach an\nadditional provider, delete the sandbox and recreate it with all required\nproviders specified. Auto-Discovery Shortcut When the trailing command in openshell sandbox create is a recognized tool name ( claude , codex , or opencode ), the CLI auto-creates the required\nprovider from your local credentials if one does not already exist. You do not\nneed to create the provider separately: $ openshell sandbox create -- claude\nThis detects claude as a known tool, finds your ANTHROPIC_API_KEY , creates\na provider, attaches it to the sandbox, and launches Claude Code. Supported Provider Types The following provider types are supported. Type Environment Variables Injected Typical Use 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 — refer to /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 outlook (none: no auto-discovery) Microsoft Outlook integration Use the generic type for any service not listed above. You define the\nenvironment variable names and values yourself with --credential . Next Steps Explore related topics: To control what the agent can access, refer to policies . To use a pre-built environment, refer to the community-sandboxes catalog. To view the complete field reference for the policy YAML, refer to the Policy Schema Reference","format":"text","content_length":3421,"word_count":502,"summary":"AI agents typically need credentials to access external services: an API key for the AI model provider, a token for GitHub or GitLab, and so on. OpenShell manages these credentials as first-class entities called providers.","headings":[{"text":"Providers","level":1,"id":"providers"},{"text":"Create a Provider","level":2,"id":"create-a-provider"},{"text":"From Local Credentials","level":3,"id":"from-local-credentials"},{"text":"With Explicit Credentials","level":3,"id":"with-explicit-credentials"},{"text":"Bare Key Form","level":3,"id":"bare-key-form"},{"text":"Manage Providers","level":2,"id":"manage-providers"},{"text":"Attach Providers to Sandboxes","level":2,"id":"attach-providers-to-sandboxes"},{"text":"Auto-Discovery Shortcut","level":3,"id":"auto-discovery-shortcut"},{"text":"Supported Provider Types","level":2,"id":"supported-provider-types"},{"text":"Next Steps","level":2,"id":"next-steps"}],"headings_text":"Providers Create a Provider From Local Credentials With Explicit Credentials Bare Key Form Manage Providers Attach Providers to Sandboxes Auto-Discovery Shortcut Supported Provider Types Next Steps","keywords":["anthropic","any","attach","auto","bare","catalog","claude","code","codex","create","credentials","delete","directly","discovery","each","environment","explicit","explore","form","from","github","gitlab","injected","inspect","key","list","local","manage","microsoft","name","next","none","openai","openshell","outlook","pass","policy","provider","providers","reference","sandbox","sandboxes","schema","separately","services","shortcut","steps","supply","supported","this"],"code_blocks":[{"content":"$ openshell provider create --name my-claude --type claude --from-existing","language":"text"},{"content":"$ openshell provider create --name my-api --type generic --credential API_KEY=sk-abc123","language":"text"},{"content":"$ openshell provider create --name my-api --type generic --credential API_KEY","language":"text"},{"content":"$ openshell provider list","language":"text"},{"content":"$ openshell provider get my-claude","language":"text"},{"content":"$ openshell provider update my-claude --type claude --from-existing","language":"text"},{"content":"$ openshell provider delete my-claude","language":"text"},{"content":"$ openshell sandbox create --provider my-claude --provider my-github -- claude","language":"text"},{"content":"$ openshell sandbox create -- claude","language":"text"}],"links":[],"images":[],"doc_type":"tutorial","section_path":["Sandboxes","Providers"]},{"id":"tutorials/github-sandbox","title":"Set Up a Sandbox of Claude Code with a Custom GitHub Policy","url":"tutorials/github-sandbox.html","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.1.0"},"product":{"name":"OpenShell","version":"0.1.0"},"description":"Learn the iterative policy workflow by launching a sandbox, diagnosing a GitHub access denial, and applying a custom policy to fix it.","tags":["Tutorial","GitHub","Sandbox","Policy","Claude Code"],"topics":["Generative AI","Cybersecurity"],"content_type":"tutorial","learning_level":"technical_intermediate","audience":["engineer"],"content":"Set Up a Sandbox of Claude Code with a Custom GitHub Policy 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\nYou 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. After completing this tutorial, you will 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. Prerequisites This tutorial requires the following: A working OpenShell installation. Complete the Quickstart before proceeding. A GitHub personal access token (PAT) with repo scope. Generate one from the GitHub personal access token settings page by selecting Generate new token (classic) and enabling the repo scope. An Anthropic account 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 with a README if needed. This tutorial uses two terminals to demonstrate the iterative policy workflow: 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 . Each section below indicates which terminal to use. Set Up a Sandbox with Your GitHub Token Depending on whether you start a new sandbox or use an existing sandbox, choose the appropriate tab and follow the instructions. Starting a new sandbox In terminal 2, create a new sandbox with Claude Code. The default policy is applied automatically, which allows read-only access to GitHub. Create a credential provider 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: $ GITHUB_TOKEN=<your-token\nopenshell provider create --name my-github --type github --from-existing\nopenshell sandbox create --provider my-github --keep -- claude\nThe --keep flag keeps the sandbox running after Claude Code exits, so you can apply policy updates later without recreating the environment. 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. Using an existing sandbox In terminal 1, connect to a sandbox that is already running and set your GitHub token as an environment variable: $ openshell sandbox connect <sandbox-name\nexport GITHUB_TOKEN=<your-token\nTo find the name of running sandboxes, run openshell sandbox list in terminal 2. Push Code to GitHub In terminal 1, ask Claude Code to write a simple script and push it to your repository. Replace <org> with your GitHub organization or username and <repo> with your repository name. Prompt Write a hello_world.py script and push it to https://github.com/<org>/<repo> . 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 In this section, you diagnose the denial from your machine and from inside the sandbox. View the Logs from Your Machine In terminal 2, launch the OpenShell terminal: $ openshell term\nThe 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: l7_action: PUT\nl7_target: /repos/<org>/<repo>/contents/hello_world.py\nl7_decision: deny\ndst_host: api.github.com\ndst_port: 443\nl7_protocol: rest\npolicy: github_rest_api\nl7_deny_reason: PUT /repos/<org>/<repo>/contents/hello_world.py not permitted by policy\nThe 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. Ask Claude Code to Check the Sandbox Logs In terminal 1, ask Claude Code to check the sandbox logs for denied requests: Prompt Check the sandbox logs for any denied network requests. What is blocking the push? 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: Response The sandbox runs a proxy that enforces policies on outbound traffic\nThe github_rest_api policy allows GET requests (used to read the file\nbut blocks PUT/write requests to GitHub. This is a sandbox-level restriction\nnot a token issue. No matter what token you provide, pushes through the API\nwill be blocked until the policy is updated. 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. Update the Policy from Your Machine 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. Prompt Based on the following deny reasons, recommend a sandbox policy update that allows GitHub pushes to https://github.com/<org>/<repo> , and save to /tmp/sandbox-policy-update.yaml : The filesystem_policy , landlock , and process 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, but only the network_policies section takes effect when you apply this to a running sandbox. The following steps outline the expected process done by the agent: Inspects the deny reasons. Writes an updated policy that adds github_git and github_api blocks that grant write access to your repository. Saves the policy to /tmp/sandbox-policy-update.yaml . 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. Full reference policy The following YAML shows a complete policy that extends the default policy with GitHub access for a single repository. Replace <org> with your GitHub organization or username and <repo> with your repository name. The filesystem_policy , landlock , and process 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, but only the network_policies section takes effect when you apply this to a running sandbox. version: 1\n── Static (locked at sandbox creation)\nfilesystem_policy\ninclude_workdir: true\nread_only\n/usr\n/lib\n/proc\n/dev/urandom\n/app\n/etc\n/var/log\nread_write\n/sandbox\n/tmp\n/dev/null\nlandlock\ncompatibility: best_effort\nprocess\nrun_as_user: sandbox\nrun_as_group: sandbox\n── Dynamic (hot-reloadable)\nnetwork_policies\nClaude Code ↔ Anthropic API\nclaude_code\nname: claude-code\nendpoints\n{ host: api.anthropic.com, port: 443, protocol: rest, enforcement: enforce, access: full, tls: terminate\n{ host: statsig.anthropic.com, port: 443\n{ host: sentry.io, port: 443\n{ host: raw.githubusercontent.com, port: 443\n{ host: platform.claude.com, port: 443\nbinaries\n{ path: /usr/local/bin/claude\n{ path: /usr/bin/node\nNVIDIA inference endpoint\nnvidia_inference\nname: nvidia-inference\nendpoints\n{ host: integrate.api.nvidia.com, port: 443\nbinaries\n{ path: /usr/bin/curl\n{ path: /bin/bash\n{ path: /usr/local/bin/opencode\n── GitHub: git operations (clone, fetch, push)\ngithub_git\nname: github-git\nendpoints\nhost: github.com\nport: 443\nprotocol: rest\ntls: terminate\nenforcement: enforce\nrules\nallow\nmethod: GET\npath: \"/<org>/<repo>.git/info/refs\nallow\nmethod: POST\npath: \"/<org>/<repo>.git/git-upload-pack\nallow\nmethod: POST\npath: \"/<org>/<repo>.git/git-receive-pack\nbinaries\n{ path: /usr/bin/git\n── GitHub: REST API\ngithub_api\nname: github-api\nendpoints\nhost: api.github.com\nport: 443\nprotocol: rest\ntls: terminate\nenforcement: enforce\nrules\nGraphQL API (used by gh CLI\nallow\nmethod: POST\npath: \"/graphql\nFull read-write access to the repository\nallow\nmethod:\npath: \"/repos/<org>/<repo\nbinaries\n{ path: /usr/local/bin/claude\n{ path: /usr/local/bin/opencode\n{ path: /usr/bin/gh\n{ path: /usr/bin/curl\n── Package managers\npypi\nname: pypi\nendpoints\n{ host: pypi.org, port: 443\n{ host: files.pythonhosted.org, port: 443\n{ host: github.com, port: 443\n{ host: objects.githubusercontent.com, port: 443\n{ host: api.github.com, port: 443\n{ host: downloads.python.org, port: 443\nbinaries\n{ path: /sandbox/.venv/bin/python\n{ path: /sandbox/.venv/bin/python3\n{ path: /sandbox/.venv/bin/pip\n{ path: /app/.venv/bin/python\n{ path: /app/.venv/bin/python3\n{ path: /app/.venv/bin/pip\n{ path: /usr/local/bin/uv\n{ path: \"/sandbox/.uv/python/**\"\n── VS Code Remote\nvscode\nname: vscode\nendpoints\n{ host: update.code.visualstudio.com, port: 443\n{ host: \"*.vo.msecnd.net\", port: 443\n{ host: vscode.download.prss.microsoft.com, port: 443\n{ host: marketplace.visualstudio.com, port: 443\n{ host: \"*.gallerycdn.vsassets.io\", port: 443\nbinaries\n{ path: /usr/bin/curl\n{ path: /usr/bin/wget\n{ path: \"/sandbox/.vscode-server/**\"\n{ path: \"/sandbox/.vscode-remote-containers/**\" } The following table summarizes the two GitHub-specific blocks: Block Endpoint Behavior github_git github.com:443 Git Smart HTTP protocol with TLS termination. 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 with TLS termination. Permits all HTTP methods for the specified repository and GraphQL queries. Denies API access to unlisted repositories. The remaining blocks ( claude_code , nvidia_inference , pypi , vscode ) are identical to the 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 Network Access Rules . Apply the Policy After you have reviewed the generated policy, apply it to the running sandbox: $ openshell policy set <sandbox-name> --policy /tmp/sandbox-policy-update.yaml --wait\nNetwork 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. Retry the Push In terminal 1, ask Claude Code to retry the push: The sandbox policy has been updated. Try pushing to the repository again\nThe 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. Clean Up When you are finished, delete the sandbox to free cluster resources: $ openshell sandbox delete <sandbox-name\nNext 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 . To learn the full policy iteration workflow (pull, edit, push, verify), refer to /sandboxes/policies . To inject credentials automatically instead of pasting tokens, refer to /sandboxes/providers","format":"text","content_length":12934,"word_count":1889,"summary":"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...","headings":[{"text":"Set Up a Sandbox of Claude Code with a Custom GitHub Policy","level":1,"id":"set-up-a-sandbox-of-claude-code-with-a-custom-github-policy"},{"text":"Prerequisites","level":2,"id":"prerequisites"},{"text":"Set Up a Sandbox with Your GitHub Token","level":2,"id":"set-up-a-sandbox-with-your-github-token"},{"text":"Push Code to GitHub","level":2,"id":"push-code-to-github"},{"text":"Diagnose the Denial","level":2,"id":"diagnose-the-denial"},{"text":"View the Logs from Your Machine","level":3,"id":"view-the-logs-from-your-machine"},{"text":"Ask Claude Code to Check the Sandbox Logs","level":3,"id":"ask-claude-code-to-check-the-sandbox-logs"},{"text":"Update the Policy from Your Machine","level":2,"id":"update-the-policy-from-your-machine"},{"text":"Review the Generated Policy","level":2,"id":"review-the-generated-policy"},{"text":"Apply the Policy","level":2,"id":"apply-the-policy"},{"text":"Retry the Push","level":2,"id":"retry-the-push"},{"text":"Clean Up","level":2,"id":"clean-up"},{"text":"Next Steps","level":2,"id":"next-steps"}],"headings_text":"Set Up a Sandbox of Claude Code with a Custom GitHub Policy Prerequisites Set Up a Sandbox with Your GitHub Token Push Code to GitHub Diagnose the Denial View the Logs from Your Machine Ask Claude Code to Check the Sandbox Logs Update the Policy from Your Machine Review the Generated Policy Apply the Policy Retry the Push Clean Up Next Steps","keywords":["access","after","agent","anthropic","api","apply","ask","based","behavior","block","blocks","both","check","claude","clean","code","com","compatibility","complete","confirm","copy","create","cursor","custom","denial","denies","depending","depth","detail","diagnose","dst_host","dst_port","dynamic","each","endpoint","enforcement","experience","following","from","full","generate","generated","git","github","graphql","have","host","https","include_workdir","inspects"],"code_blocks":[{"content":"$ GITHUB_TOKEN=<your-token>\n$ openshell provider create --name my-github --type github --from-existing\n$ openshell sandbox create --provider my-github --keep -- claude","language":"text"},{"content":"$ openshell sandbox connect <sandbox-name>\n$ export GITHUB_TOKEN=<your-token>","language":"text"},{"content":"$ openshell term","language":"text"},{"content":"l7_action:      PUT\nl7_target:      /repos/<org>/<repo>/contents/hello_world.py\nl7_decision:    deny\ndst_host:       api.github.com\ndst_port:       443\nl7_protocol:    rest\npolicy:         github_rest_api\nl7_deny_reason: PUT /repos/<org>/<repo>/contents/hello_world.py not permitted by policy","language":"text"},{"content":"version: 1\n\n# ── Static (locked at sandbox creation) ──────────────────────────\n\nfilesystem_policy:\n  include_workdir: true\n  read_only:\n    - /usr\n    - /lib\n    - /proc\n    - /dev/urandom\n    - /app\n    - /etc\n    - /var/log\n  read_write:\n    - /sandbox\n    - /tmp\n    - /dev/null\n\nlandlock:\n  compatibility: best_effort\n\nprocess:\n  run_as_user: sandbox\n  run_as_group: sandbox\n\n# ── Dynamic (hot-reloadable) ─────────────────────────────────────\n\nnetwork_policies:\n\n  # Claude Code ↔ Anthropic API\n  claude_code:\n    name: claude-code\n    endpoints:\n      - { host: api.anthropic.com, port: 443, protocol: rest, enforcement: enforce, access: full, tls: terminate }\n      - { host: statsig.anthropic.com, port: 443 }\n      - { host: sentry.io, port: 443 }\n      - { host: raw.githubusercontent.com, port: 443 }\n      - { host: platform.claude.com, port: 443 }\n    binaries:\n      - { path: /usr/local/bin/claude }\n      - { path: /usr/bin/node }\n\n  # NVIDIA inference endpoint\n  nvidia_inference:\n    name: nvidia-inference\n    endpoints:\n      - { host: integrate.api.nvidia.com, port: 443 }\n    binaries:\n      - { path: /usr/bin/curl }\n      - { path: /bin/bash }\n      - { path: /usr/local/bin/opencode }\n\n  # ── GitHub: git operations (clone, fetch, push) ──────────────\n\n  github_git:\n    name: github-git\n    endpoints:\n      - host: github.com\n        port: 443\n        protocol: rest\n        tls: terminate\n        enforcement: enforce\n        rules:\n          - allow:\n              method: GET\n              path: \"/<org>/<repo>.git/info/refs*\"\n          - allow:\n              method: POST\n              path: \"/<org>/<repo>.git/git-upload-pack\"\n          - allow:\n              method: POST\n              path: \"/<org>/<repo>.git/git-receive-pack\"\n    binaries:\n      - { path: /usr/bin/git }\n\n  # ── GitHub: REST API ─────────────────────────────────────────\n\n  github_api:\n    name: github-api\n    endpoints:\n      - host: api.github.com\n        port: 443\n        protocol: rest\n        tls: terminate\n        enforcement: enforce\n        rules:\n          # GraphQL API (used by gh CLI)\n          - allow:\n              method: POST\n              path: \"/graphql\"\n          # Full read-write access to the repository\n          - allow:\n              method: \"*\"\n              path: \"/repos/<org>/<repo>/**\"\n    binaries:\n      - { path: /usr/local/bin/claude }\n      - { path: /usr/local/bin/opencode }\n      - { path: /usr/bin/gh }\n      - { path: /usr/bin/curl }\n\n  # ── Package managers ─────────────────────────────────────────\n\n  pypi:\n    name: pypi\n    endpoints:\n      - { host: pypi.org, port: 443 }\n      - { host: files.pythonhosted.org, port: 443 }\n      - { host: github.com, port: 443 }\n      - { host: objects.githubusercontent.com, port: 443 }\n      - { host: api.github.com, port: 443 }\n      - { host: downloads.python.org, port: 443 }\n    binaries:\n      - { path: /sandbox/.venv/bin/python }\n      - { path: /sandbox/.venv/bin/python3 }\n      - { path: /sandbox/.venv/bin/pip }\n      - { path: /app/.venv/bin/python }\n      - { path: /app/.venv/bin/python3 }\n      - { path: /app/.venv/bin/pip }\n      - { path: /usr/local/bin/uv }\n      - { path: \"/sandbox/.uv/python/**\" }\n\n  # ── VS Code Remote ──────────────────────────────────────────\n\n  vscode:\n    name: vscode\n    endpoints:\n      - { host: update.code.visualstudio.com, port: 443 }\n      - { host: \"*.vo.msecnd.net\", port: 443 }\n      - { host: vscode.download.prss.microsoft.com, port: 443 }\n      - { host: marketplace.visualstudio.com, port: 443 }\n      - { host: \"*.gallerycdn.vsassets.io\", port: 443 }\n    binaries:\n      - { path: /usr/bin/curl }\n      - { path: /usr/bin/wget }\n      - { path: \"/sandbox/.vscode-server/**\" }\n      - { path: \"/sandbox/.vscode-remote-containers/**\" }","language":"text"},{"content":"$ openshell policy set <sandbox-name> --policy /tmp/sandbox-policy-update.yaml --wait","language":"text"},{"content":"The sandbox policy has been updated. Try pushing to the repository again.","language":"text"},{"content":"$ openshell sandbox delete <sandbox-name>","language":"text"}],"links":[{"text":"GitHub personal access token settings page","type":"external","url":"https://github.com/settings/tokens"},{"text":"Anthropic account","type":"external","url":"https://console.anthropic.com/"},{"text":"create one","type":"external","url":"https://github.com/new"}],"images":[],"doc_type":"tutorial","section_path":["Tutorials","Github Sandbox"]}]
\ No newline at end of file
diff --git a/pr-preview/pr-257/inference/configure.html b/pr-preview/pr-257/inference/configure.html
index 14ebea86f..94234cfb5 100644
--- a/pr-preview/pr-257/inference/configure.html
+++ b/pr-preview/pr-257/inference/configure.html
@@ -387,7 +387,7 @@
 <p aria-level="2" class="caption" role="heading"><span class="caption-text">Get Started</span></p>
 <ul class="nav bd-sidenav">
 <li class="toctree-l1"><a class="reference internal" href="../get-started/quickstart.html">Quickstart</a></li>
-<li class="toctree-l1"><a class="reference internal" href="../tutorials/github-sandbox.html">Tutorial: GitHub Policy Iteration</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../tutorials/github-sandbox.html">GitHub Policy Tutorial</a></li>
 </ul>
 <p aria-level="2" class="caption" role="heading"><span class="caption-text">Sandboxes</span></p>
 <ul class="nav bd-sidenav">
diff --git a/pr-preview/pr-257/inference/configure.json b/pr-preview/pr-257/inference/configure.json
index 4a69d9e2a..24e461ba6 100644
--- a/pr-preview/pr-257/inference/configure.json
+++ b/pr-preview/pr-257/inference/configure.json
@@ -1 +1 @@
-{"id":"inference/configure","title":"Configure Inference Routing","url":"inference/configure.html","last_modified":"2026-03-12T09:12:26.623340+00:00","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.1.0"},"product":{"name":"OpenShell","version":"0.1.0"},"description":"Set up the managed local inference endpoint with provider credentials and model configuration.","tags":["Inference Routing","Configuration","Privacy","LLM","Provider"],"topics":["Generative AI","Cybersecurity"],"content_type":"how_to","learning_level":"technical_intermediate","audience":["engineer"],"content":"Configure Inference Routing This page covers the managed local inference endpoint ( https://inference.local ). External inference endpoints go through sandbox network_policies — refer to Network Access Rules for details. The configuration consists of two values: Value Description Provider record The credential backend OpenShell uses to authenticate with the upstream model host. Model ID The model to use for generation requests. Step 1: Create a Provider Create a provider that holds the backend credentials you want OpenShell to use. NVIDIA API Catalog $ openshell provider create --name nvidia-prod --type nvidia --from-existing\nThis reads NVIDIA_API_KEY from your environment. Local / self-hosted endpoint $ openshell provider create\nname my-local-model\ntype openai\ncredential OPENAI_API_KEY=empty-if-not-required\nconfig OPENAI_BASE_URL=http://192.168.10.15/v1\nUse --config OPENAI_BASE_URL to point to any OpenAI-compatible server running on your network. Set OPENAI_API_KEY to a dummy value if the server does not require authentication. Anthropic $ openshell provider create --name anthropic-prod --type anthropic --from-existing\nThis reads ANTHROPIC_API_KEY from your environment. Step 2: Set Inference Routing Point inference.local at that provider and choose the model to use: $ openshell inference set\nprovider nvidia-prod\nmodel nvidia/nemotron-3-nano-30b-a3b\nStep 3: Verify the Active Config Confirm that the provider and model are set correctly: $ openshell inference get\nGateway inference\nProvider: nvidia-prod\nModel: nvidia/nemotron-3-nano-30b-a3b\nVersion: 1\nStep 4: Update Part of the Config Use update when you want to change only one field: $ openshell inference update --model nvidia/nemotron-3-nano-30b-a3b\nOr switch providers without repeating the current model: $ openshell inference update --provider openai-prod\nUse It from a Sandbox After inference is configured, code inside any sandbox can call https://inference.local directly: from openai import OpenAI\nclient = OpenAI(base_url=\"https://inference.local/v1\", api_key=\"dummy\nresponse = client.chat.completions.create\nmodel=\"anything\nmessages=[{\"role\": \"user\", \"content\": \"Hello\nThe client-supplied model is ignored for generation requests. OpenShell rewrites it to the configured model before forwarding upstream. Use this endpoint when inference should stay local to the host for privacy and security reasons. External providers that should be reached directly belong in network_policies instead. Verify the Endpoint from a Sandbox openshell inference get confirms the configuration was saved, but does not verify the upstream endpoint is reachable. To confirm end-to-end connectivity, connect to a sandbox and run: curl https://inference.local/v1/responses\nH \"Content-Type: application/json\"\nd\ninstructions\": \"You are a helpful assistant\ninput\": \"Hello\nA successful response confirms the privacy router can reach the configured backend and the model is serving requests. Gateway-scoped — every sandbox on the active gateway sees the same inference.local backend. HTTPS only — inference.local is intercepted only for HTTPS traffic. Next Steps Explore related topics: To understand the inference routing flow and supported API patterns, refer to index . To control external endpoints, refer to Network Access Rules . To manage provider records, refer to ../sandboxes/providers . To view openshell inference commands, refer to ../reference/cli","format":"text","summary":"This page covers the managed local inference endpoint (https://inference.local). External inference endpoints go through sandbox network_policies — refer to Network Access Rules for details.","headings":[{"text":"Configure Inference Routing","level":1},{"text":"Step 1: Create a Provider","level":2},{"text":"Step 2: Set Inference Routing","level":2},{"text":"Step 3: Verify the Active Config","level":2},{"text":"Step 4: Update Part of the Config","level":2},{"text":"Use It from a Sandbox","level":2},{"text":"Verify the Endpoint from a Sandbox","level":3},{"text":"Next Steps","level":2}]}
\ No newline at end of file
+{"id":"inference/configure","title":"Configure Inference Routing","url":"inference/configure.html","last_modified":"2026-03-12T23:38:42.358178+00:00","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.1.0"},"product":{"name":"OpenShell","version":"0.1.0"},"description":"Set up the managed local inference endpoint with provider credentials and model configuration.","tags":["Inference Routing","Configuration","Privacy","LLM","Provider"],"topics":["Generative AI","Cybersecurity"],"content_type":"how_to","learning_level":"technical_intermediate","audience":["engineer"],"content":"Configure Inference Routing This page covers the managed local inference endpoint ( https://inference.local ). External inference endpoints go through sandbox network_policies — refer to Network Access Rules for details. The configuration consists of two values: Value Description Provider record The credential backend OpenShell uses to authenticate with the upstream model host. Model ID The model to use for generation requests. Step 1: Create a Provider Create a provider that holds the backend credentials you want OpenShell to use. NVIDIA API Catalog $ openshell provider create --name nvidia-prod --type nvidia --from-existing\nThis reads NVIDIA_API_KEY from your environment. Local / self-hosted endpoint $ openshell provider create\nname my-local-model\ntype openai\ncredential OPENAI_API_KEY=empty-if-not-required\nconfig OPENAI_BASE_URL=http://192.168.10.15/v1\nUse --config OPENAI_BASE_URL to point to any OpenAI-compatible server running on your network. Set OPENAI_API_KEY to a dummy value if the server does not require authentication. Anthropic $ openshell provider create --name anthropic-prod --type anthropic --from-existing\nThis reads ANTHROPIC_API_KEY from your environment. Step 2: Set Inference Routing Point inference.local at that provider and choose the model to use: $ openshell inference set\nprovider nvidia-prod\nmodel nvidia/nemotron-3-nano-30b-a3b\nStep 3: Verify the Active Config Confirm that the provider and model are set correctly: $ openshell inference get\nGateway inference\nProvider: nvidia-prod\nModel: nvidia/nemotron-3-nano-30b-a3b\nVersion: 1\nStep 4: Update Part of the Config Use update when you want to change only one field: $ openshell inference update --model nvidia/nemotron-3-nano-30b-a3b\nOr switch providers without repeating the current model: $ openshell inference update --provider openai-prod\nUse It from a Sandbox After inference is configured, code inside any sandbox can call https://inference.local directly: from openai import OpenAI\nclient = OpenAI(base_url=\"https://inference.local/v1\", api_key=\"dummy\nresponse = client.chat.completions.create\nmodel=\"anything\nmessages=[{\"role\": \"user\", \"content\": \"Hello\nThe client-supplied model is ignored for generation requests. OpenShell rewrites it to the configured model before forwarding upstream. Use this endpoint when inference should stay local to the host for privacy and security reasons. External providers that should be reached directly belong in network_policies instead. Verify the Endpoint from a Sandbox openshell inference get confirms the configuration was saved, but does not verify the upstream endpoint is reachable. To confirm end-to-end connectivity, connect to a sandbox and run: curl https://inference.local/v1/responses\nH \"Content-Type: application/json\"\nd\ninstructions\": \"You are a helpful assistant\ninput\": \"Hello\nA successful response confirms the privacy router can reach the configured backend and the model is serving requests. Gateway-scoped — every sandbox on the active gateway sees the same inference.local backend. HTTPS only — inference.local is intercepted only for HTTPS traffic. Next Steps Explore related topics: To understand the inference routing flow and supported API patterns, refer to index . To control external endpoints, refer to Network Access Rules . To manage provider records, refer to ../sandboxes/providers . To view openshell inference commands, refer to ../reference/cli","format":"text","summary":"This page covers the managed local inference endpoint (https://inference.local). External inference endpoints go through sandbox network_policies — refer to Network Access Rules for details.","headings":[{"text":"Configure Inference Routing","level":1},{"text":"Step 1: Create a Provider","level":2},{"text":"Step 2: Set Inference Routing","level":2},{"text":"Step 3: Verify the Active Config","level":2},{"text":"Step 4: Update Part of the Config","level":2},{"text":"Use It from a Sandbox","level":2},{"text":"Verify the Endpoint from a Sandbox","level":3},{"text":"Next Steps","level":2}]}
\ No newline at end of file
diff --git a/pr-preview/pr-257/inference/index.html b/pr-preview/pr-257/inference/index.html
index e4777bf06..cd0555b67 100644
--- a/pr-preview/pr-257/inference/index.html
+++ b/pr-preview/pr-257/inference/index.html
@@ -387,7 +387,7 @@
 <p aria-level="2" class="caption" role="heading"><span class="caption-text">Get Started</span></p>
 <ul class="nav bd-sidenav">
 <li class="toctree-l1"><a class="reference internal" href="../get-started/quickstart.html">Quickstart</a></li>
-<li class="toctree-l1"><a class="reference internal" href="../tutorials/github-sandbox.html">Tutorial: GitHub Policy Iteration</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../tutorials/github-sandbox.html">GitHub Policy Tutorial</a></li>
 </ul>
 <p aria-level="2" class="caption" role="heading"><span class="caption-text">Sandboxes</span></p>
 <ul class="nav bd-sidenav">
diff --git a/pr-preview/pr-257/inference/index.json b/pr-preview/pr-257/inference/index.json
index bf32fda5e..5b896d294 100644
--- a/pr-preview/pr-257/inference/index.json
+++ b/pr-preview/pr-257/inference/index.json
@@ -1 +1 @@
-{"id":"inference/index","title":"About Inference Routing","url":"inference/index.html","last_modified":"2026-03-12T09:12:26.576260+00:00","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.1.0"},"product":{"name":"OpenShell","version":"0.1.0"},"description":"Understand how OpenShell routes inference traffic through external endpoints and the local privacy router.","tags":["Inference Routing","Privacy","AI Agents","LLM"],"topics":["Generative AI","Cybersecurity"],"content_type":"concept","learning_level":"technical_beginner","audience":["engineer","data_scientist"],"content":"About Inference Routing 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 . Refer to 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 privacy router strips the original credentials, injects the configured backend credentials, and forwards to the managed model endpoint. How inference.local Works When code inside a sandbox calls https://inference.local , the privacy router routes the request to the configured backend for that gateway. The configured model is applied to generation requests, and provider credentials are supplied by OpenShell rather than by code inside the sandbox. If code calls an external inference host directly, that traffic is evaluated only by network_policies . Property Detail Credentials No sandbox API keys needed — credentials come from the configured provider record. Configuration One provider and one model define sandbox inference. Provider support OpenAI, Anthropic, and NVIDIA providers all work through the same endpoint. Hot-refresh Provider credential changes and inference updates are picked up without recreating sandboxes. Supported API Patterns Supported request patterns depend on the provider configured for inference.local . OpenAI-compatible Pattern Method Path Chat Completions POST /v1/chat/completions Completions POST /v1/completions Responses POST /v1/responses Model Discovery GET /v1/models Model Discovery GET /v1/models/* Anthropic-compatible Pattern Method Path Messages POST /v1/messages Requests to inference.local that do not match the configured provider’s supported patterns are denied. Next Steps Continue with one of the following: To set up the backend behind inference.local , refer to configure . To control external endpoints, refer to Network Access Rules","format":"text","summary":"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.","headings":[{"text":"About Inference Routing","level":1},{"text":"How inference.local Works","level":2},{"text":"Supported API Patterns","level":2},{"text":"Next Steps","level":2}],"children":[{"id":"inference/configure","title":"Configure Inference Routing","url":"inference/configure.html","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.1.0"},"product":{"name":"OpenShell","version":"0.1.0"},"description":"Set up the managed local inference endpoint with provider credentials and model configuration.","tags":["Inference Routing","Configuration","Privacy","LLM","Provider"],"topics":["Generative AI","Cybersecurity"],"content_type":"how_to","learning_level":"technical_intermediate","audience":["engineer"],"content":"Configure Inference Routing This page covers the managed local inference endpoint ( https://inference.local ). External inference endpoints go through sandbox network_policies — refer to Network Access Rules for details. The configuration consists of two values: Value Description Provider record The credential backend OpenShell uses to authenticate with the upstream model host. Model ID The model to use for generation requests. Step 1: Create a Provider Create a provider that holds the backend credentials you want OpenShell to use. NVIDIA API Catalog $ openshell provider create --name nvidia-prod --type nvidia --from-existing\nThis reads NVIDIA_API_KEY from your environment. Local / self-hosted endpoint $ openshell provider create\nname my-local-model\ntype openai\ncredential OPENAI_API_KEY=empty-if-not-required\nconfig OPENAI_BASE_URL=http://192.168.10.15/v1\nUse --config OPENAI_BASE_URL to point to any OpenAI-compatible server running on your network. Set OPENAI_API_KEY to a dummy value if the server does not require authentication. Anthropic $ openshell provider create --name anthropic-prod --type anthropic --from-existing\nThis reads ANTHROPIC_API_KEY from your environment. Step 2: Set Inference Routing Point inference.local at that provider and choose the model to use: $ openshell inference set\nprovider nvidia-prod\nmodel nvidia/nemotron-3-nano-30b-a3b\nStep 3: Verify the Active Config Confirm that the provider and model are set correctly: $ openshell inference get\nGateway inference\nProvider: nvidia-prod\nModel: nvidia/nemotron-3-nano-30b-a3b\nVersion: 1\nStep 4: Update Part of the Config Use update when you want to change only one field: $ openshell inference update --model nvidia/nemotron-3-nano-30b-a3b\nOr switch providers without repeating the current model: $ openshell inference update --provider openai-prod\nUse It from a Sandbox After inference is configured, code inside any sandbox can call https://inference.local directly: from openai import OpenAI\nclient = OpenAI(base_url=\"https://inference.local/v1\", api_key=\"dummy\nresponse = client.chat.completions.create\nmodel=\"anything\nmessages=[{\"role\": \"user\", \"content\": \"Hello\nThe client-supplied model is ignored for generation requests. OpenShell rewrites it to the configured model before forwarding upstream. Use this endpoint when inference should stay local to the host for privacy and security reasons. External providers that should be reached directly belong in network_policies instead. Verify the Endpoint from a Sandbox openshell inference get confirms the configuration was saved, but does not verify the upstream endpoint is reachable. To confirm end-to-end connectivity, connect to a sandbox and run: curl https://inference.local/v1/responses\nH \"Content-Type: application/json\"\nd\ninstructions\": \"You are a helpful assistant\ninput\": \"Hello\nA successful response confirms the privacy router can reach the configured backend and the model is serving requests. Gateway-scoped — every sandbox on the active gateway sees the same inference.local backend. HTTPS only — inference.local is intercepted only for HTTPS traffic. Next Steps Explore related topics: To understand the inference routing flow and supported API patterns, refer to index . To control external endpoints, refer to Network Access Rules . To manage provider records, refer to ../sandboxes/providers . To view openshell inference commands, refer to ../reference/cli","format":"text","content_length":3420,"word_count":453,"summary":"This page covers the managed local inference endpoint (https://inference.local). External inference endpoints go through sandbox network_policies — refer to Network Access Rules for details.","headings":[{"text":"Configure Inference Routing","level":1,"id":"configure-inference-routing"},{"text":"Step 1: Create a Provider","level":2,"id":"step-1-create-a-provider"},{"text":"Step 2: Set Inference Routing","level":2,"id":"step-2-set-inference-routing"},{"text":"Step 3: Verify the Active Config","level":2,"id":"step-3-verify-the-active-config"},{"text":"Step 4: Update Part of the Config","level":2,"id":"step-4-update-part-of-the-config"},{"text":"Use It from a Sandbox","level":2,"id":"use-it-from-a-sandbox"},{"text":"Verify the Endpoint from a Sandbox","level":3,"id":"verify-the-endpoint-from-a-sandbox"},{"text":"Next Steps","level":2,"id":"next-steps"}],"headings_text":"Configure Inference Routing Step 1: Create a Provider Step 2: Set Inference Routing Step 3: Verify the Active Config Step 4: Update Part of the Config Use It from a Sandbox Verify the Endpoint from a Sandbox Next Steps","keywords":["access","active","after","anthropic","api_key","base_url","catalog","chat","client","config","configure","confirm","content","correctly","create","description","directly","endpoint","explore","external","field","from","gateway","hello","http","https","inference","local","messages","model","network","next","openai","openshell","part","point","provider","response","routing","rules","run","sandbox","set","step","steps","this","topics","type","update","user"],"code_blocks":[{"content":"$ openshell provider create --name nvidia-prod --type nvidia --from-existing","language":"text"},{"content":"$ openshell provider create \\\n    --name my-local-model \\\n    --type openai \\\n    --credential OPENAI_API_KEY=empty-if-not-required \\\n    --config OPENAI_BASE_URL=http://192.168.10.15/v1","language":"text"},{"content":"$ openshell provider create --name anthropic-prod --type anthropic --from-existing","language":"text"},{"content":"$ openshell inference set \\\n    --provider nvidia-prod \\\n    --model nvidia/nemotron-3-nano-30b-a3b","language":"text"},{"content":"$ openshell inference get\nGateway inference:\n\n  Provider: nvidia-prod\n  Model: nvidia/nemotron-3-nano-30b-a3b\n  Version: 1","language":"text"},{"content":"$ openshell inference update --model nvidia/nemotron-3-nano-30b-a3b","language":"text"},{"content":"$ openshell inference update --provider openai-prod","language":"text"},{"content":"from openai import OpenAI\n\nclient = OpenAI(base_url=\"https://inference.local/v1\", api_key=\"dummy\")\n\nresponse = client.chat.completions.create(\n    model=\"anything\",\n    messages=[{\"role\": \"user\", \"content\": \"Hello\"}],\n)","language":"text"},{"content":"curl https://inference.local/v1/responses \\\n    -H \"Content-Type: application/json\" \\\n    -d '{\n      \"instructions\": \"You are a helpful assistant.\",\n      \"input\": \"Hello!\"\n    }'","language":"text"}],"links":[],"images":[],"doc_type":"tutorial","section_path":["Inference","Configure"]}]}
\ No newline at end of file
+{"id":"inference/index","title":"About Inference Routing","url":"inference/index.html","last_modified":"2026-03-12T23:38:42.342525+00:00","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.1.0"},"product":{"name":"OpenShell","version":"0.1.0"},"description":"Understand how OpenShell routes inference traffic through external endpoints and the local privacy router.","tags":["Inference Routing","Privacy","AI Agents","LLM"],"topics":["Generative AI","Cybersecurity"],"content_type":"concept","learning_level":"technical_beginner","audience":["engineer","data_scientist"],"content":"About Inference Routing 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 . Refer to 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 privacy router strips the original credentials, injects the configured backend credentials, and forwards to the managed model endpoint. How inference.local Works When code inside a sandbox calls https://inference.local , the privacy router routes the request to the configured backend for that gateway. The configured model is applied to generation requests, and provider credentials are supplied by OpenShell rather than by code inside the sandbox. If code calls an external inference host directly, that traffic is evaluated only by network_policies . Property Detail Credentials No sandbox API keys needed — credentials come from the configured provider record. Configuration One provider and one model define sandbox inference. Provider support OpenAI, Anthropic, and NVIDIA providers all work through the same endpoint. Hot-refresh Provider credential changes and inference updates are picked up without recreating sandboxes. Supported API Patterns Supported request patterns depend on the provider configured for inference.local . OpenAI-compatible Pattern Method Path Chat Completions POST /v1/chat/completions Completions POST /v1/completions Responses POST /v1/responses Model Discovery GET /v1/models Model Discovery GET /v1/models/* Anthropic-compatible Pattern Method Path Messages POST /v1/messages Requests to inference.local that do not match the configured provider’s supported patterns are denied. Next Steps Continue with one of the following: To set up the backend behind inference.local , refer to configure . To control external endpoints, refer to Network Access Rules","format":"text","summary":"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.","headings":[{"text":"About Inference Routing","level":1},{"text":"How inference.local Works","level":2},{"text":"Supported API Patterns","level":2},{"text":"Next Steps","level":2}],"children":[{"id":"inference/configure","title":"Configure Inference Routing","url":"inference/configure.html","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.1.0"},"product":{"name":"OpenShell","version":"0.1.0"},"description":"Set up the managed local inference endpoint with provider credentials and model configuration.","tags":["Inference Routing","Configuration","Privacy","LLM","Provider"],"topics":["Generative AI","Cybersecurity"],"content_type":"how_to","learning_level":"technical_intermediate","audience":["engineer"],"content":"Configure Inference Routing This page covers the managed local inference endpoint ( https://inference.local ). External inference endpoints go through sandbox network_policies — refer to Network Access Rules for details. The configuration consists of two values: Value Description Provider record The credential backend OpenShell uses to authenticate with the upstream model host. Model ID The model to use for generation requests. Step 1: Create a Provider Create a provider that holds the backend credentials you want OpenShell to use. NVIDIA API Catalog $ openshell provider create --name nvidia-prod --type nvidia --from-existing\nThis reads NVIDIA_API_KEY from your environment. Local / self-hosted endpoint $ openshell provider create\nname my-local-model\ntype openai\ncredential OPENAI_API_KEY=empty-if-not-required\nconfig OPENAI_BASE_URL=http://192.168.10.15/v1\nUse --config OPENAI_BASE_URL to point to any OpenAI-compatible server running on your network. Set OPENAI_API_KEY to a dummy value if the server does not require authentication. Anthropic $ openshell provider create --name anthropic-prod --type anthropic --from-existing\nThis reads ANTHROPIC_API_KEY from your environment. Step 2: Set Inference Routing Point inference.local at that provider and choose the model to use: $ openshell inference set\nprovider nvidia-prod\nmodel nvidia/nemotron-3-nano-30b-a3b\nStep 3: Verify the Active Config Confirm that the provider and model are set correctly: $ openshell inference get\nGateway inference\nProvider: nvidia-prod\nModel: nvidia/nemotron-3-nano-30b-a3b\nVersion: 1\nStep 4: Update Part of the Config Use update when you want to change only one field: $ openshell inference update --model nvidia/nemotron-3-nano-30b-a3b\nOr switch providers without repeating the current model: $ openshell inference update --provider openai-prod\nUse It from a Sandbox After inference is configured, code inside any sandbox can call https://inference.local directly: from openai import OpenAI\nclient = OpenAI(base_url=\"https://inference.local/v1\", api_key=\"dummy\nresponse = client.chat.completions.create\nmodel=\"anything\nmessages=[{\"role\": \"user\", \"content\": \"Hello\nThe client-supplied model is ignored for generation requests. OpenShell rewrites it to the configured model before forwarding upstream. Use this endpoint when inference should stay local to the host for privacy and security reasons. External providers that should be reached directly belong in network_policies instead. Verify the Endpoint from a Sandbox openshell inference get confirms the configuration was saved, but does not verify the upstream endpoint is reachable. To confirm end-to-end connectivity, connect to a sandbox and run: curl https://inference.local/v1/responses\nH \"Content-Type: application/json\"\nd\ninstructions\": \"You are a helpful assistant\ninput\": \"Hello\nA successful response confirms the privacy router can reach the configured backend and the model is serving requests. Gateway-scoped — every sandbox on the active gateway sees the same inference.local backend. HTTPS only — inference.local is intercepted only for HTTPS traffic. Next Steps Explore related topics: To understand the inference routing flow and supported API patterns, refer to index . To control external endpoints, refer to Network Access Rules . To manage provider records, refer to ../sandboxes/providers . To view openshell inference commands, refer to ../reference/cli","format":"text","content_length":3420,"word_count":453,"summary":"This page covers the managed local inference endpoint (https://inference.local). External inference endpoints go through sandbox network_policies — refer to Network Access Rules for details.","headings":[{"text":"Configure Inference Routing","level":1,"id":"configure-inference-routing"},{"text":"Step 1: Create a Provider","level":2,"id":"step-1-create-a-provider"},{"text":"Step 2: Set Inference Routing","level":2,"id":"step-2-set-inference-routing"},{"text":"Step 3: Verify the Active Config","level":2,"id":"step-3-verify-the-active-config"},{"text":"Step 4: Update Part of the Config","level":2,"id":"step-4-update-part-of-the-config"},{"text":"Use It from a Sandbox","level":2,"id":"use-it-from-a-sandbox"},{"text":"Verify the Endpoint from a Sandbox","level":3,"id":"verify-the-endpoint-from-a-sandbox"},{"text":"Next Steps","level":2,"id":"next-steps"}],"headings_text":"Configure Inference Routing Step 1: Create a Provider Step 2: Set Inference Routing Step 3: Verify the Active Config Step 4: Update Part of the Config Use It from a Sandbox Verify the Endpoint from a Sandbox Next Steps","keywords":["access","active","after","anthropic","api_key","base_url","catalog","chat","client","config","configure","confirm","content","correctly","create","description","directly","endpoint","explore","external","field","from","gateway","hello","http","https","inference","local","messages","model","network","next","openai","openshell","part","point","provider","response","routing","rules","run","sandbox","set","step","steps","this","topics","type","update","user"],"code_blocks":[{"content":"$ openshell provider create --name nvidia-prod --type nvidia --from-existing","language":"text"},{"content":"$ openshell provider create \\\n    --name my-local-model \\\n    --type openai \\\n    --credential OPENAI_API_KEY=empty-if-not-required \\\n    --config OPENAI_BASE_URL=http://192.168.10.15/v1","language":"text"},{"content":"$ openshell provider create --name anthropic-prod --type anthropic --from-existing","language":"text"},{"content":"$ openshell inference set \\\n    --provider nvidia-prod \\\n    --model nvidia/nemotron-3-nano-30b-a3b","language":"text"},{"content":"$ openshell inference get\nGateway inference:\n\n  Provider: nvidia-prod\n  Model: nvidia/nemotron-3-nano-30b-a3b\n  Version: 1","language":"text"},{"content":"$ openshell inference update --model nvidia/nemotron-3-nano-30b-a3b","language":"text"},{"content":"$ openshell inference update --provider openai-prod","language":"text"},{"content":"from openai import OpenAI\n\nclient = OpenAI(base_url=\"https://inference.local/v1\", api_key=\"dummy\")\n\nresponse = client.chat.completions.create(\n    model=\"anything\",\n    messages=[{\"role\": \"user\", \"content\": \"Hello\"}],\n)","language":"text"},{"content":"curl https://inference.local/v1/responses \\\n    -H \"Content-Type: application/json\" \\\n    -d '{\n      \"instructions\": \"You are a helpful assistant.\",\n      \"input\": \"Hello!\"\n    }'","language":"text"}],"links":[],"images":[],"doc_type":"tutorial","section_path":["Inference","Configure"]}]}
\ No newline at end of file
diff --git a/pr-preview/pr-257/reference/cli.html b/pr-preview/pr-257/reference/cli.html
index ba58a3bc3..1d2b18187 100644
--- a/pr-preview/pr-257/reference/cli.html
+++ b/pr-preview/pr-257/reference/cli.html
@@ -387,7 +387,7 @@
 <p aria-level="2" class="caption" role="heading"><span class="caption-text">Get Started</span></p>
 <ul class="nav bd-sidenav">
 <li class="toctree-l1"><a class="reference internal" href="../get-started/quickstart.html">Quickstart</a></li>
-<li class="toctree-l1"><a class="reference internal" href="../tutorials/github-sandbox.html">Tutorial: GitHub Policy Iteration</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../tutorials/github-sandbox.html">GitHub Policy Tutorial</a></li>
 </ul>
 <p aria-level="2" class="caption" role="heading"><span class="caption-text">Sandboxes</span></p>
 <ul class="nav bd-sidenav">
diff --git a/pr-preview/pr-257/reference/cli.json b/pr-preview/pr-257/reference/cli.json
index ece78aaec..7171127f4 100644
--- a/pr-preview/pr-257/reference/cli.json
+++ b/pr-preview/pr-257/reference/cli.json
@@ -1 +1 @@
-{"id":"reference/cli","title":"CLI Reference","url":"reference/cli.html","last_modified":"2026-03-12T09:12:26.619662+00:00","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.1.0"},"product":{"name":"OpenShell","version":"0.1.0"},"description":"Complete command reference for the openshell CLI including all subcommands, flags, and environment variables.","tags":["CLI","Reference","Commands","AI Agents"],"topics":["Generative AI","Cybersecurity"],"content_type":"reference","learning_level":"technical_beginner","audience":["engineer","data_scientist"],"content":"CLI Reference Complete command reference for the openshell CLI. Every subcommand, flag, and option is documented here. Command Tree The full hierarchy of openshell subcommands: openshell\nstatus\nlogs [name\nterm\nforward\n├── start <port> <name\n├── stop <port> <name\n└── list\ngateway\n├── start\n├── stop\n├── destroy\n├── info\n├── add <url\n└── select [name\nsandbox\n├── create\n├── get [name\n├── list\n├── delete <name...> [--all\n├── connect [name\n├── upload [name\n├── download [name\n└── ssh-config <name\npolicy\n├── set <name\n├── get <name\n└── list <name\nprovider\n├── create\n├── get <name\n├── list\n├── update <name\n└── delete <name\ninference\n├── set\n├── update\n└── get\ndoctor\n├── logs\n└── exec\ncompletions <shell\nCommands that accept an optional [name] argument — such as get , connect , upload , download , and logs — fall back to the last-used sandbox when the name is omitted. The CLI records the sandbox name each time you create or connect, and prints a hint showing which sandbox was selected. 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. openshell logs [name] View sandbox logs. Use --tail for streaming, --source and --level to filter. openshell term Launch the OpenShell Terminal — a dashboard showing sandbox status, live logs, and policy decisions in a single view. Navigate with j / k , press f to follow live output, s to filter by source, and q to quit. Refer to /sandboxes/create-and-manage for more on monitoring sandboxes and reading log entries. Gateway Commands Manage the OpenShell runtime cluster. Command Description openshell gateway start Deploy a new cluster. Add --remote user@host for remote deployment. 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 <url> Register an existing remote gateway by URL. openshell gateway select <name> Set the active cluster. All subsequent commands target this cluster. openshell gateway select List all registered clusters (when called without a name). Diagnostic Commands Troubleshoot gateway issues. Command Description openshell doctor logs Fetch logs from the gateway Docker container. Use --tail for streaming, -n to limit line count. openshell doctor exec -- <command> Run a command inside the gateway container (e.g., kubectl get pods -A , k9s , sh ). Sandbox Commands Create and manage isolated agent execution environments. Command Description 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 <name...> Delete one or more sandboxes by name. Use --all to delete every sandbox in the active gateway. openshell sandbox connect [name] Open an interactive SSH session into a running sandbox. openshell sandbox upload [name] Upload files from the host into a sandbox. openshell sandbox download [name] Download files from a sandbox to the host. openshell sandbox ssh-config <name> Print the generated SSH config block for a sandbox. Sandbox Create Flags The following flags control sandbox creation: Flag Description --name Assign a human-readable name to the sandbox. Auto-generated if omitted. --provider Attach a credential provider. Repeatable for multiple providers. --policy Path to a policy YAML file to apply at creation time. --upload Upload local files into the sandbox before running. --keep Keep the sandbox alive after the trailing command exits. --editor Launch vscode or cursor into /sandbox ; installs OpenShell-managed SSH config and implies --keep . --gpu Request a GPU-enabled sandbox. If no gateway is running, auto-bootstrap starts a GPU-enabled gateway. --editor Launch vscode or cursor into /sandbox ; installs OpenShell-managed SSH config and implies --keep . --forward Forward a local port into the sandbox at startup. --from Build from a community sandbox name, local Dockerfile directory, or container image reference. -- <command> The command to run inside the sandbox. Everything after -- is passed as the agent command. Policy Commands Apply and inspect sandbox policies at runtime. Command Description openshell policy set <name> Apply or update a policy on a running sandbox. Pass --policy <file> . openshell policy get <name> Show the active policy for a sandbox. Add --full for the complete policy with metadata. openshell policy list <name> List all policy versions applied to a sandbox, with status. Port Forwarding Commands Forward sandbox ports to the host for local access. Command Description openshell forward start <port> <name> Forward a sandbox port to the host. Add -d for background mode. openshell forward stop <port> <name> Stop an active port forward. openshell forward list List all active port forwards. Provider Commands Manage credential providers that inject secrets into sandboxes. Command Description openshell provider create Create a new credential provider. Refer to the flag reference below. openshell provider get <name> Show details of a provider. openshell provider list List all providers in the active cluster. openshell provider update <name> Update a provider’s credentials or configuration. openshell provider delete <name> Delete a provider. Provider Create Flags The following flags control provider creation: Flag Description --name Name for the provider. --type Provider type: claude , codex , opencode , github , gitlab , nvidia , generic , outlook . --from-existing Discover credentials from your current shell environment variables. --credential Set a credential explicitly. Format: KEY=VALUE or bare KEY to read from env. Repeatable. --config Set a configuration value. Format: KEY=VALUE . Repeatable. Inference Commands Configure the backend used by https://inference.local . openshell inference set Set the provider and model for managed inference. Both flags are required. Flag Description --provider Provider record name to use for injected credentials. --model Model identifier to force on generation requests. openshell inference update Update only the fields you specify. Flag Description --provider Replace the current provider record. --model Replace the current model ID. openshell inference get Show the current inference configuration, including provider, model, and version. Environment Variables The following environment variables override CLI defaults: Variable Description OPENSHELL_GATEWAY Name of the gateway to operate on. Overrides the active gateway set by openshell gateway select . OPENSHELL_SANDBOX_POLICY Default path to a policy YAML file. When set, openshell sandbox create uses this policy if no --policy flag is provided. Shell Completions Generate shell completion scripts for tab completion: $ openshell completions bash\nopenshell completions zsh\nopenshell completions fish\nPipe the output to your shell’s config file: $ openshell completions zsh >> ~/.zshrc\nsource ~/.zshrc\nBuilt-in Help Every command and subcommand includes built-in help. Use --help at any level to see available subcommands, flags, and usage examples: $ openshell --help\nopenshell sandbox --help\nopenshell sandbox create --help\nopenshell gateway --help\nHelp output groups flags under distinct headings: FLAGS for command-specific options, GATEWAY FLAGS for --gateway and --gateway-endpoint , and GLOBAL FLAGS for --verbose , --help , and --version","format":"text","summary":"Complete command reference for the openshell CLI. Every subcommand, flag, and option is documented here.","headings":[{"text":"CLI Reference","level":1},{"text":"Command Tree","level":2},{"text":"Status, Logs, and Terminal","level":2},{"text":"Gateway Commands","level":2},{"text":"Diagnostic Commands","level":2},{"text":"Sandbox Commands","level":2},{"text":"Sandbox Create Flags","level":3},{"text":"Policy Commands","level":2},{"text":"Port Forwarding Commands","level":2},{"text":"Provider Commands","level":2},{"text":"Provider Create Flags","level":3},{"text":"Inference Commands","level":2},{"text":"openshell inference set","level":3},{"text":"openshell inference update","level":3},{"text":"openshell inference get","level":3},{"text":"Environment Variables","level":2},{"text":"Shell Completions","level":2},{"text":"Built-in Help","level":2}]}
\ No newline at end of file
+{"id":"reference/cli","title":"CLI Reference","url":"reference/cli.html","last_modified":"2026-03-12T23:38:42.369360+00:00","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.1.0"},"product":{"name":"OpenShell","version":"0.1.0"},"description":"Complete command reference for the openshell CLI including all subcommands, flags, and environment variables.","tags":["CLI","Reference","Commands","AI Agents"],"topics":["Generative AI","Cybersecurity"],"content_type":"reference","learning_level":"technical_beginner","audience":["engineer","data_scientist"],"content":"CLI Reference Complete command reference for the openshell CLI. Every subcommand, flag, and option is documented here. Command Tree The full hierarchy of openshell subcommands: openshell\nstatus\nlogs [name\nterm\nforward\n├── start <port> <name\n├── stop <port> <name\n└── list\ngateway\n├── start\n├── stop\n├── destroy\n├── info\n├── add <url\n└── select [name\nsandbox\n├── create\n├── get [name\n├── list\n├── delete <name...> [--all\n├── connect [name\n├── upload [name\n├── download [name\n└── ssh-config <name\npolicy\n├── set <name\n├── get <name\n└── list <name\nprovider\n├── create\n├── get <name\n├── list\n├── update <name\n└── delete <name\ninference\n├── set\n├── update\n└── get\ndoctor\n├── logs\n└── exec\ncompletions <shell\nCommands that accept an optional [name] argument — such as get , connect , upload , download , and logs — fall back to the last-used sandbox when the name is omitted. The CLI records the sandbox name each time you create or connect, and prints a hint showing which sandbox was selected. 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. openshell logs [name] View sandbox logs. Use --tail for streaming, --source and --level to filter. openshell term Launch the OpenShell Terminal — a dashboard showing sandbox status, live logs, and policy decisions in a single view. Navigate with j / k , press f to follow live output, s to filter by source, and q to quit. Refer to /sandboxes/create-and-manage for more on monitoring sandboxes and reading log entries. Gateway Commands Manage the OpenShell runtime cluster. Command Description openshell gateway start Deploy a new cluster. Add --remote user@host for remote deployment. 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 <url> Register an existing remote gateway by URL. openshell gateway select <name> Set the active cluster. All subsequent commands target this cluster. openshell gateway select List all registered clusters (when called without a name). Diagnostic Commands Troubleshoot gateway issues. Command Description openshell doctor logs Fetch logs from the gateway Docker container. Use --tail for streaming, -n to limit line count. openshell doctor exec -- <command> Run a command inside the gateway container (e.g., kubectl get pods -A , k9s , sh ). Sandbox Commands Create and manage isolated agent execution environments. Command Description 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 <name...> Delete one or more sandboxes by name. Use --all to delete every sandbox in the active gateway. openshell sandbox connect [name] Open an interactive SSH session into a running sandbox. openshell sandbox upload [name] Upload files from the host into a sandbox. openshell sandbox download [name] Download files from a sandbox to the host. openshell sandbox ssh-config <name> Print the generated SSH config block for a sandbox. Sandbox Create Flags The following flags control sandbox creation: Flag Description --name Assign a human-readable name to the sandbox. Auto-generated if omitted. --provider Attach a credential provider. Repeatable for multiple providers. --policy Path to a policy YAML file to apply at creation time. --upload Upload local files into the sandbox before running. --keep Keep the sandbox alive after the trailing command exits. --editor Launch vscode or cursor into /sandbox ; installs OpenShell-managed SSH config and implies --keep . --gpu Request a GPU-enabled sandbox. If no gateway is running, auto-bootstrap starts a GPU-enabled gateway. --editor Launch vscode or cursor into /sandbox ; installs OpenShell-managed SSH config and implies --keep . --forward Forward a local port into the sandbox at startup. --from Build from a community sandbox name, local Dockerfile directory, or container image reference. -- <command> The command to run inside the sandbox. Everything after -- is passed as the agent command. Policy Commands Apply and inspect sandbox policies at runtime. Command Description openshell policy set <name> Apply or update a policy on a running sandbox. Pass --policy <file> . openshell policy get <name> Show the active policy for a sandbox. Add --full for the complete policy with metadata. openshell policy list <name> List all policy versions applied to a sandbox, with status. Port Forwarding Commands Forward sandbox ports to the host for local access. Command Description openshell forward start <port> <name> Forward a sandbox port to the host. Add -d for background mode. openshell forward stop <port> <name> Stop an active port forward. openshell forward list List all active port forwards. Provider Commands Manage credential providers that inject secrets into sandboxes. Command Description openshell provider create Create a new credential provider. Refer to the flag reference below. openshell provider get <name> Show details of a provider. openshell provider list List all providers in the active cluster. openshell provider update <name> Update a provider’s credentials or configuration. openshell provider delete <name> Delete a provider. Provider Create Flags The following flags control provider creation: Flag Description --name Name for the provider. --type Provider type: claude , codex , opencode , github , gitlab , nvidia , generic , outlook . --from-existing Discover credentials from your current shell environment variables. --credential Set a credential explicitly. Format: KEY=VALUE or bare KEY to read from env. Repeatable. --config Set a configuration value. Format: KEY=VALUE . Repeatable. Inference Commands Configure the backend used by https://inference.local . openshell inference set Set the provider and model for managed inference. Both flags are required. Flag Description --provider Provider record name to use for injected credentials. --model Model identifier to force on generation requests. openshell inference update Update only the fields you specify. Flag Description --provider Replace the current provider record. --model Replace the current model ID. openshell inference get Show the current inference configuration, including provider, model, and version. Environment Variables The following environment variables override CLI defaults: Variable Description OPENSHELL_GATEWAY Name of the gateway to operate on. Overrides the active gateway set by openshell gateway select . OPENSHELL_SANDBOX_POLICY Default path to a policy YAML file. When set, openshell sandbox create uses this policy if no --policy flag is provided. Shell Completions Generate shell completion scripts for tab completion: $ openshell completions bash\nopenshell completions zsh\nopenshell completions fish\nPipe the output to your shell’s config file: $ openshell completions zsh >> ~/.zshrc\nsource ~/.zshrc\nBuilt-in Help Every command and subcommand includes built-in help. Use --help at any level to see available subcommands, flags, and usage examples: $ openshell --help\nopenshell sandbox --help\nopenshell sandbox create --help\nopenshell gateway --help\nHelp output groups flags under distinct headings: FLAGS for command-specific options, GATEWAY FLAGS for --gateway and --gateway-endpoint , and GLOBAL FLAGS for --verbose , --help , and --version","format":"text","summary":"Complete command reference for the openshell CLI. Every subcommand, flag, and option is documented here.","headings":[{"text":"CLI Reference","level":1},{"text":"Command Tree","level":2},{"text":"Status, Logs, and Terminal","level":2},{"text":"Gateway Commands","level":2},{"text":"Diagnostic Commands","level":2},{"text":"Sandbox Commands","level":2},{"text":"Sandbox Create Flags","level":3},{"text":"Policy Commands","level":2},{"text":"Port Forwarding Commands","level":2},{"text":"Provider Commands","level":2},{"text":"Provider Create Flags","level":3},{"text":"Inference Commands","level":2},{"text":"openshell inference set","level":3},{"text":"openshell inference update","level":3},{"text":"openshell inference get","level":3},{"text":"Environment Variables","level":2},{"text":"Shell Completions","level":2},{"text":"Built-in Help","level":2}]}
\ No newline at end of file
diff --git a/pr-preview/pr-257/reference/default-policy.html b/pr-preview/pr-257/reference/default-policy.html
index 7d092defe..94fc1402f 100644
--- a/pr-preview/pr-257/reference/default-policy.html
+++ b/pr-preview/pr-257/reference/default-policy.html
@@ -387,7 +387,7 @@
 <p aria-level="2" class="caption" role="heading"><span class="caption-text">Get Started</span></p>
 <ul class="nav bd-sidenav">
 <li class="toctree-l1"><a class="reference internal" href="../get-started/quickstart.html">Quickstart</a></li>
-<li class="toctree-l1"><a class="reference internal" href="../tutorials/github-sandbox.html">Tutorial: GitHub Policy Iteration</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../tutorials/github-sandbox.html">GitHub Policy Tutorial</a></li>
 </ul>
 <p aria-level="2" class="caption" role="heading"><span class="caption-text">Sandboxes</span></p>
 <ul class="nav bd-sidenav">
@@ -758,6 +758,35 @@
 </table>
 </div>
 <p>Only the following binaries can use these endpoints: <code class="docutils literal notranslate"><span class="pre">/usr/bin/curl</span></code>, <code class="docutils literal notranslate"><span class="pre">/usr/bin/wget</span></code>, <code class="docutils literal notranslate"><span class="pre">/sandbox/.cursor-server/**</span></code>.</p>
+<h3>opencode</h3>
+<div class="pst-scrollable-table-container"><table class="table">
+<thead>
+<tr class="row-odd"><th class="head"><p>Endpoint</p></th>
+<th class="head"><p>Port</p></th>
+<th class="head"><p>TLS</p></th>
+<th class="head"><p>Access</p></th>
+</tr>
+</thead>
+<tbody>
+<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">registry.npmjs.org</span></code></p></td>
+<td><p>443</p></td>
+<td><p>—</p></td>
+<td><p>L4 passthrough</p></td>
+</tr>
+<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">opencode.ai</span></code></p></td>
+<td><p>443</p></td>
+<td><p>—</p></td>
+<td><p>L4 passthrough</p></td>
+</tr>
+<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">integrate.api.nvidia.com</span></code></p></td>
+<td><p>443</p></td>
+<td><p>—</p></td>
+<td><p>L4 passthrough</p></td>
+</tr>
+</tbody>
+</table>
+</div>
+<p>Only the following binaries can use these endpoints: <code class="docutils literal notranslate"><span class="pre">/usr/lib/node_modules/opencode-ai/bin/.opencode</span></code>, <code class="docutils literal notranslate"><span class="pre">/usr/bin/node</span></code>, <code class="docutils literal notranslate"><span class="pre">/usr/local/bin/opencode</span></code>.</p>
 </section>
 </section>
 
diff --git a/pr-preview/pr-257/reference/default-policy.json b/pr-preview/pr-257/reference/default-policy.json
index bdcfc1bcd..5e46f7995 100644
--- a/pr-preview/pr-257/reference/default-policy.json
+++ b/pr-preview/pr-257/reference/default-policy.json
@@ -1 +1 @@
-{"id":"reference/default-policy","title":"Default Policy Reference","url":"reference/default-policy.html","last_modified":"2026-03-12T09:12:26.605877+00:00","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.1.0"},"product":{"name":"OpenShell","version":"0.1.0"},"description":"Breakdown of the built-in default policy applied when you create an OpenShell sandbox without a custom policy.","tags":["ai_agents","sandboxing","security","policy"],"topics":["generative_ai","cybersecurity"],"content_type":"reference","learning_level":"technical_beginner","audience":["engineer","data_scientist"],"keywords":["openshell default policy","sandbox policy","agent compatibility"],"content":"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 file. Agent Compatibility The following table shows the coverage of the default policy for common agents. Agent Coverage Action Required Claude Code Full None. Works out of the box. OpenCode Partial Add opencode.ai endpoint and OpenCode binary paths. Codex None Provide a complete custom policy with OpenAI endpoints and Codex binary paths. If you run a non-Claude agent without a custom policy, the agent’s API calls are denied by the proxy. You must provide a policy that declares the agent’s endpoints and binaries. Default Policy Blocks The following tables show the default policy blocks pre-configured in the file. <h2>Filesystem, Landlock, and Process</h2\nSection Setting Value Filesystem Read-only /usr , /lib , /proc , /dev/urandom , /app , /etc , /var/log Read-write /sandbox , /tmp , /dev/null Workdir included Yes Landlock Compatibility best_effort (uses the highest ABI the host kernel supports) Process User / Group sandbox / sandbox <h2>Network Policy Blocks</h2\nEach block pairs a set of endpoints (host and port) with a set of binaries (executable paths inside the sandbox). The proxy identifies the calling binary by resolving the socket to a PID through /proc/net/tcp and reading /proc/{pid}/exe . A connection is allowed only when both the destination and the calling binary match an entry in the same block. All other outbound traffic is denied. <h3>Anthropic API and Telemetry</h3\nAllows Claude Code to reach its API, feature-flagging (Statsig), error reporting (Sentry), release notes, and the Claude platform dashboard. Endpoint Port TLS Access api.anthropic.com 443 terminate full statsig.anthropic.com 443 — L4 passthrough sentry.io 443 — L4 passthrough raw.githubusercontent.com 443 — L4 passthrough platform.claude.com 443 — L4 passthrough Only the following binaries can use these endpoints: /usr/local/bin/claude , /usr/bin/node . <h3>Git Clone and Fetch</h3\nAllows git clone , git fetch , and git pull over HTTPS via Git Smart HTTP. Push ( git-receive-pack ) is disabled by default. Endpoint Port TLS Rules github.com 443 terminate GET /**/info/refs* , POST /**/git-upload-pack Only the following binaries can use these endpoints: /usr/bin/git . <h3>NVIDIA API Catalog</h3\nAllows outbound calls to the NVIDIA hosted inference API. Used by agents that route LLM requests through integrate.api.nvidia.com . Endpoint Port TLS Access integrate.api.nvidia.com 443 — L4 passthrough Only the following binaries can use these endpoints: /usr/bin/curl , /bin/bash , /usr/local/bin/opencode . <h3>GitHub API (Read-Only)</h3\nGrants read-only access to the GitHub REST API. Enables issue reads, PR listing, and repository metadata lookups without allowing mutations. Endpoint Port TLS Access api.github.com 443 terminate read-only Only the following binaries can use these endpoints: /usr/local/bin/claude , /usr/bin/gh . <h3>Python Package Installation</h3\nAllows pip install and uv pip install to reach PyPI, python-build-standalone releases on GitHub, and downloads.python.org . Endpoint Port TLS Access pypi.org 443 — L4 passthrough files.pythonhosted.org 443 — L4 passthrough github.com 443 — L4 passthrough objects.githubusercontent.com 443 — L4 passthrough api.github.com 443 — L4 passthrough downloads.python.org 443 — L4 passthrough Only the following binaries can use these endpoints: /sandbox/.venv/bin/python , /sandbox/.venv/bin/python3 , /sandbox/.venv/bin/pip , /app/.venv/bin/python , /app/.venv/bin/python3 , /app/.venv/bin/pip , /usr/local/bin/uv , /sandbox/.uv/python/** . <h3>VS Code Remote and Marketplace</h3\nAllows VS Code Server, Remote Containers, and extension marketplace traffic so remote development sessions can download updates and extensions. Endpoint Port TLS Access update.code.visualstudio.com 443 — L4 passthrough az764295.vo.msecnd.net 443 — L4 passthrough vscode.download.prss.microsoft.com 443 — L4 passthrough marketplace.visualstudio.com 443 — L4 passthrough gallerycdn.vsassets.io 443 — L4 passthrough Only the following binaries can use these endpoints: /usr/bin/curl , /usr/bin/wget , /sandbox/.vscode-server/** , /sandbox/.vscode-remote-containers/** . <h3>cursor</h3\nEndpoint Port TLS Access cursor.blob.core.windows.net 443 — L4 passthrough api2.cursor.sh 443 — L4 passthrough repo.cursor.sh 443 — L4 passthrough download.cursor.sh 443 — L4 passthrough cursor.download.prss.microsoft.com 443 — L4 passthrough Only the following binaries can use these endpoints: /usr/bin/curl , /usr/bin/wget , /sandbox/.cursor-server/**","format":"text","summary":"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 file.","headings":[{"text":"Default Policy Reference","level":1},{"text":"Agent Compatibility","level":2},{"text":"Default Policy Blocks","level":2}]}
\ No newline at end of file
+{"id":"reference/default-policy","title":"Default Policy Reference","url":"reference/default-policy.html","last_modified":"2026-03-12T23:38:42.351842+00:00","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.1.0"},"product":{"name":"OpenShell","version":"0.1.0"},"description":"Breakdown of the built-in default policy applied when you create an OpenShell sandbox without a custom policy.","tags":["ai_agents","sandboxing","security","policy"],"topics":["generative_ai","cybersecurity"],"content_type":"reference","learning_level":"technical_beginner","audience":["engineer","data_scientist"],"keywords":["openshell default policy","sandbox policy","agent compatibility"],"content":"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 file. Agent Compatibility The following table shows the coverage of the default policy for common agents. Agent Coverage Action Required Claude Code Full None. Works out of the box. OpenCode Partial Add opencode.ai endpoint and OpenCode binary paths. Codex None Provide a complete custom policy with OpenAI endpoints and Codex binary paths. If you run a non-Claude agent without a custom policy, the agent’s API calls are denied by the proxy. You must provide a policy that declares the agent’s endpoints and binaries. Default Policy Blocks The following tables show the default policy blocks pre-configured in the file. <h2>Filesystem, Landlock, and Process</h2\nSection Setting Value Filesystem Read-only /usr , /lib , /proc , /dev/urandom , /app , /etc , /var/log Read-write /sandbox , /tmp , /dev/null Workdir included Yes Landlock Compatibility best_effort (uses the highest ABI the host kernel supports) Process User / Group sandbox / sandbox <h2>Network Policy Blocks</h2\nEach block pairs a set of endpoints (host and port) with a set of binaries (executable paths inside the sandbox). The proxy identifies the calling binary by resolving the socket to a PID through /proc/net/tcp and reading /proc/{pid}/exe . A connection is allowed only when both the destination and the calling binary match an entry in the same block. All other outbound traffic is denied. <h3>Anthropic API and Telemetry</h3\nAllows Claude Code to reach its API, feature-flagging (Statsig), error reporting (Sentry), release notes, and the Claude platform dashboard. Endpoint Port TLS Access api.anthropic.com 443 terminate full statsig.anthropic.com 443 — L4 passthrough sentry.io 443 — L4 passthrough raw.githubusercontent.com 443 — L4 passthrough platform.claude.com 443 — L4 passthrough Only the following binaries can use these endpoints: /usr/local/bin/claude , /usr/bin/node . <h3>Git Clone and Fetch</h3\nAllows git clone , git fetch , and git pull over HTTPS via Git Smart HTTP. Push ( git-receive-pack ) is disabled by default. Endpoint Port TLS Rules github.com 443 terminate GET /**/info/refs* , POST /**/git-upload-pack Only the following binaries can use these endpoints: /usr/bin/git . <h3>NVIDIA API Catalog</h3\nAllows outbound calls to the NVIDIA hosted inference API. Used by agents that route LLM requests through integrate.api.nvidia.com . Endpoint Port TLS Access integrate.api.nvidia.com 443 — L4 passthrough Only the following binaries can use these endpoints: /usr/bin/curl , /bin/bash , /usr/local/bin/opencode . <h3>GitHub API (Read-Only)</h3\nGrants read-only access to the GitHub REST API. Enables issue reads, PR listing, and repository metadata lookups without allowing mutations. Endpoint Port TLS Access api.github.com 443 terminate read-only Only the following binaries can use these endpoints: /usr/local/bin/claude , /usr/bin/gh . <h3>Python Package Installation</h3\nAllows pip install and uv pip install to reach PyPI, python-build-standalone releases on GitHub, and downloads.python.org . Endpoint Port TLS Access pypi.org 443 — L4 passthrough files.pythonhosted.org 443 — L4 passthrough github.com 443 — L4 passthrough objects.githubusercontent.com 443 — L4 passthrough api.github.com 443 — L4 passthrough downloads.python.org 443 — L4 passthrough Only the following binaries can use these endpoints: /sandbox/.venv/bin/python , /sandbox/.venv/bin/python3 , /sandbox/.venv/bin/pip , /app/.venv/bin/python , /app/.venv/bin/python3 , /app/.venv/bin/pip , /usr/local/bin/uv , /sandbox/.uv/python/** . <h3>VS Code Remote and Marketplace</h3\nAllows VS Code Server, Remote Containers, and extension marketplace traffic so remote development sessions can download updates and extensions. Endpoint Port TLS Access update.code.visualstudio.com 443 — L4 passthrough az764295.vo.msecnd.net 443 — L4 passthrough vscode.download.prss.microsoft.com 443 — L4 passthrough marketplace.visualstudio.com 443 — L4 passthrough gallerycdn.vsassets.io 443 — L4 passthrough Only the following binaries can use these endpoints: /usr/bin/curl , /usr/bin/wget , /sandbox/.vscode-server/** , /sandbox/.vscode-remote-containers/** . <h3>cursor</h3\nEndpoint Port TLS Access cursor.blob.core.windows.net 443 — L4 passthrough api2.cursor.sh 443 — L4 passthrough repo.cursor.sh 443 — L4 passthrough download.cursor.sh 443 — L4 passthrough cursor.download.prss.microsoft.com 443 — L4 passthrough Only the following binaries can use these endpoints: /usr/bin/curl , /usr/bin/wget , /sandbox/.cursor-server/** . <h3>opencode</h3\nEndpoint Port TLS Access registry.npmjs.org 443 — L4 passthrough opencode.ai 443 — L4 passthrough integrate.api.nvidia.com 443 — L4 passthrough Only the following binaries can use these endpoints: /usr/lib/node_modules/opencode-ai/bin/.opencode , /usr/bin/node , /usr/local/bin/opencode","format":"text","summary":"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 file.","headings":[{"text":"Default Policy Reference","level":1},{"text":"Agent Compatibility","level":2},{"text":"Default Policy Blocks","level":2}]}
\ No newline at end of file
diff --git a/pr-preview/pr-257/reference/policy-schema.html b/pr-preview/pr-257/reference/policy-schema.html
index 9f2715034..914728d6d 100644
--- a/pr-preview/pr-257/reference/policy-schema.html
+++ b/pr-preview/pr-257/reference/policy-schema.html
@@ -387,7 +387,7 @@
 <p aria-level="2" class="caption" role="heading"><span class="caption-text">Get Started</span></p>
 <ul class="nav bd-sidenav">
 <li class="toctree-l1"><a class="reference internal" href="../get-started/quickstart.html">Quickstart</a></li>
-<li class="toctree-l1"><a class="reference internal" href="../tutorials/github-sandbox.html">Tutorial: GitHub Policy Iteration</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../tutorials/github-sandbox.html">GitHub Policy Tutorial</a></li>
 </ul>
 <p aria-level="2" class="caption" role="heading"><span class="caption-text">Sandboxes</span></p>
 <ul class="nav bd-sidenav">
diff --git a/pr-preview/pr-257/reference/policy-schema.json b/pr-preview/pr-257/reference/policy-schema.json
index 97bf6646c..c0eab2028 100644
--- a/pr-preview/pr-257/reference/policy-schema.json
+++ b/pr-preview/pr-257/reference/policy-schema.json
@@ -1 +1 @@
-{"id":"reference/policy-schema","title":"Policy Schema Reference","url":"reference/policy-schema.html","last_modified":"2026-03-12T09:12:26.591246+00:00","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.1.0"},"product":{"name":"OpenShell","version":"0.1.0"},"description":"Complete field reference for the sandbox policy YAML including static and dynamic sections.","tags":["Policy","Schema","YAML","Reference","Security"],"topics":["Generative AI","Cybersecurity"],"content_type":"reference","learning_level":"technical_advanced","audience":["engineer"],"content":"Policy Schema Reference Complete field reference for the sandbox policy YAML. Each field is documented with its type, whether it is required, and whether it is static (locked at sandbox creation) or dynamic (hot-reloadable on a running sandbox). Top-Level Structure A policy YAML file contains the following top-level fields: version: 1\nfilesystem_policy: { ...\nlandlock: { ...\nprocess: { ...\nnetwork_policies: { ...\nField Type Required Category Description version integer Yes – Policy schema version. Must be 1 . filesystem_policy object No Static Controls which directories the agent can read and write. landlock object No Static Configures Landlock LSM enforcement behavior. process object No Static Sets the user and group the agent process runs as. network_policies map No Dynamic Declares which binaries can reach which network endpoints. Static fields are set at sandbox creation time. Changing them requires destroying and recreating the sandbox. Dynamic fields can be updated on a running sandbox with openshell policy set and take effect without restarting. Version The version field identifies which schema the policy uses: Field Type Required Description version integer Yes Schema version number. Currently must be 1 . Filesystem Policy Category: Static Controls filesystem access inside the sandbox. Paths not listed in either read_only or read_write are inaccessible. Field Type Required Description include_workdir bool No When true , automatically adds the agent’s working directory to read_write . read_only list of strings No Paths the agent can read but not modify. Typically system directories like /usr , /lib , /etc . read_write list of strings No Paths the agent can read and write. Typically /sandbox (working directory) and /tmp . Validation constraints: Every path must be absolute (start with / ). Paths must not contain .. traversal components. The server normalizes paths before storage, but rejects policies where traversal would escape the intended scope. Read-write paths must not be overly broad (for example, / alone is rejected). Each individual path must not exceed 4096 characters. The combined total of read_only and read_write paths must not exceed 256. Policies that violate these constraints are rejected with INVALID_ARGUMENT at creation or update time. Disk-loaded YAML policies that fail validation fall back to a restrictive default. Example: filesystem_policy\ninclude_workdir: true\nread_only\n/usr\n/lib\n/proc\n/dev/urandom\n/etc\nread_write\n/sandbox\n/tmp\n/dev/null\nLandlock Category: Static Configures Landlock LSM enforcement at the kernel level. Landlock provides mandatory filesystem access control below what UNIX permissions allow. Field Type Required Values Description compatibility string No best_effort , hard_requirement How OpenShell handles kernel ABI differences. best_effort uses the highest Landlock ABI the host kernel supports. hard_requirement fails if the required ABI is unavailable. Example: landlock\ncompatibility: best_effort\nProcess Category: Static Sets the OS-level identity for the agent process inside the sandbox. Field Type Required Description run_as_user string No The user name or UID the agent process runs as. Default: sandbox . run_as_group string No The group name or GID the agent process runs as. Default: sandbox . Validation constraint: Neither run_as_user nor run_as_group may be set to root or 0 . Policies that request root process identity are rejected at creation or update time. Example: process\nrun_as_user: sandbox\nrun_as_group: sandbox\nNetwork Policies Category: Dynamic A map of named network policy entries. Each entry declares a set of endpoints and a set of binaries. Only the listed binaries are permitted to connect to the listed endpoints. The map key is a logical identifier. The name field inside the entry is the display name used in logs. 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. endpoints list of endpoint objects Yes Hosts and ports this entry permits. binaries list of binary objects Yes Executables allowed to connect to these endpoints. Endpoint Object Each endpoint defines a reachable destination and optional inspection rules. Field Type Required Description host string Yes Hostname or IP address. Supports wildcards: *.example.com matches any subdomain. port integer Yes TCP port number. protocol string No Set to rest to enable HTTP request inspection. Omit for TCP passthrough. tls string No TLS handling mode. terminate decrypts TLS at the proxy for inspection. passthrough forwards encrypted traffic without inspection. Only relevant when protocol is rest . enforcement string No enforce actively blocks disallowed requests. audit logs violations but allows traffic through. access string No HTTP access level. One of read-only , read-write , or full . Mutually exclusive with rules . rules list of rule objects No Fine-grained per-method, per-path allow rules. Mutually exclusive with access . Access Levels The access field accepts one of the following values: Value Allowed HTTP Methods full All methods and paths. read-only GET , HEAD , OPTIONS . read-write GET , HEAD , OPTIONS , POST , PUT , PATCH . Rule Object Used when access is not set. Each rule explicitly allows a method and path combination. Field Type Required Description allow.method string Yes HTTP method to allow (for example, GET , POST ). allow.path string Yes URL path pattern. Supports * and ** glob syntax. Example with rules: rules\nallow\nmethod: GET\npath: /**/info/refs\nallow\nmethod: POST\npath: /**/git-upload-pack\nBinary Object Identifies an executable that is permitted to use the associated endpoints. Field Type Required Description path string Yes Filesystem path to the executable. Supports glob patterns with * and ** . For example, /sandbox/.vscode-server/** matches any executable under that directory tree. Full Example The following policy grants read-only GitHub API access and npm registry access: network_policies\ngithub_rest_api\nname: github-rest-api\nendpoints\nhost: api.github.com\nport: 443\nprotocol: rest\ntls: terminate\nenforcement: enforce\naccess: read-only\nbinaries\npath: /usr/local/bin/claude\npath: /usr/bin/node\npath: /usr/bin/gh\nnpm_registry\nname: npm-registry\nendpoints\nhost: registry.npmjs.org\nport: 443\nbinaries\npath: /usr/bin/npm\npath: /usr/bin/node","format":"text","summary":"Complete field reference for the sandbox policy YAML. Each field is documented with its type, whether it is required, and whether it is static (locked at sandbox creation) or dynamic (hot-reloadable on a running sandbox).","headings":[{"text":"Policy Schema Reference","level":1},{"text":"Top-Level Structure","level":2},{"text":"Version","level":2},{"text":"Filesystem Policy","level":2},{"text":"Landlock","level":2},{"text":"Process","level":2},{"text":"Network Policies","level":2},{"text":"Network Policy Entry","level":3},{"text":"Endpoint Object","level":3},{"text":"Access Levels","level":4},{"text":"Rule Object","level":4},{"text":"Binary Object","level":3},{"text":"Full Example","level":3}]}
\ No newline at end of file
+{"id":"reference/policy-schema","title":"Policy Schema Reference","url":"reference/policy-schema.html","last_modified":"2026-03-12T23:38:42.386319+00:00","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.1.0"},"product":{"name":"OpenShell","version":"0.1.0"},"description":"Complete field reference for the sandbox policy YAML including static and dynamic sections.","tags":["Policy","Schema","YAML","Reference","Security"],"topics":["Generative AI","Cybersecurity"],"content_type":"reference","learning_level":"technical_advanced","audience":["engineer"],"content":"Policy Schema Reference Complete field reference for the sandbox policy YAML. Each field is documented with its type, whether it is required, and whether it is static (locked at sandbox creation) or dynamic (hot-reloadable on a running sandbox). Top-Level Structure A policy YAML file contains the following top-level fields: version: 1\nfilesystem_policy: { ...\nlandlock: { ...\nprocess: { ...\nnetwork_policies: { ...\nField Type Required Category Description version integer Yes – Policy schema version. Must be 1 . filesystem_policy object No Static Controls which directories the agent can read and write. landlock object No Static Configures Landlock LSM enforcement behavior. process object No Static Sets the user and group the agent process runs as. network_policies map No Dynamic Declares which binaries can reach which network endpoints. Static fields are set at sandbox creation time. Changing them requires destroying and recreating the sandbox. Dynamic fields can be updated on a running sandbox with openshell policy set and take effect without restarting. Version The version field identifies which schema the policy uses: Field Type Required Description version integer Yes Schema version number. Currently must be 1 . Filesystem Policy Category: Static Controls filesystem access inside the sandbox. Paths not listed in either read_only or read_write are inaccessible. Field Type Required Description include_workdir bool No When true , automatically adds the agent’s working directory to read_write . read_only list of strings No Paths the agent can read but not modify. Typically system directories like /usr , /lib , /etc . read_write list of strings No Paths the agent can read and write. Typically /sandbox (working directory) and /tmp . Validation constraints: Every path must be absolute (start with / ). Paths must not contain .. traversal components. The server normalizes paths before storage, but rejects policies where traversal would escape the intended scope. Read-write paths must not be overly broad (for example, / alone is rejected). Each individual path must not exceed 4096 characters. The combined total of read_only and read_write paths must not exceed 256. Policies that violate these constraints are rejected with INVALID_ARGUMENT at creation or update time. Disk-loaded YAML policies that fail validation fall back to a restrictive default. Example: filesystem_policy\ninclude_workdir: true\nread_only\n/usr\n/lib\n/proc\n/dev/urandom\n/etc\nread_write\n/sandbox\n/tmp\n/dev/null\nLandlock Category: Static Configures Landlock LSM enforcement at the kernel level. Landlock provides mandatory filesystem access control below what UNIX permissions allow. Field Type Required Values Description compatibility string No best_effort , hard_requirement How OpenShell handles kernel ABI differences. best_effort uses the highest Landlock ABI the host kernel supports. hard_requirement fails if the required ABI is unavailable. Example: landlock\ncompatibility: best_effort\nProcess Category: Static Sets the OS-level identity for the agent process inside the sandbox. Field Type Required Description run_as_user string No The user name or UID the agent process runs as. Default: sandbox . run_as_group string No The group name or GID the agent process runs as. Default: sandbox . Validation constraint: Neither run_as_user nor run_as_group may be set to root or 0 . Policies that request root process identity are rejected at creation or update time. Example: process\nrun_as_user: sandbox\nrun_as_group: sandbox\nNetwork Policies Category: Dynamic A map of named network policy entries. Each entry declares a set of endpoints and a set of binaries. Only the listed binaries are permitted to connect to the listed endpoints. The map key is a logical identifier. The name field inside the entry is the display name used in logs. 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. endpoints list of endpoint objects Yes Hosts and ports this entry permits. binaries list of binary objects Yes Executables allowed to connect to these endpoints. Endpoint Object Each endpoint defines a reachable destination and optional inspection rules. Field Type Required Description host string Yes Hostname or IP address. Supports wildcards: *.example.com matches any subdomain. port integer Yes TCP port number. protocol string No Set to rest to enable HTTP request inspection. Omit for TCP passthrough. tls string No TLS handling mode. terminate decrypts TLS at the proxy for inspection. passthrough forwards encrypted traffic without inspection. Only relevant when protocol is rest . enforcement string No enforce actively blocks disallowed requests. audit logs violations but allows traffic through. access string No HTTP access level. One of read-only , read-write , or full . Mutually exclusive with rules . rules list of rule objects No Fine-grained per-method, per-path allow rules. Mutually exclusive with access . Access Levels The access field accepts one of the following values: Value Allowed HTTP Methods full All methods and paths. read-only GET , HEAD , OPTIONS . read-write GET , HEAD , OPTIONS , POST , PUT , PATCH . Rule Object Used when access is not set. Each rule explicitly allows a method and path combination. Field Type Required Description allow.method string Yes HTTP method to allow (for example, GET , POST ). allow.path string Yes URL path pattern. Supports * and ** glob syntax. Example with rules: rules\nallow\nmethod: GET\npath: /**/info/refs\nallow\nmethod: POST\npath: /**/git-upload-pack\nBinary Object Identifies an executable that is permitted to use the associated endpoints. Field Type Required Description path string Yes Filesystem path to the executable. Supports glob patterns with * and ** . For example, /sandbox/.vscode-server/** matches any executable under that directory tree. Full Example The following policy grants read-only GitHub API access and npm registry access: network_policies\ngithub_rest_api\nname: github-rest-api\nendpoints\nhost: api.github.com\nport: 443\nprotocol: rest\ntls: terminate\nenforcement: enforce\naccess: read-only\nbinaries\npath: /usr/local/bin/claude\npath: /usr/bin/node\npath: /usr/bin/gh\nnpm_registry\nname: npm-registry\nendpoints\nhost: registry.npmjs.org\nport: 443\nbinaries\npath: /usr/bin/npm\npath: /usr/bin/node","format":"text","summary":"Complete field reference for the sandbox policy YAML. Each field is documented with its type, whether it is required, and whether it is static (locked at sandbox creation) or dynamic (hot-reloadable on a running sandbox).","headings":[{"text":"Policy Schema Reference","level":1},{"text":"Top-Level Structure","level":2},{"text":"Version","level":2},{"text":"Filesystem Policy","level":2},{"text":"Landlock","level":2},{"text":"Process","level":2},{"text":"Network Policies","level":2},{"text":"Network Policy Entry","level":3},{"text":"Endpoint Object","level":3},{"text":"Access Levels","level":4},{"text":"Rule Object","level":4},{"text":"Binary Object","level":3},{"text":"Full Example","level":3}]}
\ No newline at end of file
diff --git a/pr-preview/pr-257/reference/support-matrix.html b/pr-preview/pr-257/reference/support-matrix.html
index acab9da73..6294c48d5 100644
--- a/pr-preview/pr-257/reference/support-matrix.html
+++ b/pr-preview/pr-257/reference/support-matrix.html
@@ -387,7 +387,7 @@
 <p aria-level="2" class="caption" role="heading"><span class="caption-text">Get Started</span></p>
 <ul class="nav bd-sidenav">
 <li class="toctree-l1"><a class="reference internal" href="../get-started/quickstart.html">Quickstart</a></li>
-<li class="toctree-l1"><a class="reference internal" href="../tutorials/github-sandbox.html">Tutorial: GitHub Policy Iteration</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../tutorials/github-sandbox.html">GitHub Policy Tutorial</a></li>
 </ul>
 <p aria-level="2" class="caption" role="heading"><span class="caption-text">Sandboxes</span></p>
 <ul class="nav bd-sidenav">
diff --git a/pr-preview/pr-257/reference/support-matrix.json b/pr-preview/pr-257/reference/support-matrix.json
index bcbe390bf..91b2a3261 100644
--- a/pr-preview/pr-257/reference/support-matrix.json
+++ b/pr-preview/pr-257/reference/support-matrix.json
@@ -1 +1 @@
-{"id":"reference/support-matrix","title":"Support Matrix","url":"reference/support-matrix.html","last_modified":"2026-03-12T09:12:26.597241+00:00","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.1.0"},"product":{"name":"OpenShell","version":"0.1.0"},"content":"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 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 Gateway ghcr.io ghcr.io/nvidia/openshell/gateway:latest Cluster startup (via Helm chart) Sandbox ghcr.io ghcr.io/nvidia/openshell/sandbox:latest First sandbox creation (via Helm chart) Community sandboxes GHCR ghcr.io/nvidia/openshell-community/sandboxes/{name}:latest openshell sandbox create --from <name> 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 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 table","format":"text","summary":"This page lists the platform, software, runtime, and kernel requirements for running OpenShell.","headings":[{"text":"Support Matrix","level":1},{"text":"Supported Platforms","level":2},{"text":"Software Prerequisites","level":2},{"text":"Sandbox Runtime Versions","level":2},{"text":"Container Images","level":2},{"text":"Kernel Requirements","level":2},{"text":"Agent Compatibility","level":2}]}
\ No newline at end of file
+{"id":"reference/support-matrix","title":"Support Matrix","url":"reference/support-matrix.html","last_modified":"2026-03-12T23:38:42.375601+00:00","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.1.0"},"product":{"name":"OpenShell","version":"0.1.0"},"content":"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 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 Gateway ghcr.io ghcr.io/nvidia/openshell/gateway:latest Cluster startup (via Helm chart) Sandbox ghcr.io ghcr.io/nvidia/openshell/sandbox:latest First sandbox creation (via Helm chart) Community sandboxes GHCR ghcr.io/nvidia/openshell-community/sandboxes/{name}:latest openshell sandbox create --from <name> 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 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 table","format":"text","summary":"This page lists the platform, software, runtime, and kernel requirements for running OpenShell.","headings":[{"text":"Support Matrix","level":1},{"text":"Supported Platforms","level":2},{"text":"Software Prerequisites","level":2},{"text":"Sandbox Runtime Versions","level":2},{"text":"Container Images","level":2},{"text":"Kernel Requirements","level":2},{"text":"Agent Compatibility","level":2}]}
\ No newline at end of file
diff --git a/pr-preview/pr-257/resources/eula.html b/pr-preview/pr-257/resources/eula.html
index c361ec205..3f195539a 100644
--- a/pr-preview/pr-257/resources/eula.html
+++ b/pr-preview/pr-257/resources/eula.html
@@ -382,7 +382,7 @@
 <p aria-level="2" class="caption" role="heading"><span class="caption-text">Get Started</span></p>
 <ul class="nav bd-sidenav">
 <li class="toctree-l1"><a class="reference internal" href="../get-started/quickstart.html">Quickstart</a></li>
-<li class="toctree-l1"><a class="reference internal" href="../tutorials/github-sandbox.html">Tutorial: GitHub Policy Iteration</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../tutorials/github-sandbox.html">GitHub Policy Tutorial</a></li>
 </ul>
 <p aria-level="2" class="caption" role="heading"><span class="caption-text">Sandboxes</span></p>
 <ul class="nav bd-sidenav">
diff --git a/pr-preview/pr-257/resources/eula.json b/pr-preview/pr-257/resources/eula.json
index bb0b80a93..4cd68a378 100644
--- a/pr-preview/pr-257/resources/eula.json
+++ b/pr-preview/pr-257/resources/eula.json
@@ -1 +1 @@
-{"id":"resources/eula","title":"License","url":"resources/eula.html","last_modified":"2026-03-12T09:12:26.607534+00:00","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.1.0"},"product":{"name":"OpenShell","version":"0.1.0"},"description":"NVIDIA OpenShell license agreement and terms of use.","tags":["License","EULA"],"topics":["Legal"],"content_type":"reference","learning_level":"technical_beginner","audience":["engineer","data_scientist"],"content":"License","format":"text","summary":"<!-- SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. SPDX-License-Identifier: Apache-2.0 --> License","headings":[{"text":"License","level":1}]}
\ No newline at end of file
+{"id":"resources/eula","title":"License","url":"resources/eula.html","last_modified":"2026-03-12T23:38:42.435768+00:00","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.1.0"},"product":{"name":"OpenShell","version":"0.1.0"},"description":"NVIDIA OpenShell license agreement and terms of use.","tags":["License","EULA"],"topics":["Legal"],"content_type":"reference","learning_level":"technical_beginner","audience":["engineer","data_scientist"],"content":"License","format":"text","summary":"<!-- SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. SPDX-License-Identifier: Apache-2.0 --> License","headings":[{"text":"License","level":1}]}
\ No newline at end of file
diff --git a/pr-preview/pr-257/sandboxes/community-sandboxes.html b/pr-preview/pr-257/sandboxes/community-sandboxes.html
index 9716cceb5..487134e20 100644
--- a/pr-preview/pr-257/sandboxes/community-sandboxes.html
+++ b/pr-preview/pr-257/sandboxes/community-sandboxes.html
@@ -387,7 +387,7 @@
 <p aria-level="2" class="caption" role="heading"><span class="caption-text">Get Started</span></p>
 <ul class="nav bd-sidenav">
 <li class="toctree-l1"><a class="reference internal" href="../get-started/quickstart.html">Quickstart</a></li>
-<li class="toctree-l1"><a class="reference internal" href="../tutorials/github-sandbox.html">Tutorial: GitHub Policy Iteration</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../tutorials/github-sandbox.html">GitHub Policy Tutorial</a></li>
 </ul>
 <p aria-level="2" class="caption" role="heading"><span class="caption-text">Sandboxes</span></p>
 <ul class="current nav bd-sidenav">
diff --git a/pr-preview/pr-257/sandboxes/community-sandboxes.json b/pr-preview/pr-257/sandboxes/community-sandboxes.json
index 23a40d768..540964816 100644
--- a/pr-preview/pr-257/sandboxes/community-sandboxes.json
+++ b/pr-preview/pr-257/sandboxes/community-sandboxes.json
@@ -1 +1 @@
-{"id":"sandboxes/community-sandboxes","title":"Community Sandboxes","url":"sandboxes/community-sandboxes.html","last_modified":"2026-03-12T09:12:26.635368+00:00","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.1.0"},"product":{"name":"OpenShell","version":"0.1.0"},"description":"Use pre-built sandboxes from the OpenShell Community catalog or contribute your own.","tags":["Community","Sandbox","Container Image","Open Source"],"topics":["Generative AI","Cybersecurity"],"content_type":"concept","learning_level":"technical_beginner","audience":["engineer","data_scientist"],"content":"Community Sandboxes Use pre-built sandboxes from the OpenShell Community catalog, or contribute your\nown. What Are Community Sandboxes Community sandboxes are ready-to-use environments published in the\nOpenShell Community repository\nEach sandbox bundles a Dockerfile, policy, optional skills, and startup scripts\ninto a single package that you can launch with one command. Current Catalog The following community sandboxes are available in the catalog. Sandbox Description base Foundational image with system tools and dev environment openclaw Open agent manipulation and control sdg Synthetic data generation workflows simulation General-purpose simulation sandboxes Use a Community Sandbox Launch a community sandbox by name with the --from flag: $ openshell sandbox create --from openclaw\nWhen you pass --from with a community sandbox name, the CLI: Resolves the name against the\nOpenShell Community repository. Pulls the Dockerfile, policy, skills, and any startup scripts. Builds the container image locally. Creates the sandbox with the bundled configuration applied. You end up with a running sandbox whose image, policy, and tooling are all\npreconfigured by the community package. Other Sources The --from flag also accepts: Local directory paths: Point to a directory on disk that contains a\nDockerfile and optional policy/skills: $ openshell sandbox create --from ./my-sandbox-dir\nContainer image references: Use an existing container image directly: $ openshell sandbox create --from my-registry.example.com/my-image:latest\nContribute a Community Sandbox Each community sandbox is a directory under sandboxes/ in the\nOpenShell Community repository\nAt minimum, a sandbox directory must contain: Dockerfile : Defines the container image README.md : Describes the sandbox and how to use it Optional files: policy.yaml : Default policy applied when the sandbox launches skills/ : Agent skill definitions bundled with the sandbox Startup scripts: Any scripts the Dockerfile or entrypoint invokes To contribute, fork the repository, add your sandbox directory, and open a pull\nrequest. Refer to the repository’s\nCONTRIBUTING.md\nfor submission guidelines. The community catalog is designed to grow. If you have built a sandbox that\nsupports a particular workflow (data processing, simulation, code review\nor 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 providers for credential management. Want to customize the sandbox policy? Write custom rules in policies","format":"text","summary":"Use pre-built sandboxes from the OpenShell Community catalog, or contribute your own.","headings":[{"text":"Community Sandboxes","level":1},{"text":"What Are Community Sandboxes","level":2},{"text":"Current Catalog","level":2},{"text":"Use a Community Sandbox","level":2},{"text":"Other Sources","level":3},{"text":"Contribute a Community Sandbox","level":2},{"text":"Next Steps","level":2}]}
\ No newline at end of file
+{"id":"sandboxes/community-sandboxes","title":"Community Sandboxes","url":"sandboxes/community-sandboxes.html","last_modified":"2026-03-12T23:38:42.409112+00:00","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.1.0"},"product":{"name":"OpenShell","version":"0.1.0"},"description":"Use pre-built sandboxes from the OpenShell Community catalog or contribute your own.","tags":["Community","Sandbox","Container Image","Open Source"],"topics":["Generative AI","Cybersecurity"],"content_type":"concept","learning_level":"technical_beginner","audience":["engineer","data_scientist"],"content":"Community Sandboxes Use pre-built sandboxes from the OpenShell Community catalog, or contribute your\nown. What Are Community Sandboxes Community sandboxes are ready-to-use environments published in the\nOpenShell Community repository\nEach sandbox bundles a Dockerfile, policy, optional skills, and startup scripts\ninto a single package that you can launch with one command. Current Catalog The following community sandboxes are available in the catalog. Sandbox Description base Foundational image with system tools and dev environment openclaw Open agent manipulation and control sdg Synthetic data generation workflows simulation General-purpose simulation sandboxes Use a Community Sandbox Launch a community sandbox by name with the --from flag: $ openshell sandbox create --from openclaw\nWhen you pass --from with a community sandbox name, the CLI: Resolves the name against the\nOpenShell Community repository. Pulls the Dockerfile, policy, skills, and any startup scripts. Builds the container image locally. Creates the sandbox with the bundled configuration applied. You end up with a running sandbox whose image, policy, and tooling are all\npreconfigured by the community package. Other Sources The --from flag also accepts: Local directory paths: Point to a directory on disk that contains a\nDockerfile and optional policy/skills: $ openshell sandbox create --from ./my-sandbox-dir\nContainer image references: Use an existing container image directly: $ openshell sandbox create --from my-registry.example.com/my-image:latest\nContribute a Community Sandbox Each community sandbox is a directory under sandboxes/ in the\nOpenShell Community repository\nAt minimum, a sandbox directory must contain: Dockerfile : Defines the container image README.md : Describes the sandbox and how to use it Optional files: policy.yaml : Default policy applied when the sandbox launches skills/ : Agent skill definitions bundled with the sandbox Startup scripts: Any scripts the Dockerfile or entrypoint invokes To contribute, fork the repository, add your sandbox directory, and open a pull\nrequest. Refer to the repository’s\nCONTRIBUTING.md\nfor submission guidelines. The community catalog is designed to grow. If you have built a sandbox that\nsupports a particular workflow (data processing, simulation, code review\nor 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 providers for credential management. Want to customize the sandbox policy? Write custom rules in policies","format":"text","summary":"Use pre-built sandboxes from the OpenShell Community catalog, or contribute your own.","headings":[{"text":"Community Sandboxes","level":1},{"text":"What Are Community Sandboxes","level":2},{"text":"Current Catalog","level":2},{"text":"Use a Community Sandbox","level":2},{"text":"Other Sources","level":3},{"text":"Contribute a Community Sandbox","level":2},{"text":"Next Steps","level":2}]}
\ No newline at end of file
diff --git a/pr-preview/pr-257/sandboxes/create-and-manage.html b/pr-preview/pr-257/sandboxes/create-and-manage.html
index 5f46f74d4..888a2e7ac 100644
--- a/pr-preview/pr-257/sandboxes/create-and-manage.html
+++ b/pr-preview/pr-257/sandboxes/create-and-manage.html
@@ -387,7 +387,7 @@
 <p aria-level="2" class="caption" role="heading"><span class="caption-text">Get Started</span></p>
 <ul class="nav bd-sidenav">
 <li class="toctree-l1"><a class="reference internal" href="../get-started/quickstart.html">Quickstart</a></li>
-<li class="toctree-l1"><a class="reference internal" href="../tutorials/github-sandbox.html">Tutorial: GitHub Policy Iteration</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../tutorials/github-sandbox.html">GitHub Policy Tutorial</a></li>
 </ul>
 <p aria-level="2" class="caption" role="heading"><span class="caption-text">Sandboxes</span></p>
 <ul class="current nav bd-sidenav">
diff --git a/pr-preview/pr-257/sandboxes/create-and-manage.json b/pr-preview/pr-257/sandboxes/create-and-manage.json
index c12f2eae8..1bce45621 100644
--- a/pr-preview/pr-257/sandboxes/create-and-manage.json
+++ b/pr-preview/pr-257/sandboxes/create-and-manage.json
@@ -1 +1 @@
-{"id":"sandboxes/create-and-manage","title":"Create and Manage Sandboxes","url":"sandboxes/create-and-manage.html","last_modified":"2026-03-12T09:12:26.630029+00:00","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.1.0"},"product":{"name":"OpenShell","version":"0.1.0"},"description":"Create, inspect, connect to, monitor, transfer files, and delete OpenShell sandboxes.","tags":["Sandboxing","AI Agents","Sandbox Management","CLI"],"topics":["Generative AI","Cybersecurity"],"content_type":"how_to","learning_level":"technical_beginner","audience":["engineer","data_scientist"],"content":"Create and Manage Sandboxes 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 . Docker must be running before you create a sandbox. If it is not, the CLI\nreturns a connection-refused error ( os error 61 ) without explaining\nthe cause. Start Docker and try again. Create a Sandbox Run a single command to create a sandbox and launch your agent: $ openshell sandbox create -- claude\nIf you have an existing gateway, the sandbox is created in it. Otherwise, a gateway is created automatically. To request GPU resources explicitly, add --gpu : $ openshell sandbox create --gpu -- claude\nIf no gateway is running, the auto-bootstrap path starts a GPU-enabled gateway first. A fully specified creation command might look like: $ openshell sandbox create\nname dev\nprovider my-claude\npolicy policy.yaml\nupload\nkeep\nclaude\nUse --keep to keep the sandbox running after the trailing command exits\nThis is especially useful when you are iterating on a policy or want to\nreconnect later from another terminal or VS Code. Create from a Community Sandbox or Custom Image Use --from to create a sandbox from a pre-built community package, a local directory, or a container image: $ openshell sandbox create --from openclaw\nThe CLI resolves the name against the OpenShell Community catalog, pulls the bundled Dockerfile and policy, builds the image locally, and creates the sandbox. For the full catalog and how to contribute your own, refer to community-sandboxes . You can also point --from at a local directory or a container image reference: $ openshell sandbox create --from ./my-sandbox-dir\nopenshell sandbox create --from my-registry.example.com/my-image:latest\nImages whose final name component contains gpu also trigger GPU sandbox requests automatically. For example, --from nvidia-gpu behaves like a GPU sandbox request even without --gpu . List and Inspect Sandboxes Check the status of your sandboxes and retrieve detailed information about individual ones. List all sandboxes: $ openshell sandbox list\nGet detailed information about a specific sandbox: $ openshell sandbox get my-sandbox\nConnect to a Sandbox Access a running sandbox through an interactive SSH session or VS Code Remote-SSH. Interactive SSH Open an SSH session into a running sandbox: $ openshell sandbox connect my-sandbox\nOpen in a remote editor Launch VS Code or Cursor directly into the sandbox workspace: $ openshell sandbox create --editor vscode --name my-sandbox\nopenshell sandbox connect my-sandbox --editor cursor\nWhen --editor is used, OpenShell keeps the sandbox alive and installs an\nOpenShell-managed SSH include file instead of cluttering your main\nssh/config with generated host blocks. View Logs Stream and filter sandbox logs to monitor agent activity and diagnose policy decisions. Stream sandbox logs: $ openshell logs my-sandbox\nUse flags to filter and follow output: Flag Purpose Example --tail Stream logs in real time openshell logs my-sandbox --tail --source Filter by log source --source sandbox --level Filter by severity --level warn --since Show logs from a time window --since 5m Monitor Your Sandbox OpenShell Terminal is a real-time dashboard that combines sandbox status and live logs in a single view. $ openshell term\nThe dashboard shows the following information. 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 policies for the workflow. Transfer Files Transfer files between your host machine and a running sandbox. Upload files from your host into the sandbox: $ openshell sandbox upload my-sandbox ./src /sandbox/src\nDownload files from the sandbox to your host: $ openshell sandbox download my-sandbox /sandbox/output ./local\nYou can also upload files at creation time with the --upload flag on\nopenshell sandbox create . Delete Sandboxes Remove sandboxes when they are no longer needed. Deleting a sandbox stops all processes, releases cluster resources, and purges injected credentials. Delete a sandbox by name: $ openshell sandbox delete my-sandbox\nDelete all sandboxes in the active gateway: $ openshell sandbox delete --all\nNext Steps Explore related topics: To follow a complete end-to-end example, refer to the /tutorials/github-sandbox tutorial. To supply API keys or tokens, refer to providers . To control what the agent can access, refer to policies . To use a pre-built environment, refer to the community-sandboxes catalog","format":"text","summary":"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.","headings":[{"text":"Create and Manage Sandboxes","level":1},{"text":"Create a Sandbox","level":2},{"text":"Create from a Community Sandbox or Custom Image","level":2},{"text":"List and Inspect Sandboxes","level":2},{"text":"Connect to a Sandbox","level":2},{"text":"Interactive SSH","level":3},{"text":"Open in a remote editor","level":3},{"text":"View Logs","level":2},{"text":"Monitor Your Sandbox","level":2},{"text":"Transfer Files","level":2},{"text":"Delete Sandboxes","level":2},{"text":"Next Steps","level":2}]}
\ No newline at end of file
+{"id":"sandboxes/create-and-manage","title":"Create and Manage Sandboxes","url":"sandboxes/create-and-manage.html","last_modified":"2026-03-12T23:38:42.399009+00:00","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.1.0"},"product":{"name":"OpenShell","version":"0.1.0"},"description":"Create, inspect, connect to, monitor, transfer files, and delete OpenShell sandboxes.","tags":["Sandboxing","AI Agents","Sandbox Management","CLI"],"topics":["Generative AI","Cybersecurity"],"content_type":"how_to","learning_level":"technical_beginner","audience":["engineer","data_scientist"],"content":"Create and Manage Sandboxes 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 . Docker must be running before you create a sandbox. If it is not, the CLI\nreturns a connection-refused error ( os error 61 ) without explaining\nthe cause. Start Docker and try again. Create a Sandbox Run a single command to create a sandbox and launch your agent: $ openshell sandbox create -- claude\nIf you have an existing gateway, the sandbox is created in it. Otherwise, a gateway is created automatically. To request GPU resources explicitly, add --gpu : $ openshell sandbox create --gpu -- claude\nIf no gateway is running, the auto-bootstrap path starts a GPU-enabled gateway first. A fully specified creation command might look like: $ openshell sandbox create\nname dev\nprovider my-claude\npolicy policy.yaml\nupload\nkeep\nclaude\nUse --keep to keep the sandbox running after the trailing command exits\nThis is especially useful when you are iterating on a policy or want to\nreconnect later from another terminal or VS Code. Create from a Community Sandbox or Custom Image Use --from to create a sandbox from a pre-built community package, a local directory, or a container image: $ openshell sandbox create --from openclaw\nThe CLI resolves the name against the OpenShell Community catalog, pulls the bundled Dockerfile and policy, builds the image locally, and creates the sandbox. For the full catalog and how to contribute your own, refer to community-sandboxes . You can also point --from at a local directory or a container image reference: $ openshell sandbox create --from ./my-sandbox-dir\nopenshell sandbox create --from my-registry.example.com/my-image:latest\nImages whose final name component contains gpu also trigger GPU sandbox requests automatically. For example, --from nvidia-gpu behaves like a GPU sandbox request even without --gpu . List and Inspect Sandboxes Check the status of your sandboxes and retrieve detailed information about individual ones. List all sandboxes: $ openshell sandbox list\nGet detailed information about a specific sandbox: $ openshell sandbox get my-sandbox\nConnect to a Sandbox Access a running sandbox through an interactive SSH session or VS Code Remote-SSH. Interactive SSH Open an SSH session into a running sandbox: $ openshell sandbox connect my-sandbox\nOpen in a remote editor Launch VS Code or Cursor directly into the sandbox workspace: $ openshell sandbox create --editor vscode --name my-sandbox\nopenshell sandbox connect my-sandbox --editor cursor\nWhen --editor is used, OpenShell keeps the sandbox alive and installs an\nOpenShell-managed SSH include file instead of cluttering your main\nssh/config with generated host blocks. View Logs Stream and filter sandbox logs to monitor agent activity and diagnose policy decisions. Stream sandbox logs: $ openshell logs my-sandbox\nUse flags to filter and follow output: Flag Purpose Example --tail Stream logs in real time openshell logs my-sandbox --tail --source Filter by log source --source sandbox --level Filter by severity --level warn --since Show logs from a time window --since 5m Monitor Your Sandbox OpenShell Terminal is a real-time dashboard that combines sandbox status and live logs in a single view. $ openshell term\nThe dashboard shows the following information. 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 policies for the workflow. Transfer Files Transfer files between your host machine and a running sandbox. Upload files from your host into the sandbox: $ openshell sandbox upload my-sandbox ./src /sandbox/src\nDownload files from the sandbox to your host: $ openshell sandbox download my-sandbox /sandbox/output ./local\nYou can also upload files at creation time with the --upload flag on\nopenshell sandbox create . Delete Sandboxes Remove sandboxes when they are no longer needed. Deleting a sandbox stops all processes, releases cluster resources, and purges injected credentials. Delete a sandbox by name: $ openshell sandbox delete my-sandbox\nDelete all sandboxes in the active gateway: $ openshell sandbox delete --all\nNext Steps Explore related topics: To follow a complete end-to-end example, refer to the /tutorials/github-sandbox tutorial. To supply API keys or tokens, refer to providers . To control what the agent can access, refer to policies . To use a pre-built environment, refer to the community-sandboxes catalog","format":"text","summary":"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.","headings":[{"text":"Create and Manage Sandboxes","level":1},{"text":"Create a Sandbox","level":2},{"text":"Create from a Community Sandbox or Custom Image","level":2},{"text":"List and Inspect Sandboxes","level":2},{"text":"Connect to a Sandbox","level":2},{"text":"Interactive SSH","level":3},{"text":"Open in a remote editor","level":3},{"text":"View Logs","level":2},{"text":"Monitor Your Sandbox","level":2},{"text":"Transfer Files","level":2},{"text":"Delete Sandboxes","level":2},{"text":"Next Steps","level":2}]}
\ No newline at end of file
diff --git a/pr-preview/pr-257/sandboxes/index.html b/pr-preview/pr-257/sandboxes/index.html
index 8c8750684..3b126efeb 100644
--- a/pr-preview/pr-257/sandboxes/index.html
+++ b/pr-preview/pr-257/sandboxes/index.html
@@ -387,7 +387,7 @@
 <p aria-level="2" class="caption" role="heading"><span class="caption-text">Get Started</span></p>
 <ul class="nav bd-sidenav">
 <li class="toctree-l1"><a class="reference internal" href="../get-started/quickstart.html">Quickstart</a></li>
-<li class="toctree-l1"><a class="reference internal" href="../tutorials/github-sandbox.html">Tutorial: GitHub Policy Iteration</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../tutorials/github-sandbox.html">GitHub Policy Tutorial</a></li>
 </ul>
 <p aria-level="2" class="caption" role="heading"><span class="caption-text">Sandboxes</span></p>
 <ul class="current nav bd-sidenav">
diff --git a/pr-preview/pr-257/sandboxes/index.json b/pr-preview/pr-257/sandboxes/index.json
index 896be7813..c0d519826 100644
--- a/pr-preview/pr-257/sandboxes/index.json
+++ b/pr-preview/pr-257/sandboxes/index.json
@@ -1 +1 @@
-{"id":"sandboxes/index","title":"About Sandboxes","url":"sandboxes/index.html","last_modified":"2026-03-12T09:12:26.664376+00:00","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.1.0"},"product":{"name":"OpenShell","version":"0.1.0"},"description":"Understand sandbox lifecycle, supported agents, built-in default policy, and network access rules in OpenShell.","tags":["Sandboxing","AI Agents","Security","Policy","Isolation"],"topics":["Generative AI","Cybersecurity"],"content_type":"concept","learning_level":"technical_beginner","audience":["engineer","data_scientist"],"content":"About Sandboxes An OpenShell sandbox is a safe, private execution environment for an AI agent. Each sandbox runs with multiple layers of protection that prevent unauthorized data access, credential exposure, and network exfiltration. Protection layers include filesystem restrictions (Landlock), system call filtering (seccomp), network namespace isolation, and a privacy-enforcing HTTP CONNECT proxy. Sandbox Lifecycle Every sandbox moves through a defined set of phases: Phase Description Provisioning The runtime is setting up the sandbox environment, injecting credentials, and applying your policy. Ready The sandbox is running. The agent process is active and all isolation layers are enforced. You can connect, sync files, and view logs. 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 community-sandboxes catalog. Agent Source Default Policy Notes Claude Code Built-in Full coverage Works out of the box. Requires ANTHROPIC_API_KEY . OpenCode Built-in Partial coverage Pre-installed. Add opencode.ai endpoint and OpenCode binary paths to the policy for full functionality. Codex Built-in No coverage Pre-installed. Requires a custom policy with OpenAI endpoints and Codex binary paths. Requires OPENAI_API_KEY . OpenClaw OpenShell Community Bundled Agent orchestration layer. Launch with openshell sandbox create --from openclaw\nBuilt-in Default Policy OpenShell ships a built-in policy that covers common agent workflows out of the box\nWhen you create a sandbox without --policy , the default policy is applied. It controls three things: Layer What It Controls How It Works Filesystem What the agent can access on disk Paths are split into read-only and read-write sets. Landlock LSM enforces these restrictions at the kernel level. 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, refer to ../reference/default-policy . Policy Structure A policy has static sections ( filesystem_policy , landlock , process ) that are locked at sandbox creation, and dynamic sections ( network_policies , inference ) that are hot-reloadable on a running sandbox. version: 1\nStatic: locked at sandbox creation. Paths the agent can read vs read/write\nfilesystem_policy\nread_only: [/usr, /lib, /etc\nread_write: [/sandbox, /tmp\nStatic: Landlock LSM kernel enforcement. best_effort uses highest ABI the host supports\nlandlock\ncompatibility: best_effort\nStatic: Unprivileged user/group the agent process runs as\nprocess\nrun_as_user: sandbox\nrun_as_group: sandbox\nDynamic: hot-reloadable. Named blocks of endpoints + binaries allowed to reach them\nnetwork_policies\nmy_api\nname: my-api\nendpoints\nhost: api.example.com\nport: 443\nprotocol: rest\ntls: terminate\nenforcement: enforce\naccess: full\nbinaries\npath: /usr/bin/curl\nDynamic: hot-reloadable. Routing hints this sandbox can use for inference (e.g. local, nvidia\ninference\nallowed_routes: [local\nFor the complete structure and every field, refer to the Policy Schema Reference . 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. Every outbound connection from the sandbox goes through the proxy: The proxy queries the policy engine 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 Continue with one of the following: To create your first sandbox, refer to create-and-manage . To supply API keys or tokens, refer to providers . To control what the agent can access, refer to policies . To use a pre-built environment, refer to the community-sandboxes catalog","format":"text","summary":"An OpenShell sandbox is a safe, private execution environment for an AI agent. Each sandbox runs with multiple layers of protection that prevent unauthorized data access, credential exposure, and network exfiltration. Protection layers include filesystem restrictions (Landlock), system call filte...","headings":[{"text":"About Sandboxes","level":1},{"text":"Sandbox Lifecycle","level":2},{"text":"Supported Agents","level":2},{"text":"Built-in Default Policy","level":2},{"text":"Policy Structure","level":2},{"text":"Network Access Rules","level":2},{"text":"Next Steps","level":2}],"children":[{"id":"sandboxes/community-sandboxes","title":"Community Sandboxes","url":"sandboxes/community-sandboxes.html","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.1.0"},"product":{"name":"OpenShell","version":"0.1.0"},"description":"Use pre-built sandboxes from the OpenShell Community catalog or contribute your own.","tags":["Community","Sandbox","Container Image","Open Source"],"topics":["Generative AI","Cybersecurity"],"content_type":"concept","learning_level":"technical_beginner","audience":["engineer","data_scientist"],"content":"Community Sandboxes Use pre-built sandboxes from the OpenShell Community catalog, or contribute your\nown. What Are Community Sandboxes Community sandboxes are ready-to-use environments published in the\nOpenShell Community repository\nEach sandbox bundles a Dockerfile, policy, optional skills, and startup scripts\ninto a single package that you can launch with one command. Current Catalog The following community sandboxes are available in the catalog. Sandbox Description base Foundational image with system tools and dev environment openclaw Open agent manipulation and control sdg Synthetic data generation workflows simulation General-purpose simulation sandboxes Use a Community Sandbox Launch a community sandbox by name with the --from flag: $ openshell sandbox create --from openclaw\nWhen you pass --from with a community sandbox name, the CLI: Resolves the name against the\nOpenShell Community repository. Pulls the Dockerfile, policy, skills, and any startup scripts. Builds the container image locally. Creates the sandbox with the bundled configuration applied. You end up with a running sandbox whose image, policy, and tooling are all\npreconfigured by the community package. Other Sources The --from flag also accepts: Local directory paths: Point to a directory on disk that contains a\nDockerfile and optional policy/skills: $ openshell sandbox create --from ./my-sandbox-dir\nContainer image references: Use an existing container image directly: $ openshell sandbox create --from my-registry.example.com/my-image:latest\nContribute a Community Sandbox Each community sandbox is a directory under sandboxes/ in the\nOpenShell Community repository\nAt minimum, a sandbox directory must contain: Dockerfile : Defines the container image README.md : Describes the sandbox and how to use it Optional files: policy.yaml : Default policy applied when the sandbox launches skills/ : Agent skill definitions bundled with the sandbox Startup scripts: Any scripts the Dockerfile or entrypoint invokes To contribute, fork the repository, add your sandbox directory, and open a pull\nrequest. Refer to the repository’s\nCONTRIBUTING.md\nfor submission guidelines. The community catalog is designed to grow. If you have built a sandbox that\nsupports a particular workflow (data processing, simulation, code review\nor 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 providers for credential management. Want to customize the sandbox policy? Write custom rules in policies","format":"text","content_length":2562,"word_count":367,"summary":"Use pre-built sandboxes from the OpenShell Community catalog, or contribute your own.","headings":[{"text":"Community Sandboxes","level":1,"id":"community-sandboxes"},{"text":"What Are Community Sandboxes","level":2,"id":"what-are-community-sandboxes"},{"text":"Current Catalog","level":2,"id":"current-catalog"},{"text":"Use a Community Sandbox","level":2,"id":"use-a-community-sandbox"},{"text":"Other Sources","level":3,"id":"other-sources"},{"text":"Contribute a Community Sandbox","level":2,"id":"contribute-a-community-sandbox"},{"text":"Next Steps","level":2,"id":"next-steps"}],"headings_text":"Community Sandboxes What Are Community Sandboxes Current Catalog Use a Community Sandbox Other Sources Contribute a Community Sandbox Next Steps","keywords":["accepts","agent","any","builds","catalog","com","community","contain","container","contribute","creates","current","default","defines","describes","description","directly","dockerfile","each","explore","files","flag","foundational","general","image","launch","local","need","next","open","openshell","optional","other","paths","point","pulls","refer","references","resolves","sandbox","sandboxes","scripts","set","skills","sources","startup","steps","synthetic","topics","want"],"code_blocks":[{"content":"$ openshell sandbox create --from openclaw","language":"text"},{"content":"$ openshell sandbox create --from ./my-sandbox-dir","language":"text"},{"content":"$ openshell sandbox create --from my-registry.example.com/my-image:latest","language":"text"}],"links":[{"text":"OpenShell Community","type":"external","url":"https://github.com/NVIDIA/OpenShell-Community"},{"text":"OpenShell Community","type":"external","url":"https://github.com/NVIDIA/OpenShell-Community"},{"text":"OpenShell Community","type":"external","url":"https://github.com/NVIDIA/OpenShell-Community"},{"text":"Contributing","type":"external","url":"https://github.com/NVIDIA/OpenShell-Community/blob/main/CONTRIBUTING.md","original_text":"CONTRIBUTING.md"}],"images":[],"doc_type":"tutorial","section_path":["Sandboxes","Community Sandboxes"]},{"id":"sandboxes/create-and-manage","title":"Create and Manage Sandboxes","url":"sandboxes/create-and-manage.html","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.1.0"},"product":{"name":"OpenShell","version":"0.1.0"},"description":"Create, inspect, connect to, monitor, transfer files, and delete OpenShell sandboxes.","tags":["Sandboxing","AI Agents","Sandbox Management","CLI"],"topics":["Generative AI","Cybersecurity"],"content_type":"how_to","learning_level":"technical_beginner","audience":["engineer","data_scientist"],"content":"Create and Manage Sandboxes 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 . Docker must be running before you create a sandbox. If it is not, the CLI\nreturns a connection-refused error ( os error 61 ) without explaining\nthe cause. Start Docker and try again. Create a Sandbox Run a single command to create a sandbox and launch your agent: $ openshell sandbox create -- claude\nIf you have an existing gateway, the sandbox is created in it. Otherwise, a gateway is created automatically. To request GPU resources explicitly, add --gpu : $ openshell sandbox create --gpu -- claude\nIf no gateway is running, the auto-bootstrap path starts a GPU-enabled gateway first. A fully specified creation command might look like: $ openshell sandbox create\nname dev\nprovider my-claude\npolicy policy.yaml\nupload\nkeep\nclaude\nUse --keep to keep the sandbox running after the trailing command exits\nThis is especially useful when you are iterating on a policy or want to\nreconnect later from another terminal or VS Code. Create from a Community Sandbox or Custom Image Use --from to create a sandbox from a pre-built community package, a local directory, or a container image: $ openshell sandbox create --from openclaw\nThe CLI resolves the name against the OpenShell Community catalog, pulls the bundled Dockerfile and policy, builds the image locally, and creates the sandbox. For the full catalog and how to contribute your own, refer to community-sandboxes . You can also point --from at a local directory or a container image reference: $ openshell sandbox create --from ./my-sandbox-dir\nopenshell sandbox create --from my-registry.example.com/my-image:latest\nImages whose final name component contains gpu also trigger GPU sandbox requests automatically. For example, --from nvidia-gpu behaves like a GPU sandbox request even without --gpu . List and Inspect Sandboxes Check the status of your sandboxes and retrieve detailed information about individual ones. List all sandboxes: $ openshell sandbox list\nGet detailed information about a specific sandbox: $ openshell sandbox get my-sandbox\nConnect to a Sandbox Access a running sandbox through an interactive SSH session or VS Code Remote-SSH. Interactive SSH Open an SSH session into a running sandbox: $ openshell sandbox connect my-sandbox\nOpen in a remote editor Launch VS Code or Cursor directly into the sandbox workspace: $ openshell sandbox create --editor vscode --name my-sandbox\nopenshell sandbox connect my-sandbox --editor cursor\nWhen --editor is used, OpenShell keeps the sandbox alive and installs an\nOpenShell-managed SSH include file instead of cluttering your main\nssh/config with generated host blocks. View Logs Stream and filter sandbox logs to monitor agent activity and diagnose policy decisions. Stream sandbox logs: $ openshell logs my-sandbox\nUse flags to filter and follow output: Flag Purpose Example --tail Stream logs in real time openshell logs my-sandbox --tail --source Filter by log source --source sandbox --level Filter by severity --level warn --since Show logs from a time window --since 5m Monitor Your Sandbox OpenShell Terminal is a real-time dashboard that combines sandbox status and live logs in a single view. $ openshell term\nThe dashboard shows the following information. 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 policies for the workflow. Transfer Files Transfer files between your host machine and a running sandbox. Upload files from your host into the sandbox: $ openshell sandbox upload my-sandbox ./src /sandbox/src\nDownload files from the sandbox to your host: $ openshell sandbox download my-sandbox /sandbox/output ./local\nYou can also upload files at creation time with the --upload flag on\nopenshell sandbox create . Delete Sandboxes Remove sandboxes when they are no longer needed. Deleting a sandbox stops all processes, releases cluster resources, and purges injected credentials. Delete a sandbox by name: $ openshell sandbox delete my-sandbox\nDelete all sandboxes in the active gateway: $ openshell sandbox delete --all\nNext Steps Explore related topics: To follow a complete end-to-end example, refer to the /tutorials/github-sandbox tutorial. To supply API keys or tokens, refer to providers . To control what the agent can access, refer to policies . To use a pre-built environment, refer to the community-sandboxes catalog","format":"text","content_length":4970,"word_count":758,"summary":"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.","headings":[{"text":"Create and Manage Sandboxes","level":1,"id":"create-and-manage-sandboxes"},{"text":"Create a Sandbox","level":2,"id":"create-a-sandbox"},{"text":"Create from a Community Sandbox or Custom Image","level":2,"id":"create-from-a-community-sandbox-or-custom-image"},{"text":"List and Inspect Sandboxes","level":2,"id":"list-and-inspect-sandboxes"},{"text":"Connect to a Sandbox","level":2,"id":"connect-to-a-sandbox"},{"text":"Interactive SSH","level":3,"id":"interactive-ssh"},{"text":"Open in a remote editor","level":3,"id":"open-in-a-remote-editor"},{"text":"View Logs","level":2,"id":"view-logs"},{"text":"Monitor Your Sandbox","level":2,"id":"monitor-your-sandbox"},{"text":"Transfer Files","level":2,"id":"transfer-files"},{"text":"Delete Sandboxes","level":2,"id":"delete-sandboxes"},{"text":"Next Steps","level":2,"id":"next-steps"}],"headings_text":"Create and Manage Sandboxes Create a Sandbox Create from a Community Sandbox or Custom Image List and Inspect Sandboxes Connect to a Sandbox Interactive SSH Open in a remote editor View Logs Monitor Your Sandbox Transfer Files Delete Sandboxes Next Steps","keywords":["about","access","action","agent","check","code","com","community","connect","create","cursor","custom","delete","deleting","docker","dockerfile","download","editor","example","explore","files","filter","flag","from","gateway","gpu","host","image","images","inspect","interactive","launch","lifecycle","like","list","live","logs","manage","monitor","name","next","omutbound","open","openshell","otherwise","output","purpose","reference","remote","remove"],"code_blocks":[{"content":"$ openshell sandbox create -- claude","language":"text"},{"content":"$ openshell sandbox create --gpu -- claude","language":"text"},{"content":"$ openshell sandbox create \\\n    --name dev \\\n    --provider my-claude \\\n    --policy policy.yaml \\\n    --upload \\\n    --keep \\\n    -- claude","language":"text"},{"content":"$ openshell sandbox create --from openclaw","language":"text"},{"content":"$ openshell sandbox create --from ./my-sandbox-dir\n$ openshell sandbox create --from my-registry.example.com/my-image:latest","language":"text"},{"content":"$ openshell sandbox list","language":"text"},{"content":"$ openshell sandbox get my-sandbox","language":"text"},{"content":"$ openshell sandbox connect my-sandbox","language":"text"},{"content":"$ openshell sandbox create --editor vscode --name my-sandbox\n$ openshell sandbox connect my-sandbox --editor cursor","language":"text"},{"content":"$ openshell logs my-sandbox","language":"text"},{"content":"$ openshell term","language":"text"},{"content":"$ openshell sandbox upload my-sandbox ./src /sandbox/src","language":"text"},{"content":"$ openshell sandbox download my-sandbox /sandbox/output ./local","language":"text"},{"content":"$ openshell sandbox delete my-sandbox","language":"text"},{"content":"$ openshell sandbox delete --all","language":"text"}],"links":[{"text":"OpenShell Community","type":"external","url":"https://github.com/NVIDIA/OpenShell-Community"}],"images":[],"doc_type":"tutorial","section_path":["Sandboxes","Create And Manage"]},{"id":"sandboxes/policies","title":"Customize Sandbox Policies","url":"sandboxes/policies.html","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.1.0"},"product":{"name":"OpenShell","version":"0.1.0"},"description":"Apply, iterate, and debug sandbox network policies with hot-reload on running OpenShell sandboxes.","tags":["Policy","Network Policy","Sandbox","Security","Hot Reload"],"topics":["Generative AI","Cybersecurity"],"content_type":"how_to","learning_level":"technical_intermediate","audience":["engineer"],"content":"Customize Sandbox Policies Use this page to apply and iterate policy changes on running sandboxes. For a full field-by-field YAML definition, use the Policy Schema Reference . Quick Start: Apply a Custom Policy Pass a policy YAML file when creating the sandbox: $ openshell sandbox create --policy ./my-policy.yaml --keep -- claude\nThe --keep flag keeps the sandbox running after the initial command exits, which is useful when you plan to iterate on the policy. To avoid passing --policy every time, set a default policy with an environment variable: $ export OPENSHELL_SANDBOX_POLICY=./my-policy.yaml\nopenshell sandbox create --keep -- claude\nThe CLI uses the policy from OPENSHELL_SANDBOX_POLICY whenever --policy is not explicitly provided. Iterate on a Running Sandbox To change what the sandbox can access, pull the current policy, edit the YAML, and push the update. The workflow is iterative: create the sandbox, monitor logs for denied actions, pull the policy, modify it, push, and verify. The following steps outline the hot-reload policy update workflow. Create the sandbox with your initial policy by following Quick Start: Apply a Custom Policy above (or set OPENSHELL_SANDBOX_POLICY ). Monitor denials. Each log entry shows host, port, binary, and reason. Alternatively, use openshell term for a live dashboard. $ openshell logs <name> --tail --source sandbox\nPull the current policy. Strip the metadata header (Version, Hash, Status) before reusing the file. $ openshell policy get <name> --full > current-policy.yaml\nEdit the YAML: add or adjust network_policies entries, binaries, access or rules , or inference.allowed_routes . Push the updated policy. Exit codes: 0 = loaded, 1 = validation failed, 124 = timeout. $ openshell policy set <name> --policy current-policy.yaml --wait\nVerify the new revision. If status is loaded , repeat from step 2 as needed; if failed , fix the policy and repeat from step 4. $ openshell policy list <name\nDebug Denied Requests Check openshell logs <name> --tail --source sandbox for the denied host, path, and binary. When triaging denied requests, check: Destination host and port to confirm which endpoint is missing. Calling binary path to confirm which binaries entry needs to be added or adjusted. HTTP method and path (for REST endpoints) to confirm which rules entry needs to be added or adjusted. Then push the updated policy as described above. Examples Add these blocks to the network_policies section of your sandbox policy. Apply with openshell policy set <name> --policy <file> --wait\nUse Simple endpoint for host-level allowlists and Granular rules for method/path control. Simple endpoint Allow pip install and uv pip install to reach PyPI: pypi\nname: pypi\nendpoints\nhost: pypi.org\nport: 443\nhost: files.pythonhosted.org\nport: 443\nbinaries\n{ path: /usr/bin/pip\n{ path: /usr/local/bin/uv\nEndpoints without protocol or tls use TCP passthrough — the proxy allows the stream without inspecting payloads. Granular rules 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 <org_name> with your GitHub org or username. For an end-to-end walkthrough that combines this policy with a GitHub credential provider and sandbox creation, refer to /tutorials/github-sandbox . github_repos\nname: github_repos\nendpoints\nhost: api.github.com\nport: 443\nprotocol: rest\ntls: terminate\nenforcement: enforce\nrules\nallow\nmethod: GET\npath:\nallow\nmethod: HEAD\npath:\nallow\nmethod: OPTIONS\npath:\nallow\nmethod: POST\npath: \"/graphql\nallow\nmethod:\npath: \"/repos/<org_name>/alpha-repo\nallow\nmethod: POST\npath: \"/repos/<org_name>/bravo-repo/issues\nallow\nmethod: PATCH\npath: \"/repos/<org_name>/bravo-repo/issues\nbinaries\n{ path: /usr/local/bin/claude\n{ path: /usr/bin/gh\nEndpoints with protocol: rest and tls: terminate enable HTTP request inspection — the proxy decrypts TLS and checks each HTTP request against the rules list. Next Steps Explore related topics: To learn about policy structure and network access rules, refer to index . To view the full field-by-field YAML definition, refer to the Policy Schema Reference . To review the default policy breakdown, refer to ../reference/default-policy","format":"text","content_length":4315,"word_count":639,"summary":"Use this page to apply and iterate policy changes on running sandboxes. For a full field-by-field YAML definition, use the Policy Schema Reference.","headings":[{"text":"Customize Sandbox Policies","level":1,"id":"customize-sandbox-policies"},{"text":"Quick Start: Apply a Custom Policy","level":2,"id":"quick-start-apply-a-custom-policy"},{"text":"Iterate on a Running Sandbox","level":2,"id":"iterate-on-a-running-sandbox"},{"text":"Debug Denied Requests","level":2,"id":"debug-denied-requests"},{"text":"Examples","level":2,"id":"examples"},{"text":"Next Steps","level":2,"id":"next-steps"}],"headings_text":"Customize Sandbox Policies Quick Start: Apply a Custom Policy Iterate on a Running Sandbox Debug Denied Requests Examples Next Steps","keywords":["add","allow","alternatively","apply","calling","check","claude","codes","com","create","custom","customize","debug","denied","destination","each","edit","endpoints","enforcement","examples","exit","explore","github","granular","graphql","hash","host","iterate","iterative","method","monitor","name","next","org","pass","path","policies","policy","port","protocol","pull","push","pypi","quick","reference","replace","requests","rules","running","sandbox"],"code_blocks":[{"content":"$ openshell sandbox create --policy ./my-policy.yaml --keep -- claude","language":"text"},{"content":"$ export OPENSHELL_SANDBOX_POLICY=./my-policy.yaml\n$ openshell sandbox create --keep -- claude","language":"text"},{"content":"$ openshell logs <name> --tail --source sandbox","language":"text"},{"content":"$ openshell policy get <name> --full > current-policy.yaml","language":"text"},{"content":"$ openshell policy set <name> --policy current-policy.yaml --wait","language":"text"},{"content":"$ openshell policy list <name>","language":"text"},{"content":"pypi:\n    name: pypi\n    endpoints:\n      - host: pypi.org\n        port: 443\n      - host: files.pythonhosted.org\n        port: 443\n    binaries:\n      - { path: /usr/bin/pip }\n      - { path: /usr/local/bin/uv }","language":"text"},{"content":"github_repos:\n    name: github_repos\n    endpoints:\n      - host: api.github.com\n        port: 443\n        protocol: rest\n        tls: terminate\n        enforcement: enforce\n        rules:\n          - allow:\n              method: GET\n              path: \"/**\"\n          - allow:\n              method: HEAD\n              path: \"/**\"\n          - allow:\n              method: OPTIONS\n              path: \"/**\"\n          - allow:\n              method: POST\n              path: \"/graphql\"\n          - allow:\n              method: \"*\"\n              path: \"/repos/<org_name>/alpha-repo/**\"\n          - allow:\n              method: POST\n              path: \"/repos/<org_name>/bravo-repo/issues\"\n          - allow:\n              method: PATCH\n              path: \"/repos/<org_name>/bravo-repo/issues/*\"\n    binaries:\n      - { path: /usr/local/bin/claude }\n      - { path: /usr/bin/gh }","language":"text"}],"links":[{"text":"Quick Start: Apply a Custom Policy","type":"anchor","url":"#quick-start-apply-a-custom-policy"}],"images":[],"doc_type":"tutorial","section_path":["Sandboxes","Policies"]},{"id":"sandboxes/providers","title":"Providers","url":"sandboxes/providers.html","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.1.0"},"product":{"name":"OpenShell","version":"0.1.0"},"description":"Create and manage credential providers that inject API keys and tokens into OpenShell sandboxes.","tags":["Providers","Credentials","API Keys","Sandbox","Security"],"topics":["Generative AI","Cybersecurity"],"content_type":"how_to","learning_level":"technical_beginner","audience":["engineer","data_scientist"],"content":"Providers AI agents typically need credentials to access external services: an API key for the AI model provider, a token for GitHub or GitLab, and so on. OpenShell manages these credentials as first-class entities called providers . Create and manage providers that supply credentials to sandboxes. Create a Provider Providers can be created from local environment variables or with explicit credential values. From Local Credentials The fastest way to create a provider is to let the CLI discover credentials from\nyour shell environment: $ openshell provider create --name my-claude --type claude --from-existing\nThis reads ANTHROPIC_API_KEY or CLAUDE_API_KEY from your current environment\nand stores them in the provider. With Explicit Credentials Supply a credential value directly: $ openshell provider create --name my-api --type generic --credential API_KEY=sk-abc123\nBare Key Form Pass a key name without a value to read the value from the environment variable\nof that name: $ openshell provider create --name my-api --type generic --credential API_KEY\nThis looks up the current value of $API_KEY in your shell and stores it. Manage Providers List, inspect, update, and delete providers from the active cluster. List all providers: $ openshell provider list\nInspect a provider: $ openshell provider get my-claude\nUpdate a provider’s credentials: $ openshell provider update my-claude --type claude --from-existing\nDelete a provider: $ openshell provider delete my-claude\nAttach Providers to Sandboxes Pass one or more --provider flags when creating a sandbox: $ openshell sandbox create --provider my-claude --provider my-github -- claude\nEach --provider flag attaches one provider. The sandbox receives all\ncredentials from every attached provider at runtime. Providers cannot be added to a running sandbox. If you need to attach an\nadditional provider, delete the sandbox and recreate it with all required\nproviders specified. Auto-Discovery Shortcut When the trailing command in openshell sandbox create is a recognized tool name ( claude , codex , or opencode ), the CLI auto-creates the required\nprovider from your local credentials if one does not already exist. You do not\nneed to create the provider separately: $ openshell sandbox create -- claude\nThis detects claude as a known tool, finds your ANTHROPIC_API_KEY , creates\na provider, attaches it to the sandbox, and launches Claude Code. Supported Provider Types The following provider types are supported. Type Environment Variables Injected Typical Use 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 — refer to /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 outlook (none: no auto-discovery) Microsoft Outlook integration Use the generic type for any service not listed above. You define the\nenvironment variable names and values yourself with --credential . Next Steps Explore related topics: To control what the agent can access, refer to policies . To use a pre-built environment, refer to the community-sandboxes catalog. To view the complete field reference for the policy YAML, refer to the Policy Schema Reference","format":"text","content_length":3421,"word_count":502,"summary":"AI agents typically need credentials to access external services: an API key for the AI model provider, a token for GitHub or GitLab, and so on. OpenShell manages these credentials as first-class entities called providers.","headings":[{"text":"Providers","level":1,"id":"providers"},{"text":"Create a Provider","level":2,"id":"create-a-provider"},{"text":"From Local Credentials","level":3,"id":"from-local-credentials"},{"text":"With Explicit Credentials","level":3,"id":"with-explicit-credentials"},{"text":"Bare Key Form","level":3,"id":"bare-key-form"},{"text":"Manage Providers","level":2,"id":"manage-providers"},{"text":"Attach Providers to Sandboxes","level":2,"id":"attach-providers-to-sandboxes"},{"text":"Auto-Discovery Shortcut","level":3,"id":"auto-discovery-shortcut"},{"text":"Supported Provider Types","level":2,"id":"supported-provider-types"},{"text":"Next Steps","level":2,"id":"next-steps"}],"headings_text":"Providers Create a Provider From Local Credentials With Explicit Credentials Bare Key Form Manage Providers Attach Providers to Sandboxes Auto-Discovery Shortcut Supported Provider Types Next Steps","keywords":["anthropic","any","attach","auto","bare","catalog","claude","code","codex","create","credentials","delete","directly","discovery","each","environment","explicit","explore","form","from","github","gitlab","injected","inspect","key","list","local","manage","microsoft","name","next","none","openai","openshell","outlook","pass","policy","provider","providers","reference","sandbox","sandboxes","schema","separately","services","shortcut","steps","supply","supported","this"],"code_blocks":[{"content":"$ openshell provider create --name my-claude --type claude --from-existing","language":"text"},{"content":"$ openshell provider create --name my-api --type generic --credential API_KEY=sk-abc123","language":"text"},{"content":"$ openshell provider create --name my-api --type generic --credential API_KEY","language":"text"},{"content":"$ openshell provider list","language":"text"},{"content":"$ openshell provider get my-claude","language":"text"},{"content":"$ openshell provider update my-claude --type claude --from-existing","language":"text"},{"content":"$ openshell provider delete my-claude","language":"text"},{"content":"$ openshell sandbox create --provider my-claude --provider my-github -- claude","language":"text"},{"content":"$ openshell sandbox create -- claude","language":"text"}],"links":[],"images":[],"doc_type":"tutorial","section_path":["Sandboxes","Providers"]}]}
\ No newline at end of file
+{"id":"sandboxes/index","title":"About Sandboxes","url":"sandboxes/index.html","last_modified":"2026-03-12T23:38:42.405946+00:00","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.1.0"},"product":{"name":"OpenShell","version":"0.1.0"},"description":"Understand sandbox lifecycle, supported agents, built-in default policy, and network access rules in OpenShell.","tags":["Sandboxing","AI Agents","Security","Policy","Isolation"],"topics":["Generative AI","Cybersecurity"],"content_type":"concept","learning_level":"technical_beginner","audience":["engineer","data_scientist"],"content":"About Sandboxes An OpenShell sandbox is a safe, private execution environment for an AI agent. Each sandbox runs with multiple layers of protection that prevent unauthorized data access, credential exposure, and network exfiltration. Protection layers include filesystem restrictions (Landlock), system call filtering (seccomp), network namespace isolation, and a privacy-enforcing HTTP CONNECT proxy. Sandbox Lifecycle Every sandbox moves through a defined set of phases: Phase Description Provisioning The runtime is setting up the sandbox environment, injecting credentials, and applying your policy. Ready The sandbox is running. The agent process is active and all isolation layers are enforced. You can connect, sync files, and view logs. 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 community-sandboxes catalog. Agent Source Default Policy Notes Claude Code Built-in Full coverage Works out of the box. Requires ANTHROPIC_API_KEY . OpenCode Built-in Partial coverage Pre-installed. Add opencode.ai endpoint and OpenCode binary paths to the policy for full functionality. Codex Built-in No coverage Pre-installed. Requires a custom policy with OpenAI endpoints and Codex binary paths. Requires OPENAI_API_KEY . OpenClaw OpenShell Community Bundled Agent orchestration layer. Launch with openshell sandbox create --from openclaw\nBuilt-in Default Policy OpenShell ships a built-in policy that covers common agent workflows out of the box\nWhen you create a sandbox without --policy , the default policy is applied. It controls three things: Layer What It Controls How It Works Filesystem What the agent can access on disk Paths are split into read-only and read-write sets. Landlock LSM enforces these restrictions at the kernel level. 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, refer to ../reference/default-policy . Policy Structure A policy has static sections ( filesystem_policy , landlock , process ) that are locked at sandbox creation, and dynamic sections ( network_policies , inference ) that are hot-reloadable on a running sandbox. version: 1\nStatic: locked at sandbox creation. Paths the agent can read vs read/write\nfilesystem_policy\nread_only: [/usr, /lib, /etc\nread_write: [/sandbox, /tmp\nStatic: Landlock LSM kernel enforcement. best_effort uses highest ABI the host supports\nlandlock\ncompatibility: best_effort\nStatic: Unprivileged user/group the agent process runs as\nprocess\nrun_as_user: sandbox\nrun_as_group: sandbox\nDynamic: hot-reloadable. Named blocks of endpoints + binaries allowed to reach them\nnetwork_policies\nmy_api\nname: my-api\nendpoints\nhost: api.example.com\nport: 443\nprotocol: rest\ntls: terminate\nenforcement: enforce\naccess: full\nbinaries\npath: /usr/bin/curl\nDynamic: hot-reloadable. Routing hints this sandbox can use for inference (e.g. local, nvidia\ninference\nallowed_routes: [local\nFor the complete structure and every field, refer to the Policy Schema Reference . 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. Every outbound connection from the sandbox goes through the proxy: The proxy queries the policy engine 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 Continue with one of the following: To create your first sandbox, refer to create-and-manage . To supply API keys or tokens, refer to providers . To control what the agent can access, refer to policies . To use a pre-built environment, refer to the community-sandboxes catalog","format":"text","summary":"An OpenShell sandbox is a safe, private execution environment for an AI agent. Each sandbox runs with multiple layers of protection that prevent unauthorized data access, credential exposure, and network exfiltration. Protection layers include filesystem restrictions (Landlock), system call filte...","headings":[{"text":"About Sandboxes","level":1},{"text":"Sandbox Lifecycle","level":2},{"text":"Supported Agents","level":2},{"text":"Built-in Default Policy","level":2},{"text":"Policy Structure","level":2},{"text":"Network Access Rules","level":2},{"text":"Next Steps","level":2}],"children":[{"id":"sandboxes/community-sandboxes","title":"Community Sandboxes","url":"sandboxes/community-sandboxes.html","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.1.0"},"product":{"name":"OpenShell","version":"0.1.0"},"description":"Use pre-built sandboxes from the OpenShell Community catalog or contribute your own.","tags":["Community","Sandbox","Container Image","Open Source"],"topics":["Generative AI","Cybersecurity"],"content_type":"concept","learning_level":"technical_beginner","audience":["engineer","data_scientist"],"content":"Community Sandboxes Use pre-built sandboxes from the OpenShell Community catalog, or contribute your\nown. What Are Community Sandboxes Community sandboxes are ready-to-use environments published in the\nOpenShell Community repository\nEach sandbox bundles a Dockerfile, policy, optional skills, and startup scripts\ninto a single package that you can launch with one command. Current Catalog The following community sandboxes are available in the catalog. Sandbox Description base Foundational image with system tools and dev environment openclaw Open agent manipulation and control sdg Synthetic data generation workflows simulation General-purpose simulation sandboxes Use a Community Sandbox Launch a community sandbox by name with the --from flag: $ openshell sandbox create --from openclaw\nWhen you pass --from with a community sandbox name, the CLI: Resolves the name against the\nOpenShell Community repository. Pulls the Dockerfile, policy, skills, and any startup scripts. Builds the container image locally. Creates the sandbox with the bundled configuration applied. You end up with a running sandbox whose image, policy, and tooling are all\npreconfigured by the community package. Other Sources The --from flag also accepts: Local directory paths: Point to a directory on disk that contains a\nDockerfile and optional policy/skills: $ openshell sandbox create --from ./my-sandbox-dir\nContainer image references: Use an existing container image directly: $ openshell sandbox create --from my-registry.example.com/my-image:latest\nContribute a Community Sandbox Each community sandbox is a directory under sandboxes/ in the\nOpenShell Community repository\nAt minimum, a sandbox directory must contain: Dockerfile : Defines the container image README.md : Describes the sandbox and how to use it Optional files: policy.yaml : Default policy applied when the sandbox launches skills/ : Agent skill definitions bundled with the sandbox Startup scripts: Any scripts the Dockerfile or entrypoint invokes To contribute, fork the repository, add your sandbox directory, and open a pull\nrequest. Refer to the repository’s\nCONTRIBUTING.md\nfor submission guidelines. The community catalog is designed to grow. If you have built a sandbox that\nsupports a particular workflow (data processing, simulation, code review\nor 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 providers for credential management. Want to customize the sandbox policy? Write custom rules in policies","format":"text","content_length":2562,"word_count":367,"summary":"Use pre-built sandboxes from the OpenShell Community catalog, or contribute your own.","headings":[{"text":"Community Sandboxes","level":1,"id":"community-sandboxes"},{"text":"What Are Community Sandboxes","level":2,"id":"what-are-community-sandboxes"},{"text":"Current Catalog","level":2,"id":"current-catalog"},{"text":"Use a Community Sandbox","level":2,"id":"use-a-community-sandbox"},{"text":"Other Sources","level":3,"id":"other-sources"},{"text":"Contribute a Community Sandbox","level":2,"id":"contribute-a-community-sandbox"},{"text":"Next Steps","level":2,"id":"next-steps"}],"headings_text":"Community Sandboxes What Are Community Sandboxes Current Catalog Use a Community Sandbox Other Sources Contribute a Community Sandbox Next Steps","keywords":["accepts","agent","any","builds","catalog","com","community","contain","container","contribute","creates","current","default","defines","describes","description","directly","dockerfile","each","explore","files","flag","foundational","general","image","launch","local","need","next","open","openshell","optional","other","paths","point","pulls","refer","references","resolves","sandbox","sandboxes","scripts","set","skills","sources","startup","steps","synthetic","topics","want"],"code_blocks":[{"content":"$ openshell sandbox create --from openclaw","language":"text"},{"content":"$ openshell sandbox create --from ./my-sandbox-dir","language":"text"},{"content":"$ openshell sandbox create --from my-registry.example.com/my-image:latest","language":"text"}],"links":[{"text":"OpenShell Community","type":"external","url":"https://github.com/NVIDIA/OpenShell-Community"},{"text":"OpenShell Community","type":"external","url":"https://github.com/NVIDIA/OpenShell-Community"},{"text":"OpenShell Community","type":"external","url":"https://github.com/NVIDIA/OpenShell-Community"},{"text":"Contributing","type":"external","url":"https://github.com/NVIDIA/OpenShell-Community/blob/main/CONTRIBUTING.md","original_text":"CONTRIBUTING.md"}],"images":[],"doc_type":"tutorial","section_path":["Sandboxes","Community Sandboxes"]},{"id":"sandboxes/create-and-manage","title":"Create and Manage Sandboxes","url":"sandboxes/create-and-manage.html","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.1.0"},"product":{"name":"OpenShell","version":"0.1.0"},"description":"Create, inspect, connect to, monitor, transfer files, and delete OpenShell sandboxes.","tags":["Sandboxing","AI Agents","Sandbox Management","CLI"],"topics":["Generative AI","Cybersecurity"],"content_type":"how_to","learning_level":"technical_beginner","audience":["engineer","data_scientist"],"content":"Create and Manage Sandboxes 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 . Docker must be running before you create a sandbox. If it is not, the CLI\nreturns a connection-refused error ( os error 61 ) without explaining\nthe cause. Start Docker and try again. Create a Sandbox Run a single command to create a sandbox and launch your agent: $ openshell sandbox create -- claude\nIf you have an existing gateway, the sandbox is created in it. Otherwise, a gateway is created automatically. To request GPU resources explicitly, add --gpu : $ openshell sandbox create --gpu -- claude\nIf no gateway is running, the auto-bootstrap path starts a GPU-enabled gateway first. A fully specified creation command might look like: $ openshell sandbox create\nname dev\nprovider my-claude\npolicy policy.yaml\nupload\nkeep\nclaude\nUse --keep to keep the sandbox running after the trailing command exits\nThis is especially useful when you are iterating on a policy or want to\nreconnect later from another terminal or VS Code. Create from a Community Sandbox or Custom Image Use --from to create a sandbox from a pre-built community package, a local directory, or a container image: $ openshell sandbox create --from openclaw\nThe CLI resolves the name against the OpenShell Community catalog, pulls the bundled Dockerfile and policy, builds the image locally, and creates the sandbox. For the full catalog and how to contribute your own, refer to community-sandboxes . You can also point --from at a local directory or a container image reference: $ openshell sandbox create --from ./my-sandbox-dir\nopenshell sandbox create --from my-registry.example.com/my-image:latest\nImages whose final name component contains gpu also trigger GPU sandbox requests automatically. For example, --from nvidia-gpu behaves like a GPU sandbox request even without --gpu . List and Inspect Sandboxes Check the status of your sandboxes and retrieve detailed information about individual ones. List all sandboxes: $ openshell sandbox list\nGet detailed information about a specific sandbox: $ openshell sandbox get my-sandbox\nConnect to a Sandbox Access a running sandbox through an interactive SSH session or VS Code Remote-SSH. Interactive SSH Open an SSH session into a running sandbox: $ openshell sandbox connect my-sandbox\nOpen in a remote editor Launch VS Code or Cursor directly into the sandbox workspace: $ openshell sandbox create --editor vscode --name my-sandbox\nopenshell sandbox connect my-sandbox --editor cursor\nWhen --editor is used, OpenShell keeps the sandbox alive and installs an\nOpenShell-managed SSH include file instead of cluttering your main\nssh/config with generated host blocks. View Logs Stream and filter sandbox logs to monitor agent activity and diagnose policy decisions. Stream sandbox logs: $ openshell logs my-sandbox\nUse flags to filter and follow output: Flag Purpose Example --tail Stream logs in real time openshell logs my-sandbox --tail --source Filter by log source --source sandbox --level Filter by severity --level warn --since Show logs from a time window --since 5m Monitor Your Sandbox OpenShell Terminal is a real-time dashboard that combines sandbox status and live logs in a single view. $ openshell term\nThe dashboard shows the following information. 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 policies for the workflow. Transfer Files Transfer files between your host machine and a running sandbox. Upload files from your host into the sandbox: $ openshell sandbox upload my-sandbox ./src /sandbox/src\nDownload files from the sandbox to your host: $ openshell sandbox download my-sandbox /sandbox/output ./local\nYou can also upload files at creation time with the --upload flag on\nopenshell sandbox create . Delete Sandboxes Remove sandboxes when they are no longer needed. Deleting a sandbox stops all processes, releases cluster resources, and purges injected credentials. Delete a sandbox by name: $ openshell sandbox delete my-sandbox\nDelete all sandboxes in the active gateway: $ openshell sandbox delete --all\nNext Steps Explore related topics: To follow a complete end-to-end example, refer to the /tutorials/github-sandbox tutorial. To supply API keys or tokens, refer to providers . To control what the agent can access, refer to policies . To use a pre-built environment, refer to the community-sandboxes catalog","format":"text","content_length":4970,"word_count":758,"summary":"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.","headings":[{"text":"Create and Manage Sandboxes","level":1,"id":"create-and-manage-sandboxes"},{"text":"Create a Sandbox","level":2,"id":"create-a-sandbox"},{"text":"Create from a Community Sandbox or Custom Image","level":2,"id":"create-from-a-community-sandbox-or-custom-image"},{"text":"List and Inspect Sandboxes","level":2,"id":"list-and-inspect-sandboxes"},{"text":"Connect to a Sandbox","level":2,"id":"connect-to-a-sandbox"},{"text":"Interactive SSH","level":3,"id":"interactive-ssh"},{"text":"Open in a remote editor","level":3,"id":"open-in-a-remote-editor"},{"text":"View Logs","level":2,"id":"view-logs"},{"text":"Monitor Your Sandbox","level":2,"id":"monitor-your-sandbox"},{"text":"Transfer Files","level":2,"id":"transfer-files"},{"text":"Delete Sandboxes","level":2,"id":"delete-sandboxes"},{"text":"Next Steps","level":2,"id":"next-steps"}],"headings_text":"Create and Manage Sandboxes Create a Sandbox Create from a Community Sandbox or Custom Image List and Inspect Sandboxes Connect to a Sandbox Interactive SSH Open in a remote editor View Logs Monitor Your Sandbox Transfer Files Delete Sandboxes Next Steps","keywords":["about","access","action","agent","check","code","com","community","connect","create","cursor","custom","delete","deleting","docker","dockerfile","download","editor","example","explore","files","filter","flag","from","gateway","gpu","host","image","images","inspect","interactive","launch","lifecycle","like","list","live","logs","manage","monitor","name","next","omutbound","open","openshell","otherwise","output","purpose","reference","remote","remove"],"code_blocks":[{"content":"$ openshell sandbox create -- claude","language":"text"},{"content":"$ openshell sandbox create --gpu -- claude","language":"text"},{"content":"$ openshell sandbox create \\\n    --name dev \\\n    --provider my-claude \\\n    --policy policy.yaml \\\n    --upload \\\n    --keep \\\n    -- claude","language":"text"},{"content":"$ openshell sandbox create --from openclaw","language":"text"},{"content":"$ openshell sandbox create --from ./my-sandbox-dir\n$ openshell sandbox create --from my-registry.example.com/my-image:latest","language":"text"},{"content":"$ openshell sandbox list","language":"text"},{"content":"$ openshell sandbox get my-sandbox","language":"text"},{"content":"$ openshell sandbox connect my-sandbox","language":"text"},{"content":"$ openshell sandbox create --editor vscode --name my-sandbox\n$ openshell sandbox connect my-sandbox --editor cursor","language":"text"},{"content":"$ openshell logs my-sandbox","language":"text"},{"content":"$ openshell term","language":"text"},{"content":"$ openshell sandbox upload my-sandbox ./src /sandbox/src","language":"text"},{"content":"$ openshell sandbox download my-sandbox /sandbox/output ./local","language":"text"},{"content":"$ openshell sandbox delete my-sandbox","language":"text"},{"content":"$ openshell sandbox delete --all","language":"text"}],"links":[{"text":"OpenShell Community","type":"external","url":"https://github.com/NVIDIA/OpenShell-Community"}],"images":[],"doc_type":"tutorial","section_path":["Sandboxes","Create And Manage"]},{"id":"sandboxes/policies","title":"Customize Sandbox Policies","url":"sandboxes/policies.html","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.1.0"},"product":{"name":"OpenShell","version":"0.1.0"},"description":"Apply, iterate, and debug sandbox network policies with hot-reload on running OpenShell sandboxes.","tags":["Policy","Network Policy","Sandbox","Security","Hot Reload"],"topics":["Generative AI","Cybersecurity"],"content_type":"how_to","learning_level":"technical_intermediate","audience":["engineer"],"content":"Customize Sandbox Policies Use this page to apply and iterate policy changes on running sandboxes. For a full field-by-field YAML definition, use the Policy Schema Reference . Quick Start: Apply a Custom Policy Pass a policy YAML file when creating the sandbox: $ openshell sandbox create --policy ./my-policy.yaml --keep -- claude\nThe --keep flag keeps the sandbox running after the initial command exits, which is useful when you plan to iterate on the policy. To avoid passing --policy every time, set a default policy with an environment variable: $ export OPENSHELL_SANDBOX_POLICY=./my-policy.yaml\nopenshell sandbox create --keep -- claude\nThe CLI uses the policy from OPENSHELL_SANDBOX_POLICY whenever --policy is not explicitly provided. Iterate on a Running Sandbox To change what the sandbox can access, pull the current policy, edit the YAML, and push the update. The workflow is iterative: create the sandbox, monitor logs for denied actions, pull the policy, modify it, push, and verify. The following steps outline the hot-reload policy update workflow. Create the sandbox with your initial policy by following Quick Start: Apply a Custom Policy above (or set OPENSHELL_SANDBOX_POLICY ). Monitor denials. Each log entry shows host, port, binary, and reason. Alternatively, use openshell term for a live dashboard. $ openshell logs <name> --tail --source sandbox\nPull the current policy. Strip the metadata header (Version, Hash, Status) before reusing the file. $ openshell policy get <name> --full > current-policy.yaml\nEdit the YAML: add or adjust network_policies entries, binaries, access or rules , or inference.allowed_routes . Push the updated policy. Exit codes: 0 = loaded, 1 = validation failed, 124 = timeout. $ openshell policy set <name> --policy current-policy.yaml --wait\nVerify the new revision. If status is loaded , repeat from step 2 as needed; if failed , fix the policy and repeat from step 4. $ openshell policy list <name\nDebug Denied Requests Check openshell logs <name> --tail --source sandbox for the denied host, path, and binary. When triaging denied requests, check: Destination host and port to confirm which endpoint is missing. Calling binary path to confirm which binaries entry needs to be added or adjusted. HTTP method and path (for REST endpoints) to confirm which rules entry needs to be added or adjusted. Then push the updated policy as described above. Examples Add these blocks to the network_policies section of your sandbox policy. Apply with openshell policy set <name> --policy <file> --wait\nUse Simple endpoint for host-level allowlists and Granular rules for method/path control. Simple endpoint Allow pip install and uv pip install to reach PyPI: pypi\nname: pypi\nendpoints\nhost: pypi.org\nport: 443\nhost: files.pythonhosted.org\nport: 443\nbinaries\n{ path: /usr/bin/pip\n{ path: /usr/local/bin/uv\nEndpoints without protocol or tls use TCP passthrough — the proxy allows the stream without inspecting payloads. Granular rules 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 <org_name> with your GitHub org or username. For an end-to-end walkthrough that combines this policy with a GitHub credential provider and sandbox creation, refer to /tutorials/github-sandbox . github_repos\nname: github_repos\nendpoints\nhost: api.github.com\nport: 443\nprotocol: rest\ntls: terminate\nenforcement: enforce\nrules\nallow\nmethod: GET\npath:\nallow\nmethod: HEAD\npath:\nallow\nmethod: OPTIONS\npath:\nallow\nmethod: POST\npath: \"/graphql\nallow\nmethod:\npath: \"/repos/<org_name>/alpha-repo\nallow\nmethod: POST\npath: \"/repos/<org_name>/bravo-repo/issues\nallow\nmethod: PATCH\npath: \"/repos/<org_name>/bravo-repo/issues\nbinaries\n{ path: /usr/local/bin/claude\n{ path: /usr/bin/gh\nEndpoints with protocol: rest and tls: terminate enable HTTP request inspection — the proxy decrypts TLS and checks each HTTP request against the rules list. Next Steps Explore related topics: To learn about policy structure and network access rules, refer to index . To view the full field-by-field YAML definition, refer to the Policy Schema Reference . To review the default policy breakdown, refer to ../reference/default-policy","format":"text","content_length":4315,"word_count":639,"summary":"Use this page to apply and iterate policy changes on running sandboxes. For a full field-by-field YAML definition, use the Policy Schema Reference.","headings":[{"text":"Customize Sandbox Policies","level":1,"id":"customize-sandbox-policies"},{"text":"Quick Start: Apply a Custom Policy","level":2,"id":"quick-start-apply-a-custom-policy"},{"text":"Iterate on a Running Sandbox","level":2,"id":"iterate-on-a-running-sandbox"},{"text":"Debug Denied Requests","level":2,"id":"debug-denied-requests"},{"text":"Examples","level":2,"id":"examples"},{"text":"Next Steps","level":2,"id":"next-steps"}],"headings_text":"Customize Sandbox Policies Quick Start: Apply a Custom Policy Iterate on a Running Sandbox Debug Denied Requests Examples Next Steps","keywords":["add","allow","alternatively","apply","calling","check","claude","codes","com","create","custom","customize","debug","denied","destination","each","edit","endpoints","enforcement","examples","exit","explore","github","granular","graphql","hash","host","iterate","iterative","method","monitor","name","next","org","pass","path","policies","policy","port","protocol","pull","push","pypi","quick","reference","replace","requests","rules","running","sandbox"],"code_blocks":[{"content":"$ openshell sandbox create --policy ./my-policy.yaml --keep -- claude","language":"text"},{"content":"$ export OPENSHELL_SANDBOX_POLICY=./my-policy.yaml\n$ openshell sandbox create --keep -- claude","language":"text"},{"content":"$ openshell logs <name> --tail --source sandbox","language":"text"},{"content":"$ openshell policy get <name> --full > current-policy.yaml","language":"text"},{"content":"$ openshell policy set <name> --policy current-policy.yaml --wait","language":"text"},{"content":"$ openshell policy list <name>","language":"text"},{"content":"pypi:\n    name: pypi\n    endpoints:\n      - host: pypi.org\n        port: 443\n      - host: files.pythonhosted.org\n        port: 443\n    binaries:\n      - { path: /usr/bin/pip }\n      - { path: /usr/local/bin/uv }","language":"text"},{"content":"github_repos:\n    name: github_repos\n    endpoints:\n      - host: api.github.com\n        port: 443\n        protocol: rest\n        tls: terminate\n        enforcement: enforce\n        rules:\n          - allow:\n              method: GET\n              path: \"/**\"\n          - allow:\n              method: HEAD\n              path: \"/**\"\n          - allow:\n              method: OPTIONS\n              path: \"/**\"\n          - allow:\n              method: POST\n              path: \"/graphql\"\n          - allow:\n              method: \"*\"\n              path: \"/repos/<org_name>/alpha-repo/**\"\n          - allow:\n              method: POST\n              path: \"/repos/<org_name>/bravo-repo/issues\"\n          - allow:\n              method: PATCH\n              path: \"/repos/<org_name>/bravo-repo/issues/*\"\n    binaries:\n      - { path: /usr/local/bin/claude }\n      - { path: /usr/bin/gh }","language":"text"}],"links":[{"text":"Quick Start: Apply a Custom Policy","type":"anchor","url":"#quick-start-apply-a-custom-policy"}],"images":[],"doc_type":"tutorial","section_path":["Sandboxes","Policies"]},{"id":"sandboxes/providers","title":"Providers","url":"sandboxes/providers.html","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.1.0"},"product":{"name":"OpenShell","version":"0.1.0"},"description":"Create and manage credential providers that inject API keys and tokens into OpenShell sandboxes.","tags":["Providers","Credentials","API Keys","Sandbox","Security"],"topics":["Generative AI","Cybersecurity"],"content_type":"how_to","learning_level":"technical_beginner","audience":["engineer","data_scientist"],"content":"Providers AI agents typically need credentials to access external services: an API key for the AI model provider, a token for GitHub or GitLab, and so on. OpenShell manages these credentials as first-class entities called providers . Create and manage providers that supply credentials to sandboxes. Create a Provider Providers can be created from local environment variables or with explicit credential values. From Local Credentials The fastest way to create a provider is to let the CLI discover credentials from\nyour shell environment: $ openshell provider create --name my-claude --type claude --from-existing\nThis reads ANTHROPIC_API_KEY or CLAUDE_API_KEY from your current environment\nand stores them in the provider. With Explicit Credentials Supply a credential value directly: $ openshell provider create --name my-api --type generic --credential API_KEY=sk-abc123\nBare Key Form Pass a key name without a value to read the value from the environment variable\nof that name: $ openshell provider create --name my-api --type generic --credential API_KEY\nThis looks up the current value of $API_KEY in your shell and stores it. Manage Providers List, inspect, update, and delete providers from the active cluster. List all providers: $ openshell provider list\nInspect a provider: $ openshell provider get my-claude\nUpdate a provider’s credentials: $ openshell provider update my-claude --type claude --from-existing\nDelete a provider: $ openshell provider delete my-claude\nAttach Providers to Sandboxes Pass one or more --provider flags when creating a sandbox: $ openshell sandbox create --provider my-claude --provider my-github -- claude\nEach --provider flag attaches one provider. The sandbox receives all\ncredentials from every attached provider at runtime. Providers cannot be added to a running sandbox. If you need to attach an\nadditional provider, delete the sandbox and recreate it with all required\nproviders specified. Auto-Discovery Shortcut When the trailing command in openshell sandbox create is a recognized tool name ( claude , codex , or opencode ), the CLI auto-creates the required\nprovider from your local credentials if one does not already exist. You do not\nneed to create the provider separately: $ openshell sandbox create -- claude\nThis detects claude as a known tool, finds your ANTHROPIC_API_KEY , creates\na provider, attaches it to the sandbox, and launches Claude Code. Supported Provider Types The following provider types are supported. Type Environment Variables Injected Typical Use 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 — refer to /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 outlook (none: no auto-discovery) Microsoft Outlook integration Use the generic type for any service not listed above. You define the\nenvironment variable names and values yourself with --credential . Next Steps Explore related topics: To control what the agent can access, refer to policies . To use a pre-built environment, refer to the community-sandboxes catalog. To view the complete field reference for the policy YAML, refer to the Policy Schema Reference","format":"text","content_length":3421,"word_count":502,"summary":"AI agents typically need credentials to access external services: an API key for the AI model provider, a token for GitHub or GitLab, and so on. OpenShell manages these credentials as first-class entities called providers.","headings":[{"text":"Providers","level":1,"id":"providers"},{"text":"Create a Provider","level":2,"id":"create-a-provider"},{"text":"From Local Credentials","level":3,"id":"from-local-credentials"},{"text":"With Explicit Credentials","level":3,"id":"with-explicit-credentials"},{"text":"Bare Key Form","level":3,"id":"bare-key-form"},{"text":"Manage Providers","level":2,"id":"manage-providers"},{"text":"Attach Providers to Sandboxes","level":2,"id":"attach-providers-to-sandboxes"},{"text":"Auto-Discovery Shortcut","level":3,"id":"auto-discovery-shortcut"},{"text":"Supported Provider Types","level":2,"id":"supported-provider-types"},{"text":"Next Steps","level":2,"id":"next-steps"}],"headings_text":"Providers Create a Provider From Local Credentials With Explicit Credentials Bare Key Form Manage Providers Attach Providers to Sandboxes Auto-Discovery Shortcut Supported Provider Types Next Steps","keywords":["anthropic","any","attach","auto","bare","catalog","claude","code","codex","create","credentials","delete","directly","discovery","each","environment","explicit","explore","form","from","github","gitlab","injected","inspect","key","list","local","manage","microsoft","name","next","none","openai","openshell","outlook","pass","policy","provider","providers","reference","sandbox","sandboxes","schema","separately","services","shortcut","steps","supply","supported","this"],"code_blocks":[{"content":"$ openshell provider create --name my-claude --type claude --from-existing","language":"text"},{"content":"$ openshell provider create --name my-api --type generic --credential API_KEY=sk-abc123","language":"text"},{"content":"$ openshell provider create --name my-api --type generic --credential API_KEY","language":"text"},{"content":"$ openshell provider list","language":"text"},{"content":"$ openshell provider get my-claude","language":"text"},{"content":"$ openshell provider update my-claude --type claude --from-existing","language":"text"},{"content":"$ openshell provider delete my-claude","language":"text"},{"content":"$ openshell sandbox create --provider my-claude --provider my-github -- claude","language":"text"},{"content":"$ openshell sandbox create -- claude","language":"text"}],"links":[],"images":[],"doc_type":"tutorial","section_path":["Sandboxes","Providers"]}]}
\ No newline at end of file
diff --git a/pr-preview/pr-257/sandboxes/policies.html b/pr-preview/pr-257/sandboxes/policies.html
index 1d07b0131..6fce9b656 100644
--- a/pr-preview/pr-257/sandboxes/policies.html
+++ b/pr-preview/pr-257/sandboxes/policies.html
@@ -822,7 +822,7 @@ window.addEventListener("load", load);</script>
 <p aria-level="2" class="caption" role="heading"><span class="caption-text">Get Started</span></p>
 <ul class="nav bd-sidenav">
 <li class="toctree-l1"><a class="reference internal" href="../get-started/quickstart.html">Quickstart</a></li>
-<li class="toctree-l1"><a class="reference internal" href="../tutorials/github-sandbox.html">Tutorial: GitHub Policy Iteration</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../tutorials/github-sandbox.html">GitHub Policy Tutorial</a></li>
 </ul>
 <p aria-level="2" class="caption" role="heading"><span class="caption-text">Sandboxes</span></p>
 <ul class="current nav bd-sidenav">
diff --git a/pr-preview/pr-257/sandboxes/policies.json b/pr-preview/pr-257/sandboxes/policies.json
index 6125cc3fc..b2f740d26 100644
--- a/pr-preview/pr-257/sandboxes/policies.json
+++ b/pr-preview/pr-257/sandboxes/policies.json
@@ -1 +1 @@
-{"id":"sandboxes/policies","title":"Customize Sandbox Policies","url":"sandboxes/policies.html","last_modified":"2026-03-12T09:12:26.641004+00:00","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.1.0"},"product":{"name":"OpenShell","version":"0.1.0"},"description":"Apply, iterate, and debug sandbox network policies with hot-reload on running OpenShell sandboxes.","tags":["Policy","Network Policy","Sandbox","Security","Hot Reload"],"topics":["Generative AI","Cybersecurity"],"content_type":"how_to","learning_level":"technical_intermediate","audience":["engineer"],"content":"Customize Sandbox Policies Use this page to apply and iterate policy changes on running sandboxes. For a full field-by-field YAML definition, use the Policy Schema Reference . Quick Start: Apply a Custom Policy Pass a policy YAML file when creating the sandbox: $ openshell sandbox create --policy ./my-policy.yaml --keep -- claude\nThe --keep flag keeps the sandbox running after the initial command exits, which is useful when you plan to iterate on the policy. To avoid passing --policy every time, set a default policy with an environment variable: $ export OPENSHELL_SANDBOX_POLICY=./my-policy.yaml\nopenshell sandbox create --keep -- claude\nThe CLI uses the policy from OPENSHELL_SANDBOX_POLICY whenever --policy is not explicitly provided. Iterate on a Running Sandbox To change what the sandbox can access, pull the current policy, edit the YAML, and push the update. The workflow is iterative: create the sandbox, monitor logs for denied actions, pull the policy, modify it, push, and verify. The following steps outline the hot-reload policy update workflow. Create the sandbox with your initial policy by following Quick Start: Apply a Custom Policy above (or set OPENSHELL_SANDBOX_POLICY ). Monitor denials. Each log entry shows host, port, binary, and reason. Alternatively, use openshell term for a live dashboard. $ openshell logs <name> --tail --source sandbox\nPull the current policy. Strip the metadata header (Version, Hash, Status) before reusing the file. $ openshell policy get <name> --full > current-policy.yaml\nEdit the YAML: add or adjust network_policies entries, binaries, access or rules , or inference.allowed_routes . Push the updated policy. Exit codes: 0 = loaded, 1 = validation failed, 124 = timeout. $ openshell policy set <name> --policy current-policy.yaml --wait\nVerify the new revision. If status is loaded , repeat from step 2 as needed; if failed , fix the policy and repeat from step 4. $ openshell policy list <name\nDebug Denied Requests Check openshell logs <name> --tail --source sandbox for the denied host, path, and binary. When triaging denied requests, check: Destination host and port to confirm which endpoint is missing. Calling binary path to confirm which binaries entry needs to be added or adjusted. HTTP method and path (for REST endpoints) to confirm which rules entry needs to be added or adjusted. Then push the updated policy as described above. Examples Add these blocks to the network_policies section of your sandbox policy. Apply with openshell policy set <name> --policy <file> --wait\nUse Simple endpoint for host-level allowlists and Granular rules for method/path control. Simple endpoint Allow pip install and uv pip install to reach PyPI: pypi\nname: pypi\nendpoints\nhost: pypi.org\nport: 443\nhost: files.pythonhosted.org\nport: 443\nbinaries\n{ path: /usr/bin/pip\n{ path: /usr/local/bin/uv\nEndpoints without protocol or tls use TCP passthrough — the proxy allows the stream without inspecting payloads. Granular rules 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 <org_name> with your GitHub org or username. For an end-to-end walkthrough that combines this policy with a GitHub credential provider and sandbox creation, refer to /tutorials/github-sandbox . github_repos\nname: github_repos\nendpoints\nhost: api.github.com\nport: 443\nprotocol: rest\ntls: terminate\nenforcement: enforce\nrules\nallow\nmethod: GET\npath:\nallow\nmethod: HEAD\npath:\nallow\nmethod: OPTIONS\npath:\nallow\nmethod: POST\npath: \"/graphql\nallow\nmethod:\npath: \"/repos/<org_name>/alpha-repo\nallow\nmethod: POST\npath: \"/repos/<org_name>/bravo-repo/issues\nallow\nmethod: PATCH\npath: \"/repos/<org_name>/bravo-repo/issues\nbinaries\n{ path: /usr/local/bin/claude\n{ path: /usr/bin/gh\nEndpoints with protocol: rest and tls: terminate enable HTTP request inspection — the proxy decrypts TLS and checks each HTTP request against the rules list. Next Steps Explore related topics: To learn about policy structure and network access rules, refer to index . To view the full field-by-field YAML definition, refer to the Policy Schema Reference . To review the default policy breakdown, refer to ../reference/default-policy","format":"text","summary":"Use this page to apply and iterate policy changes on running sandboxes. For a full field-by-field YAML definition, use the Policy Schema Reference.","headings":[{"text":"Customize Sandbox Policies","level":1},{"text":"Quick Start: Apply a Custom Policy","level":2},{"text":"Iterate on a Running Sandbox","level":2},{"text":"Debug Denied Requests","level":2},{"text":"Examples","level":2},{"text":"Next Steps","level":2}]}
\ No newline at end of file
+{"id":"sandboxes/policies","title":"Customize Sandbox Policies","url":"sandboxes/policies.html","last_modified":"2026-03-12T23:38:42.414803+00:00","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.1.0"},"product":{"name":"OpenShell","version":"0.1.0"},"description":"Apply, iterate, and debug sandbox network policies with hot-reload on running OpenShell sandboxes.","tags":["Policy","Network Policy","Sandbox","Security","Hot Reload"],"topics":["Generative AI","Cybersecurity"],"content_type":"how_to","learning_level":"technical_intermediate","audience":["engineer"],"content":"Customize Sandbox Policies Use this page to apply and iterate policy changes on running sandboxes. For a full field-by-field YAML definition, use the Policy Schema Reference . Quick Start: Apply a Custom Policy Pass a policy YAML file when creating the sandbox: $ openshell sandbox create --policy ./my-policy.yaml --keep -- claude\nThe --keep flag keeps the sandbox running after the initial command exits, which is useful when you plan to iterate on the policy. To avoid passing --policy every time, set a default policy with an environment variable: $ export OPENSHELL_SANDBOX_POLICY=./my-policy.yaml\nopenshell sandbox create --keep -- claude\nThe CLI uses the policy from OPENSHELL_SANDBOX_POLICY whenever --policy is not explicitly provided. Iterate on a Running Sandbox To change what the sandbox can access, pull the current policy, edit the YAML, and push the update. The workflow is iterative: create the sandbox, monitor logs for denied actions, pull the policy, modify it, push, and verify. The following steps outline the hot-reload policy update workflow. Create the sandbox with your initial policy by following Quick Start: Apply a Custom Policy above (or set OPENSHELL_SANDBOX_POLICY ). Monitor denials. Each log entry shows host, port, binary, and reason. Alternatively, use openshell term for a live dashboard. $ openshell logs <name> --tail --source sandbox\nPull the current policy. Strip the metadata header (Version, Hash, Status) before reusing the file. $ openshell policy get <name> --full > current-policy.yaml\nEdit the YAML: add or adjust network_policies entries, binaries, access or rules , or inference.allowed_routes . Push the updated policy. Exit codes: 0 = loaded, 1 = validation failed, 124 = timeout. $ openshell policy set <name> --policy current-policy.yaml --wait\nVerify the new revision. If status is loaded , repeat from step 2 as needed; if failed , fix the policy and repeat from step 4. $ openshell policy list <name\nDebug Denied Requests Check openshell logs <name> --tail --source sandbox for the denied host, path, and binary. When triaging denied requests, check: Destination host and port to confirm which endpoint is missing. Calling binary path to confirm which binaries entry needs to be added or adjusted. HTTP method and path (for REST endpoints) to confirm which rules entry needs to be added or adjusted. Then push the updated policy as described above. Examples Add these blocks to the network_policies section of your sandbox policy. Apply with openshell policy set <name> --policy <file> --wait\nUse Simple endpoint for host-level allowlists and Granular rules for method/path control. Simple endpoint Allow pip install and uv pip install to reach PyPI: pypi\nname: pypi\nendpoints\nhost: pypi.org\nport: 443\nhost: files.pythonhosted.org\nport: 443\nbinaries\n{ path: /usr/bin/pip\n{ path: /usr/local/bin/uv\nEndpoints without protocol or tls use TCP passthrough — the proxy allows the stream without inspecting payloads. Granular rules 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 <org_name> with your GitHub org or username. For an end-to-end walkthrough that combines this policy with a GitHub credential provider and sandbox creation, refer to /tutorials/github-sandbox . github_repos\nname: github_repos\nendpoints\nhost: api.github.com\nport: 443\nprotocol: rest\ntls: terminate\nenforcement: enforce\nrules\nallow\nmethod: GET\npath:\nallow\nmethod: HEAD\npath:\nallow\nmethod: OPTIONS\npath:\nallow\nmethod: POST\npath: \"/graphql\nallow\nmethod:\npath: \"/repos/<org_name>/alpha-repo\nallow\nmethod: POST\npath: \"/repos/<org_name>/bravo-repo/issues\nallow\nmethod: PATCH\npath: \"/repos/<org_name>/bravo-repo/issues\nbinaries\n{ path: /usr/local/bin/claude\n{ path: /usr/bin/gh\nEndpoints with protocol: rest and tls: terminate enable HTTP request inspection — the proxy decrypts TLS and checks each HTTP request against the rules list. Next Steps Explore related topics: To learn about policy structure and network access rules, refer to index . To view the full field-by-field YAML definition, refer to the Policy Schema Reference . To review the default policy breakdown, refer to ../reference/default-policy","format":"text","summary":"Use this page to apply and iterate policy changes on running sandboxes. For a full field-by-field YAML definition, use the Policy Schema Reference.","headings":[{"text":"Customize Sandbox Policies","level":1},{"text":"Quick Start: Apply a Custom Policy","level":2},{"text":"Iterate on a Running Sandbox","level":2},{"text":"Debug Denied Requests","level":2},{"text":"Examples","level":2},{"text":"Next Steps","level":2}]}
\ No newline at end of file
diff --git a/pr-preview/pr-257/sandboxes/providers.html b/pr-preview/pr-257/sandboxes/providers.html
index 83ff90888..7f48c0eb9 100644
--- a/pr-preview/pr-257/sandboxes/providers.html
+++ b/pr-preview/pr-257/sandboxes/providers.html
@@ -387,7 +387,7 @@
 <p aria-level="2" class="caption" role="heading"><span class="caption-text">Get Started</span></p>
 <ul class="nav bd-sidenav">
 <li class="toctree-l1"><a class="reference internal" href="../get-started/quickstart.html">Quickstart</a></li>
-<li class="toctree-l1"><a class="reference internal" href="../tutorials/github-sandbox.html">Tutorial: GitHub Policy Iteration</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../tutorials/github-sandbox.html">GitHub Policy Tutorial</a></li>
 </ul>
 <p aria-level="2" class="caption" role="heading"><span class="caption-text">Sandboxes</span></p>
 <ul class="current nav bd-sidenav">
diff --git a/pr-preview/pr-257/sandboxes/providers.json b/pr-preview/pr-257/sandboxes/providers.json
index 29d847c51..2fd4e77ec 100644
--- a/pr-preview/pr-257/sandboxes/providers.json
+++ b/pr-preview/pr-257/sandboxes/providers.json
@@ -1 +1 @@
-{"id":"sandboxes/providers","title":"Providers","url":"sandboxes/providers.html","last_modified":"2026-03-12T09:12:26.656605+00:00","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.1.0"},"product":{"name":"OpenShell","version":"0.1.0"},"description":"Create and manage credential providers that inject API keys and tokens into OpenShell sandboxes.","tags":["Providers","Credentials","API Keys","Sandbox","Security"],"topics":["Generative AI","Cybersecurity"],"content_type":"how_to","learning_level":"technical_beginner","audience":["engineer","data_scientist"],"content":"Providers AI agents typically need credentials to access external services: an API key for the AI model provider, a token for GitHub or GitLab, and so on. OpenShell manages these credentials as first-class entities called providers . Create and manage providers that supply credentials to sandboxes. Create a Provider Providers can be created from local environment variables or with explicit credential values. From Local Credentials The fastest way to create a provider is to let the CLI discover credentials from\nyour shell environment: $ openshell provider create --name my-claude --type claude --from-existing\nThis reads ANTHROPIC_API_KEY or CLAUDE_API_KEY from your current environment\nand stores them in the provider. With Explicit Credentials Supply a credential value directly: $ openshell provider create --name my-api --type generic --credential API_KEY=sk-abc123\nBare Key Form Pass a key name without a value to read the value from the environment variable\nof that name: $ openshell provider create --name my-api --type generic --credential API_KEY\nThis looks up the current value of $API_KEY in your shell and stores it. Manage Providers List, inspect, update, and delete providers from the active cluster. List all providers: $ openshell provider list\nInspect a provider: $ openshell provider get my-claude\nUpdate a provider’s credentials: $ openshell provider update my-claude --type claude --from-existing\nDelete a provider: $ openshell provider delete my-claude\nAttach Providers to Sandboxes Pass one or more --provider flags when creating a sandbox: $ openshell sandbox create --provider my-claude --provider my-github -- claude\nEach --provider flag attaches one provider. The sandbox receives all\ncredentials from every attached provider at runtime. Providers cannot be added to a running sandbox. If you need to attach an\nadditional provider, delete the sandbox and recreate it with all required\nproviders specified. Auto-Discovery Shortcut When the trailing command in openshell sandbox create is a recognized tool name ( claude , codex , or opencode ), the CLI auto-creates the required\nprovider from your local credentials if one does not already exist. You do not\nneed to create the provider separately: $ openshell sandbox create -- claude\nThis detects claude as a known tool, finds your ANTHROPIC_API_KEY , creates\na provider, attaches it to the sandbox, and launches Claude Code. Supported Provider Types The following provider types are supported. Type Environment Variables Injected Typical Use 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 — refer to /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 outlook (none: no auto-discovery) Microsoft Outlook integration Use the generic type for any service not listed above. You define the\nenvironment variable names and values yourself with --credential . Next Steps Explore related topics: To control what the agent can access, refer to policies . To use a pre-built environment, refer to the community-sandboxes catalog. To view the complete field reference for the policy YAML, refer to the Policy Schema Reference","format":"text","summary":"AI agents typically need credentials to access external services: an API key for the AI model provider, a token for GitHub or GitLab, and so on. OpenShell manages these credentials as first-class entities called providers.","headings":[{"text":"Providers","level":1},{"text":"Create a Provider","level":2},{"text":"From Local Credentials","level":3},{"text":"With Explicit Credentials","level":3},{"text":"Bare Key Form","level":3},{"text":"Manage Providers","level":2},{"text":"Attach Providers to Sandboxes","level":2},{"text":"Auto-Discovery Shortcut","level":3},{"text":"Supported Provider Types","level":2},{"text":"Next Steps","level":2}]}
\ No newline at end of file
+{"id":"sandboxes/providers","title":"Providers","url":"sandboxes/providers.html","last_modified":"2026-03-12T23:38:42.422131+00:00","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.1.0"},"product":{"name":"OpenShell","version":"0.1.0"},"description":"Create and manage credential providers that inject API keys and tokens into OpenShell sandboxes.","tags":["Providers","Credentials","API Keys","Sandbox","Security"],"topics":["Generative AI","Cybersecurity"],"content_type":"how_to","learning_level":"technical_beginner","audience":["engineer","data_scientist"],"content":"Providers AI agents typically need credentials to access external services: an API key for the AI model provider, a token for GitHub or GitLab, and so on. OpenShell manages these credentials as first-class entities called providers . Create and manage providers that supply credentials to sandboxes. Create a Provider Providers can be created from local environment variables or with explicit credential values. From Local Credentials The fastest way to create a provider is to let the CLI discover credentials from\nyour shell environment: $ openshell provider create --name my-claude --type claude --from-existing\nThis reads ANTHROPIC_API_KEY or CLAUDE_API_KEY from your current environment\nand stores them in the provider. With Explicit Credentials Supply a credential value directly: $ openshell provider create --name my-api --type generic --credential API_KEY=sk-abc123\nBare Key Form Pass a key name without a value to read the value from the environment variable\nof that name: $ openshell provider create --name my-api --type generic --credential API_KEY\nThis looks up the current value of $API_KEY in your shell and stores it. Manage Providers List, inspect, update, and delete providers from the active cluster. List all providers: $ openshell provider list\nInspect a provider: $ openshell provider get my-claude\nUpdate a provider’s credentials: $ openshell provider update my-claude --type claude --from-existing\nDelete a provider: $ openshell provider delete my-claude\nAttach Providers to Sandboxes Pass one or more --provider flags when creating a sandbox: $ openshell sandbox create --provider my-claude --provider my-github -- claude\nEach --provider flag attaches one provider. The sandbox receives all\ncredentials from every attached provider at runtime. Providers cannot be added to a running sandbox. If you need to attach an\nadditional provider, delete the sandbox and recreate it with all required\nproviders specified. Auto-Discovery Shortcut When the trailing command in openshell sandbox create is a recognized tool name ( claude , codex , or opencode ), the CLI auto-creates the required\nprovider from your local credentials if one does not already exist. You do not\nneed to create the provider separately: $ openshell sandbox create -- claude\nThis detects claude as a known tool, finds your ANTHROPIC_API_KEY , creates\na provider, attaches it to the sandbox, and launches Claude Code. Supported Provider Types The following provider types are supported. Type Environment Variables Injected Typical Use 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 — refer to /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 outlook (none: no auto-discovery) Microsoft Outlook integration Use the generic type for any service not listed above. You define the\nenvironment variable names and values yourself with --credential . Next Steps Explore related topics: To control what the agent can access, refer to policies . To use a pre-built environment, refer to the community-sandboxes catalog. To view the complete field reference for the policy YAML, refer to the Policy Schema Reference","format":"text","summary":"AI agents typically need credentials to access external services: an API key for the AI model provider, a token for GitHub or GitLab, and so on. OpenShell manages these credentials as first-class entities called providers.","headings":[{"text":"Providers","level":1},{"text":"Create a Provider","level":2},{"text":"From Local Credentials","level":3},{"text":"With Explicit Credentials","level":3},{"text":"Bare Key Form","level":3},{"text":"Manage Providers","level":2},{"text":"Attach Providers to Sandboxes","level":2},{"text":"Auto-Discovery Shortcut","level":3},{"text":"Supported Provider Types","level":2},{"text":"Next Steps","level":2}]}
\ No newline at end of file
diff --git a/pr-preview/pr-257/search.html b/pr-preview/pr-257/search.html
index e56994e5d..55c01e742 100644
--- a/pr-preview/pr-257/search.html
+++ b/pr-preview/pr-257/search.html
@@ -815,7 +815,7 @@ window.addEventListener("load", load);</script>
 <p aria-level="2" class="caption" role="heading"><span class="caption-text">Get Started</span></p>
 <ul class="nav bd-sidenav">
 <li class="toctree-l1"><a class="reference internal" href="get-started/quickstart.html">Quickstart</a></li>
-<li class="toctree-l1"><a class="reference internal" href="tutorials/github-sandbox.html">Tutorial: GitHub Policy Iteration</a></li>
+<li class="toctree-l1"><a class="reference internal" href="tutorials/github-sandbox.html">GitHub Policy Tutorial</a></li>
 </ul>
 <p aria-level="2" class="caption" role="heading"><span class="caption-text">Sandboxes</span></p>
 <ul class="nav bd-sidenav">
diff --git a/pr-preview/pr-257/searchindex.js b/pr-preview/pr-257/searchindex.js
index a0dc85491..8c96c7177 100644
--- a/pr-preview/pr-257/searchindex.js
+++ b/pr-preview/pr-257/searchindex.js
@@ -1 +1 @@
-Search.setIndex({"alltitles": {"0.1.0": [[2, "id1"]], "About Inference Routing": [[6, null]], "About Sandboxes": [[14, null]], "Access Levels": [[9, "access-levels"]], "Agent Compatibility": [[8, "agent-compatibility"], [10, "agent-compatibility"]], "Ask Claude to check the sandbox logs": [[17, "ask-claude-to-check-the-sandbox-logs"]], "Attach Providers to Sandboxes": [[16, "attach-providers-to-sandboxes"]], "Auto-Discovery Shortcut": [[16, "auto-discovery-shortcut"]], "Bare Key Form": [[16, "bare-key-form"]], "Binary Object": [[9, "binary-object"]], "Built-in Default Policy": [[14, "built-in-default-policy"]], "Built-in Help": [[7, "built-in-help"]], "CLI Reference": [[7, null]], "Command Tree": [[7, "command-tree"]], "Common Risks and Controls": [[1, "common-risks-and-controls"]], "Common Use Cases": [[1, "common-use-cases"]], "Community Sandboxes": [[12, null]], "Components": [[0, "components"]], "Configure Inference Routing": [[5, null]], "Connect to a Remote Gateway (Optional)": [[3, "connect-to-a-remote-gateway-optional"]], "Connect to a Sandbox": [[13, "connect-to-a-sandbox"]], "Container Images": [[10, "container-images"]], "Contribute a Community Sandbox": [[12, "contribute-a-community-sandbox"]], "Create Your First OpenShell Sandbox": [[3, "create-your-first-openshell-sandbox"]], "Create a Provider": [[16, "create-a-provider"]], "Create a Sandbox": [[13, "create-a-sandbox"]], "Create and Manage Sandboxes": [[13, null]], "Create from a Community Sandbox or Custom Image": [[13, "create-from-a-community-sandbox-or-custom-image"]], "Current Catalog": [[12, "current-catalog"]], "Customize Sandbox Policies": [[15, null]], "Debug Denied Requests": [[15, "debug-denied-requests"]], "Default Policy Blocks": [[8, "default-policy-blocks"]], "Default Policy Reference": [[8, null]], "Delete Sandboxes": [[13, "delete-sandboxes"]], "Deployment Modes": [[0, "deployment-modes"]], "Diagnose the Denial": [[17, "diagnose-the-denial"]], "Diagnostic Commands": [[7, "diagnostic-commands"]], "Endpoint Object": [[9, "endpoint-object"]], "Environment Variables": [[7, "environment-variables"]], "Examples": [[15, "examples"]], "Explore": [[4, "explore"]], "Filesystem Policy": [[9, "filesystem-policy"]], "From Local Credentials": [[16, "from-local-credentials"]], "Full Example": [[9, "full-example"]], "Gateway Commands": [[7, "gateway-commands"]], "Get Started": [[4, "get-started"]], "Highlights": [[2, "highlights"]], "How OpenShell Works": [[0, null]], "How a Request Flows": [[0, "how-a-request-flows"]], "How inference.local Works": [[6, "how-inference-local-works"]], "Inference Commands": [[7, "inference-commands"]], "Install the OpenShell CLI": [[3, "install-the-openshell-cli"]], "Interactive SSH": [[13, "interactive-ssh"]], "Iterate on a Running Sandbox": [[15, "iterate-on-a-running-sandbox"]], "Kernel Requirements": [[10, "kernel-requirements"]], "Landlock": [[9, "landlock"]], "Launch the Sandbox": [[17, "launch-the-sandbox"]], "License": [[11, null]], "List and Inspect Sandboxes": [[13, "list-and-inspect-sandboxes"]], "Manage Providers": [[16, "manage-providers"]], "Monitor Your Sandbox": [[13, "monitor-your-sandbox"]], "NVIDIA OpenShell": [[4, null]], "NVIDIA OpenShell Release Notes": [[2, null]], "Network Access Rules": [[14, "network-access-rules"]], "Network Policies": [[9, "network-policies"]], "Network Policy Entry": [[9, "network-policy-entry"]], "Next Steps": [[0, "next-steps"], [1, "next-steps"], [5, "next-steps"], [6, "next-steps"], [12, "next-steps"], [13, "next-steps"], [14, "next-steps"], [15, "next-steps"], [16, "next-steps"], [17, "next-steps"]], "Open in a remote editor": [[13, "open-in-a-remote-editor"]], "Other Sources": [[12, "other-sources"]], "Overview of NVIDIA OpenShell": [[1, null]], "Policy Commands": [[7, "policy-commands"]], "Policy Schema Reference": [[9, null]], "Policy Structure": [[14, "policy-structure"]], "Port Forwarding Commands": [[7, "port-forwarding-commands"]], "Prerequisites": [[3, "prerequisites"], [17, "prerequisites"]], "Process": [[9, "process"]], "Protection Layers at a Glance": [[1, "protection-layers-at-a-glance"]], "Provider Commands": [[7, "provider-commands"]], "Provider Create Flags": [[7, "provider-create-flags"]], "Providers": [[16, null]], "Push Code to GitHub": [[17, "push-code-to-github"]], "Quick Start: Apply a Custom Policy": [[15, "quick-start-apply-a-custom-policy"]], "Quickstart": [[3, null]], "Retry the Push": [[17, "retry-the-push"]], "Rule Object": [[9, "rule-object"]], "Sandbox Commands": [[7, "sandbox-commands"]], "Sandbox Create Flags": [[7, "sandbox-create-flags"]], "Sandbox Lifecycle": [[14, "sandbox-lifecycle"]], "Sandbox Runtime Versions": [[10, "sandbox-runtime-versions"]], "Set Up a Sandbox of Claude Code with a Custom GitHub Policy": [[17, null]], "Shell Completions": [[7, "shell-completions"]], "Software Prerequisites": [[10, "software-prerequisites"]], "Status, Logs, and Terminal": [[7, "status-logs-and-terminal"]], "Step 1: Create a Provider": [[5, "step-1-create-a-provider"]], "Step 2: Set Inference Routing": [[5, "step-2-set-inference-routing"]], "Step 3: Verify the Active Config": [[5, "step-3-verify-the-active-config"]], "Step 4: Update Part of the Config": [[5, "step-4-update-part-of-the-config"]], "Support Matrix": [[10, null]], "Supported API Patterns": [[6, "supported-api-patterns"]], "Supported Agents": [[14, "supported-agents"]], "Supported Platforms": [[10, "supported-platforms"]], "Supported Provider Types": [[16, "supported-provider-types"]], "Top-Level Structure": [[9, "top-level-structure"]], "Transfer Files": [[13, "transfer-files"]], "Update the Policy from Your Laptop": [[17, "update-the-policy-from-your-laptop"]], "Use It from a Sandbox": [[5, "use-it-from-a-sandbox"]], "Use a Community Sandbox": [[12, "use-a-community-sandbox"]], "Verify the Endpoint from a Sandbox": [[5, "verify-the-endpoint-from-a-sandbox"]], "Version": [[9, "version"]], "View Logs": [[13, "view-logs"]], "View the logs from your laptop": [[17, "view-the-logs-from-your-laptop"]], "What Are Community Sandboxes": [[12, "what-are-community-sandboxes"]], "Why OpenShell Exists": [[1, "why-openshell-exists"]], "With Explicit Credentials": [[16, "with-explicit-credentials"]], "openshell inference get": [[7, "openshell-inference-get"]], "openshell inference set": [[7, "openshell-inference-set"]], "openshell inference update": [[7, "openshell-inference-update"]]}, "docnames": ["about/architecture", "about/overview", "about/release-notes", "get-started/quickstart", "index", "inference/configure", "inference/index", "reference/cli", "reference/default-policy", "reference/policy-schema", "reference/support-matrix", "resources/eula", "sandboxes/community-sandboxes", "sandboxes/create-and-manage", "sandboxes/index", "sandboxes/policies", "sandboxes/providers", "tutorials/github-sandbox"], "envversion": {"sphinx": 62, "sphinx.domains.c": 3, "sphinx.domains.changeset": 1, "sphinx.domains.citation": 1, "sphinx.domains.cpp": 9, "sphinx.domains.index": 1, "sphinx.domains.javascript": 3, "sphinx.domains.math": 2, "sphinx.domains.python": 4, "sphinx.domains.rst": 2, "sphinx.domains.std": 2, "sphinx.ext.intersphinx": 1, "sphinx.ext.viewcode": 1}, "filenames": ["about/architecture.md", "about/overview.md", "about/release-notes.md", "get-started/quickstart.md", "index.md", "inference/configure.md", "inference/index.md", "reference/cli.md", "reference/default-policy.md", "reference/policy-schema.md", "reference/support-matrix.md", "resources/eula.md", "sandboxes/community-sandboxes.md", "sandboxes/create-and-manage.md", "sandboxes/index.md", "sandboxes/policies.md", "sandboxes/providers.md", "tutorials/github-sandbox.md"], "indexentries": {}, "objects": {}, "objnames": {}, "objtypes": {}, "terms": {"": [6, 7, 8, 9, 12, 14, 16, 17], "0": [9, 10, 15], "1": [9, 10, 14, 15, 17], "10": [5, 10], "11": 10, "111": 10, "12": [3, 10], "124": 15, "13": 10, "15": 5, "168": 5, "17": 10, "18": 10, "192": 5, "2": [10, 15, 17], "22": 10, "256": 9, "3": [3, 10], "30b": 5, "35": 10, "4": 15, "4096": 9, "443": [8, 9, 14, 15, 17], "5m": 13, "61": 13, "8": 10, "8080": 3, "9": 10, "A": [5, 6, 7, 8, 9, 13, 14, 17], "At": 12, "For": [0, 1, 2, 3, 9, 10, 13, 14, 15, 17], "If": [3, 6, 7, 8, 12, 13, 14, 15, 16], "It": [1, 2, 4, 6, 8, 14, 17], "No": [6, 9, 10, 14, 17], "On": 10, "One": [6, 9], "Or": 5, "That": 1, "The": [0, 1, 3, 5, 6, 7, 8, 9, 10, 12, 13, 14, 15, 16, 17], "Then": 15, "These": 10, "To": [0, 1, 5, 6, 10, 12, 13, 14, 15, 16, 17], "With": 1, "a3b": 5, "aarch64": 10, "abc123": 16, "abi": [8, 9, 10, 14], "about": [4, 5, 7, 13, 15], "abov": [15, 16], "absolut": 9, "accept": [7, 9, 12], "access": [1, 3, 4, 5, 6, 7, 8, 10, 13, 15, 16, 17], "account": 17, "across": [0, 1], "act": 0, "action": [8, 13, 15], "activ": [3, 4, 7, 9, 13, 14, 16], "ad": [3, 15, 16], "add": [3, 7, 8, 9, 12, 13, 14, 15, 17], "addit": 16, "address": 9, "adjust": 15, "after": [3, 5, 7, 13, 15, 17], "ag": 13, "again": [13, 17], "against": [0, 12, 13, 14, 15], "agent": [0, 1, 2, 3, 4, 7, 9, 12, 13, 16, 17], "ai": [1, 2, 4, 8, 14, 16], "aliv": [7, 13], "all": [0, 1, 3, 6, 7, 8, 9, 10, 12, 13, 14, 15, 16, 17], "allow": [0, 1, 6, 8, 9, 14, 15, 17], "allowed_rout": [14, 15], "allowlist": 15, "alon": 9, "alpha": 15, "alreadi": [16, 17], "also": [0, 12, 13], "altern": 15, "amd64": 10, "an": [0, 1, 3, 6, 7, 8, 9, 12, 13, 14, 15, 16, 17], "angl": 17, "ani": [5, 6, 7, 9, 10, 12, 16, 17], "anoth": 13, "anthrop": [5, 6, 8, 16, 17], "anthropic_api_kei": [3, 5, 14, 16], "anyth": [5, 12], "api": [0, 1, 4, 5, 8, 9, 12, 13, 14, 15, 16, 17], "api2": 8, "api_kei": [5, 16], "app": [8, 17], "appear": 17, "appl": 10, "appli": [1, 6, 7, 8, 10, 12, 14, 17], "applic": [0, 5], "approv": 1, "ar": [1, 5, 6, 7, 8, 9, 10, 13, 14, 16, 17], "architectur": [0, 1, 4, 10], "argument": 7, "arm64": 10, "assign": 7, "assist": 5, "associ": 9, "attach": [7, 13], "attempt": [1, 17], "audit": [1, 9], "auth": 0, "authent": [5, 17], "auto": [7, 13, 14], "automat": [0, 3, 9, 10, 13, 17], "autonom": [1, 4], "avail": [7, 10, 12, 14], "avoid": 15, "awar": 0, "az764295": 8, "back": [7, 9, 12, 17], "backend": [0, 1, 4, 5, 6, 7], "background": [7, 13], "bare": 7, "base": [0, 3, 10, 12, 14], "base_url": 5, "bash": [7, 8, 17], "been": 17, "befor": [0, 3, 5, 7, 9, 10, 13, 15, 17], "begin": 3, "behav": 13, "behavior": [1, 9, 17], "behind": 6, "being": 14, "belong": 5, "below": [1, 7, 9, 17], "best_effort": [8, 9, 10, 14, 17], "between": [13, 17], "bin": [3, 8, 9, 14, 15, 17], "binari": [0, 8, 14, 15, 17], "blob": 8, "block": [0, 1, 7, 9, 13, 14, 15, 17], "bookworm": 10, "bool": 9, "bootstrap": [7, 10, 13], "both": [0, 7, 8, 14, 17], "boundari": 0, "box": [8, 14], "bravo": 15, "breakdown": [14, 15], "brev": 3, "brevlab": 3, "bring": 1, "broad": 9, "broker": 0, "build": [7, 8, 10, 12, 13], "built": [1, 3, 12, 13, 16], "bundl": [3, 10, 12, 13, 14], "call": [0, 1, 4, 5, 6, 7, 8, 10, 14, 15, 16], "can": [0, 1, 3, 5, 8, 9, 12, 13, 14, 15, 16, 17], "cannot": 16, "capabl": [1, 4], "case": 0, "catalog": [3, 5, 8, 13, 14, 16], "categori": 9, "caus": [13, 17], "chang": [0, 2, 5, 6, 9, 15], "charact": 9, "chart": 10, "chat": [5, 6], "check": [0, 7, 13, 14, 15], "choos": [3, 5], "ci_job_token": 16, "class": 16, "classic": 17, "claud": [1, 3, 4, 7, 8, 9, 10, 13, 14, 15, 16], "claude_api_kei": 16, "claude_cod": 17, "cli": [0, 1, 2, 4, 5, 10, 12, 13, 15, 16, 17], "client": 5, "clone": [0, 8, 17], "cloud": 1, "cluster": [0, 7, 10, 13, 16], "clutter": 13, "code": [0, 1, 3, 4, 5, 6, 8, 10, 12, 13, 14, 15, 16], "codex": [3, 4, 7, 8, 10, 14, 16], "com": [3, 6, 8, 9, 12, 13, 14, 15, 17], "combin": [1, 9, 13, 15], "come": 6, "command": [3, 4, 5, 10, 12, 13, 14, 15, 16, 17], "common": [8, 14], "commun": [1, 3, 4, 7, 10, 14, 16], "compat": [5, 6, 9, 14, 17], "complet": [5, 6, 8, 9, 13, 14, 16, 17], "complianc": 1, "compon": [1, 9, 10, 13], "comput": 0, "concept": 4, "config": [7, 13], "configur": [0, 3, 4, 6, 7, 8, 9, 12, 14, 17], "confin": 1, "confirm": [5, 15, 17], "connect": [0, 1, 5, 7, 8, 9, 14, 17], "consid": 12, "consist": 5, "consol": 3, "constrain": 1, "constraint": [0, 9], "contain": [0, 3, 7, 8, 9, 12, 13, 17], "container": 1, "content": [5, 17], "context": [0, 1, 17], "continu": [0, 3, 6, 14], "contribut": 13, "control": [0, 5, 6, 7, 9, 10, 12, 13, 14, 15, 16], "convers": 17, "coordin": 0, "copi": [3, 17], "core": 8, "correct": 17, "correctli": 5, "cost": 0, "count": 7, "cover": [2, 5, 14, 17], "coverag": [8, 10, 14], "creat": [0, 1, 2, 4, 8, 10, 12, 14, 15, 17], "creation": [1, 7, 9, 10, 13, 14, 15, 17], "credenti": [0, 1, 2, 3, 4, 5, 6, 7, 12, 13, 14, 15, 17], "curl": [5, 8, 14, 17], "current": [5, 7, 9, 15, 16], "cursor": [7, 8, 13, 17], "custom": [1, 2, 4, 8, 12, 14, 16], "d": [5, 7], "danger": [1, 10, 14], "dashboard": [7, 8, 13, 15, 17], "data": [1, 4, 7, 12, 14, 17], "debian": 10, "decis": [0, 7, 13, 17], "declar": [1, 4, 8, 9], "decrypt": [0, 9, 15], "deeper": 1, "default": [1, 7, 9, 10, 12, 15, 17], "defens": [0, 1], "defin": [6, 8, 9, 12, 14, 16], "definit": [0, 3, 12, 15], "delet": [7, 14, 16, 17], "deni": [0, 1, 6, 8, 13, 14, 17], "denial": 15, "depend": 6, "deploi": [0, 3, 7, 8], "deploy": [1, 7], "depth": [0, 1, 17], "describ": [0, 12, 15], "descript": [1, 5, 7, 9, 12, 14], "design": [1, 12, 17], "desktop": [3, 10], "destin": [0, 1, 8, 9, 14, 15], "destroi": [7, 9], "detail": [1, 2, 4, 5, 6, 7, 10, 13, 14, 17], "detect": 16, "dev": [8, 9, 12, 13, 17], "develop": [1, 8, 17], "dgx": [0, 3], "diagnos": 13, "differ": [9, 17], "dir": [12, 13], "directli": [0, 5, 6, 12, 13, 16], "directori": [7, 9, 12, 13], "disabl": 8, "disallow": 9, "discov": [7, 16], "discoveri": 6, "disk": [9, 12, 14], "displai": 9, "distinct": 7, "do": [6, 16, 17], "docker": [0, 3, 7, 8, 10, 13], "dockerfil": [7, 12, 13], "doctor": 7, "document": [7, 9], "doe": [5, 16, 17], "domain": 1, "down": [0, 14], "download": [7, 8, 13, 17], "dst_host": 17, "dst_port": 17, "dummi": 5, "dure": [10, 14], "dynam": [9, 14, 17], "e": [7, 14], "each": [0, 3, 7, 8, 9, 12, 14, 15, 16, 17], "edit": [15, 17], "editor": 7, "effect": [9, 17], "egress": 0, "either": 9, "elev": 14, "els": 12, "empti": 5, "enabl": [0, 7, 8, 9, 13, 15], "encrypt": 9, "end": [4, 5, 12, 13, 15], "endpoint": [0, 1, 3, 6, 7, 8, 14, 15, 17], "enforc": [0, 1, 2, 3, 9, 10, 14, 15, 17], "engin": [0, 10, 14, 17], "enterpris": 1, "entiti": 16, "entri": [7, 8, 13, 14, 15, 17], "entrypoint": 12, "env": 7, "environ": [1, 3, 4, 5, 10, 12, 13, 14, 15, 16, 17], "error": [8, 13, 14, 17], "escal": 1, "escap": 9, "especi": 13, "etc": [8, 9, 14, 17], "evalu": 6, "even": 13, "event": 13, "everi": [0, 5, 6, 7, 9, 14, 15, 16], "everyth": 7, "ex": 8, "exact": 17, "exactli": 4, "exampl": [0, 3, 7, 12, 13, 14, 17], "exce": 9, "exclus": 9, "exec": 7, "execut": [1, 2, 4, 7, 8, 9, 14], "exfiltr": [1, 4, 14], "exist": [5, 7, 12, 13, 16, 17], "exit": [7, 13, 15, 17], "expect": 17, "experi": 17, "explain": [13, 17], "explicit": 1, "explicitli": [7, 9, 13, 15], "explor": [1, 5, 12, 13, 15, 16], "export": [15, 17], "expos": 6, "exposur": 14, "extend": 17, "extens": 8, "extern": [0, 1, 5, 6, 16], "f": 7, "fail": [9, 10, 15, 17], "failur": [1, 17], "fall": [7, 9], "fastest": 16, "featur": 8, "fetch": [7, 8, 17], "field": [5, 7, 9, 14, 15, 16], "file": [1, 4, 7, 8, 9, 12, 14, 15, 17], "filesystem": [0, 1, 8, 10, 14], "filesystem_polici": [9, 14, 17], "filter": [7, 10, 13, 14], "final": 13, "find": [3, 16], "fine": 9, "first": [0, 1, 2, 4, 10, 13, 14, 16], "fish": 7, "fix": [15, 17], "flag": [3, 8, 12, 13, 15, 16, 17], "flow": 5, "follow": [0, 1, 3, 6, 7, 8, 9, 10, 12, 13, 14, 15, 16, 17], "forc": 7, "fork": 12, "format": 7, "forward": [0, 5, 6, 9, 13], "foundat": 12, "four": 0, "from": [0, 3, 4, 6, 7, 10, 12, 14, 15], "full": [7, 8, 10, 13, 14, 15, 17], "fulli": 13, "function": 14, "g": [7, 14], "gallerycdn": [8, 17], "gatewai": [0, 2, 5, 6, 10, 13], "gener": [5, 6, 7, 12, 13, 16, 17], "get": [3, 5, 6, 8, 9, 13, 15, 16, 17], "gh": [8, 9, 15, 16, 17], "gh_token": 16, "ghcr": 10, "gid": 9, "git": [0, 8, 9, 17], "github": [2, 4, 7, 8, 9, 13, 15, 16], "github_api": 17, "github_git": 17, "github_repo": 15, "github_rest_api": [9, 17], "github_token": [16, 17], "githubusercont": [8, 17], "gitlab": [7, 16], "gitlab_token": 16, "give": [1, 17], "glab": 16, "glab_token": 16, "glob": 9, "global": 7, "go": [1, 5, 17], "goe": 14, "govern": 4, "gpu": [7, 13], "grain": 9, "grant": [8, 9, 17], "granular": 15, "graphql": [15, 17], "greater": 17, "group": [7, 8, 9, 14], "grow": 12, "guid": [4, 17], "guidelin": 12, "h": 5, "ha": [9, 14, 17], "handi": 17, "handl": [6, 9], "happen": 13, "hard_requir": [9, 10], "hash": 15, "have": [3, 12, 13, 17], "head": [7, 9, 15], "header": 15, "health": 7, "healthi": 3, "hello": 5, "hello_world": 17, "helm": 10, "help": 5, "here": [7, 17], "hierarchi": 7, "highest": [8, 9, 10, 14], "hint": [7, 14], "hit": 3, "hold": 5, "host": [0, 1, 3, 4, 5, 6, 7, 8, 9, 10, 13, 14, 15, 17], "hostnam": 9, "hot": [1, 6, 9, 14, 15, 17], "how": [1, 9, 12, 13, 14, 17], "http": [0, 3, 5, 6, 7, 8, 9, 14, 15, 17], "human": 7, "i": [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 12, 13, 14, 15, 16, 17], "id": [5, 7], "ident": [0, 1, 9, 17], "identifi": [0, 7, 8, 9, 17], "ignor": 5, "imag": [1, 3, 4, 7, 12, 14], "immedi": 17, "impli": 7, "import": 5, "improv": 2, "inaccess": 9, "includ": [0, 7, 8, 13, 14], "include_workdir": [9, 17], "indic": 17, "individu": [9, 13], "infer": [0, 1, 4, 8, 13, 14, 15, 17], "info": [7, 8, 9, 17], "inform": [7, 13], "infrastructur": [0, 4], "initi": 15, "inject": [0, 6, 7, 13, 14, 16, 17], "input": 5, "insid": [0, 3, 5, 6, 7, 8, 9, 10, 17], "inspect": [7, 9, 14, 15, 16, 17], "inspect_for_infer": 13, "instal": [0, 1, 4, 7, 8, 10, 13, 14, 15], "instanc": 3, "instead": [5, 13, 17], "instruct": 5, "integ": 9, "integr": [8, 16, 17], "intel": 10, "intend": 9, "interact": [7, 17], "intercept": [0, 5, 13, 17], "intern": 1, "introduc": 2, "invalid_argu": 9, "invok": 12, "io": [8, 10, 17], "ip": 9, "isol": [0, 1, 2, 7, 10, 14], "issu": [7, 8, 15, 17], "iter": [13, 17], "its": [0, 4, 7, 8, 9, 17], "j": [7, 10], "job": 17, "json": 5, "k": 7, "k3": [0, 10], "k3s1": 10, "k9": 7, "keep": [0, 1, 4, 7, 13, 15, 17], "kei": [1, 3, 6, 7, 9, 12, 13, 14], "kernel": [0, 1, 2, 8, 9, 14], "known": 16, "kubectl": 7, "kubernet": [0, 10], "l4": 8, "l7_action": 17, "l7_decis": 17, "l7_deny_reason": 17, "l7_protocol": 17, "l7_target": 17, "label": 13, "landlock": [1, 8, 10, 14, 17], "last": 7, "later": [3, 13, 17], "latest": [2, 10, 12, 13], "launch": [3, 7, 12, 13, 14, 16], "launchabl": 3, "layer": [0, 14], "learn": [0, 1, 4, 15, 17], "let": 16, "level": [1, 2, 7, 10, 13, 14, 15, 17], "lib": [8, 9, 14, 17], "lifecycl": [0, 13], "like": [6, 9, 13], "limit": 7, "line": 7, "link": 3, "linux": 10, "list": [7, 8, 9, 10, 14, 15, 16], "live": [7, 13, 15, 17], "llm": [0, 8], "load": [9, 15, 17], "local": [0, 1, 3, 4, 5, 7, 8, 9, 12, 13, 14, 15, 17], "locat": 0, "lock": [1, 9, 14, 17], "log": [0, 8, 9, 14, 15], "logic": 9, "longer": 13, "look": [13, 16, 17], "lookup": 8, "lsm": [9, 10, 14], "machin": [3, 13], "maco": 10, "mai": [9, 14, 17], "main": 13, "make": [1, 3], "manag": [0, 2, 4, 5, 6, 7, 12, 14, 17], "mandatori": 9, "manifest": 10, "manipul": 12, "map": 9, "marketplac": [8, 17], "match": [0, 3, 6, 8, 9, 14], "materi": 1, "matter": 17, "md": 12, "messag": [5, 6], "metadata": [7, 8, 15], "method": [0, 6, 9, 14, 15, 17], "microsoft": [8, 16, 17], "might": 13, "minimum": [10, 12], "miss": 15, "mitig": 1, "mode": [1, 7, 9, 10], "model": [0, 1, 5, 6, 7, 16], "modern": 10, "modifi": [9, 15], "modul": 10, "monitor": [7, 15], "more": [2, 4, 7, 14, 16], "most": 1, "move": 14, "msecnd": [8, 17], "multi": 10, "multipl": [7, 14], "must": [8, 9, 10, 12, 13, 14], "mutat": 8, "mutual": 9, "my": [5, 12, 13, 14, 15, 16, 17], "my_api": 14, "n": 7, "name": [5, 7, 9, 10, 12, 13, 14, 15, 16, 17], "namespac": 14, "nano": 5, "navig": 7, "need": [4, 6, 12, 13, 15, 16, 17], "neither": 9, "nemotron": 5, "net": [8, 17], "network": [0, 1, 4, 5, 6, 8, 13, 15, 17], "network_polici": [5, 6, 9, 14, 15, 17], "new": [7, 15, 17], "node": [8, 9, 10, 17], "non": 8, "none": [8, 16], "nor": 9, "normal": 9, "note": [8, 10, 14], "noth": 4, "now": 17, "npm": [9, 10], "npm_registri": 9, "npmj": 9, "null": [8, 9, 17], "number": 9, "nvidia": [3, 5, 6, 7, 8, 10, 13, 14, 16, 17], "nvidia_api_kei": [5, 16], "nvidia_infer": 17, "o": [9, 10, 13], "object": [8, 17], "omit": [7, 9], "omutbound": 13, "one": [0, 5, 6, 7, 9, 12, 14, 16, 17], "ones": 13, "onli": [0, 1, 5, 6, 7, 8, 9, 14, 15, 17], "open": [0, 1, 7, 12, 14, 17], "openai": [5, 6, 8, 14, 16], "openai_api_kei": [3, 5, 14, 16], "openai_base_url": 5, "openclaw": [1, 3, 4, 12, 13, 14], "opencod": [1, 3, 4, 7, 8, 10, 14, 16, 17], "opencode_api_kei": 16, "openrouter_api_kei": [3, 16], "openshel": [5, 6, 8, 9, 10, 12, 13, 14, 15, 16, 17], "openshell_cluster_imag": 10, "openshell_community_registri": 10, "openshell_gatewai": 7, "openshell_sandbox_polici": [7, 15], "oper": [7, 17], "option": [7, 9, 12, 14, 15], "orchestr": 14, "org": [8, 9, 15, 17], "org_nam": 15, "organ": 17, "origin": [0, 6], "other": [1, 3, 6, 8, 17], "otherwis": [13, 14], "out": [8, 14], "outbound": [0, 1, 6, 8, 14, 17], "outlin": 15, "outlook": [7, 16], "output": [7, 9, 13, 17], "outsid": [1, 17], "over": [1, 3, 8, 17], "overli": 9, "overrid": [7, 10], "overview": 4, "own": [1, 12, 13, 17], "pack": [8, 9, 17], "packag": [0, 1, 3, 8, 12, 13, 17], "page": [2, 3, 5, 10, 13, 15], "pair": [8, 14], "partial": [8, 14], "particular": 12, "pass": [0, 7, 12, 14, 15, 16], "passthrough": [8, 9, 15], "past": 17, "pat": 17, "patch": [9, 15], "path": [0, 1, 6, 7, 8, 9, 12, 13, 14, 15, 17], "pattern": [1, 5, 9], "payload": [14, 15], "per": [0, 9, 15, 17], "perman": 7, "permiss": [4, 9, 17], "permit": [9, 17], "person": 17, "perspect": 17, "phase": [13, 14], "pick": [3, 6], "pid": 8, "pip": [3, 4, 8, 10, 15, 17], "pipe": 7, "plan": 15, "plane": [0, 10], "platform": [0, 8, 17], "pod": [0, 7], "point": [5, 12, 13], "polici": [0, 1, 2, 3, 4, 10, 12, 13, 16], "port": [0, 3, 8, 9, 13, 14, 15, 17], "post": [6, 8, 9, 15, 17], "pr": 8, "pre": [3, 8, 12, 13, 14, 16], "preconfigur": 12, "prefer": 17, "preserv": [1, 7], "press": 7, "prevent": [1, 4, 14], "previou": 17, "previous": 17, "print": 7, "privaci": [0, 1, 5, 6, 14], "privat": [1, 4, 14], "privileg": [1, 14], "problem": 17, "proc": [8, 9, 17], "process": [0, 1, 8, 12, 13, 14, 17], "prod": 5, "prompt": [1, 3, 17], "properti": 6, "protect": [0, 4, 14], "protocol": [9, 14, 15, 17], "provid": [1, 3, 4, 6, 8, 9, 12, 13, 14, 15, 17], "provis": [0, 14], "proxi": [0, 8, 9, 13, 14, 15, 17], "prss": [8, 17], "public": 17, "publish": [10, 12], "pull": [3, 8, 10, 12, 13, 15, 17], "purg": [13, 14], "purpos": [10, 12, 13], "push": [8, 15], "put": [9, 17], "py": 17, "pypi": [8, 15, 17], "python": [3, 8, 10, 17], "python3": [8, 17], "pythonhost": [8, 15, 17], "q": 7, "queri": [0, 14, 17], "quickstart": [0, 1, 4, 17], "quit": 7, "rancher": 10, "rang": 1, "rather": 6, "raw": [8, 17], "re": 3, "reach": [5, 8, 9, 14, 15, 17], "reachabl": [5, 9], "read": [1, 5, 7, 8, 9, 14, 15, 16, 17], "read_onli": [9, 14, 17], "read_writ": [9, 14, 17], "readabl": 7, "readi": [12, 14], "readm": [12, 17], "real": 13, "reason": [5, 15, 17], "receiv": [8, 16, 17], "recogn": [16, 17], "recommend": 10, "reconnect": [13, 17], "record": [5, 6, 7], "recreat": [6, 9, 16, 17], "ref": [8, 9, 17], "refer": [0, 1, 2, 4, 5, 6, 10, 12, 13, 14, 15, 16, 17], "refresh": 6, "refus": 13, "regist": 7, "registri": [3, 9, 10, 12, 13], "reject": 9, "relat": [5, 12, 13, 15, 16, 17], "releas": [8, 13, 14], "relev": 9, "reload": [1, 9, 14, 15, 17], "remain": 17, "remot": [0, 7, 8, 17], "remov": [7, 13], "repeat": [5, 7, 15], "replac": [7, 15, 17], "repo": [4, 8, 15, 17], "report": [8, 17], "repositori": [8, 12, 17], "repres": 17, "request": [5, 6, 7, 8, 9, 12, 13, 14, 17], "requir": [5, 7, 8, 9, 14, 16, 17], "rerout": [1, 14], "resolv": [8, 12, 13], "resourc": [13, 14, 17], "respons": [5, 6, 17], "rest": [0, 8, 9, 14, 15, 17], "restart": [9, 17], "restrict": [1, 9, 10, 14, 17], "retriev": 13, "return": [0, 13], "reus": 15, "reusabl": 1, "review": [1, 12, 15], "revis": [15, 17], "rewrit": 5, "role": [0, 5], "root": [9, 17], "rout": [0, 1, 3, 4, 8, 14], "router": [0, 5, 6], "rule": [0, 5, 6, 8, 12, 15, 17], "run": [0, 1, 2, 3, 4, 5, 7, 8, 9, 10, 12, 13, 14, 16, 17], "run_as_group": [9, 14, 17], "run_as_us": [9, 14, 17], "runtim": [0, 1, 4, 7, 13, 14, 16], "safe": [4, 14], "same": [0, 1, 5, 6, 8, 14, 17], "sandbox": [0, 1, 2, 4, 6, 8, 9], "save": 5, "schema": [4, 14, 15, 16, 17], "scope": [5, 9, 17], "scratch": 17, "script": [7, 12, 17], "sdg": 12, "seccomp": [1, 10, 14], "secret": [1, 7], "section": [8, 14, 15, 17], "secur": [0, 1, 3, 5, 6, 10], "see": [5, 7, 17], "select": [7, 17], "self": [1, 4, 5], "send": 1, "sensit": [0, 1], "sentri": [8, 17], "separ": [10, 16, 17], "serv": 5, "server": [5, 8, 9, 10, 17], "servic": [0, 2, 16], "session": [7, 8, 13, 17], "set": [3, 4, 6, 8, 9, 10, 12, 13, 14, 15, 16], "setuid": [1, 14], "sever": [10, 13], "sh": [7, 8], "shareabl": 3, "shell": 16, "ship": [10, 14], "should": [5, 6], "show": [3, 7, 8, 13, 15, 17], "silicon": 10, "similar": 17, "simpl": [15, 17], "simul": 12, "sinc": 13, "singl": [3, 7, 12, 13, 17], "sk": 16, "skill": [3, 12], "skip": 3, "small": 17, "smart": [8, 17], "so": [0, 1, 8, 12, 16, 17], "socket": 8, "someth": 14, "sourc": [1, 3, 7, 13, 14, 15], "spark": [0, 3], "special": 6, "specif": [7, 13, 17], "specifi": [7, 13, 16, 17], "split": 14, "spot": 13, "src": 13, "ssh": [1, 3, 7], "ssid": [0, 3], "stai": [5, 6], "standalon": 8, "start": [0, 3, 7, 9, 10, 13, 17], "startup": [7, 10, 12], "state": [0, 7], "static": [9, 14, 17], "statsig": [8, 17], "statu": [0, 3, 10, 13, 15, 17], "step": 3, "stop": [7, 13], "storag": 9, "store": 16, "stream": [7, 13, 14, 15, 17], "string": 9, "strip": [0, 6, 15], "structur": [15, 17], "subcommand": 7, "subdomain": 9, "submiss": 12, "subsequ": [3, 7], "success": 5, "successfulli": 17, "sudo": [1, 14], "summar": [1, 14, 17], "supervis": 0, "suppli": [5, 6, 12, 13, 14, 16], "support": [1, 5, 8, 9, 12], "sure": 3, "switch": [5, 17], "sync": [3, 14], "syntax": 9, "synthet": 12, "syscal": 1, "system": [0, 4, 9, 10, 12, 14], "tab": [3, 7], "tabl": [0, 1, 8, 10, 14, 17], "tail": [7, 13, 15], "tailor": 3, "take": [9, 17], "target": [7, 17], "tcp": [8, 9, 14, 15], "team": 1, "telemetri": 8, "term": [7, 13, 15, 17], "termin": [0, 8, 9, 13, 14, 15, 17], "test": 17, "than": 6, "theft": 1, "thei": [1, 4, 13], "them": [1, 9, 14, 16], "thi": [1, 2, 3, 5, 7, 9, 10, 13, 14, 15, 16, 17], "thing": [14, 17], "those": 14, "threat": 1, "three": [0, 14], "through": [0, 3, 5, 6, 8, 9, 10, 13, 14, 17], "throughout": 17, "time": [7, 9, 10, 13, 15], "timeout": 15, "tl": [0, 8, 9, 14, 15, 17], "tmp": [8, 9, 14, 17], "togeth": 0, "token": [12, 13, 14, 16, 17], "tool": [12, 16], "topic": [1, 5, 12, 13, 15, 16, 17], "torn": 14, "total": 9, "track": 2, "tradeoff": 1, "traffic": [0, 1, 4, 5, 6, 8, 9, 17], "trail": [7, 13, 14, 16], "travers": 9, "treat": [1, 6], "tree": 9, "triag": 15, "trigger": 13, "troubleshoot": 7, "true": [9, 17], "trust": 17, "try": [13, 17], "tunnel": 3, "tutori": [4, 13, 17], "two": [3, 4, 5, 6, 10, 17], "type": [3, 5, 7, 9, 17], "typic": [9, 16], "ubuntu": 10, "uid": 9, "unapprov": 1, "unauthor": [1, 4, 14], "unavail": [9, 10], "unblock": 17, "unchang": 17, "uncontrol": 4, "under": [1, 3, 7, 9, 12, 14], "understand": [1, 5], "unexpectedli": 13, "unix": 9, "unlist": 17, "unprivileg": [1, 14], "unrestrict": 1, "untest": 10, "until": 17, "up": [1, 3, 4, 6, 12, 13, 14, 15, 16], "updat": [6, 8, 9, 15, 16], "upload": [1, 7, 8, 9, 13, 17], "upstream": 5, "urandom": [8, 9, 17], "url": [3, 7, 9], "us": [0, 3, 7, 8, 9, 10, 13, 14, 15, 16, 17], "usag": [1, 7], "user": [0, 5, 7, 8, 9, 14, 16], "usernam": [0, 3, 15, 17], "usr": [8, 9, 14, 15, 17], "uv": [3, 4, 8, 10, 15, 17], "v": [8, 13, 14, 17], "v1": [5, 6, 10], "valid": [9, 15], "valu": [5, 7, 8, 9, 16], "var": [8, 17], "variabl": [4, 10, 15, 16, 17], "venv": [3, 8, 17], "verbos": 7, "verifi": [15, 17], "version": [1, 5, 7, 14, 15, 17], "via": [8, 10, 17], "view": [5, 7, 14, 15, 16], "violat": 9, "virtual": 3, "visualstudio": [8, 17], "vm": 10, "vo": [8, 17], "vsasset": [8, 17], "vscode": [7, 8, 9, 13, 17], "wa": [5, 7], "wai": [6, 16], "wait": [15, 17], "walk": [13, 17], "walkthrough": 15, "want": [5, 12, 13, 17], "warn": 13, "well": 17, "went": 14, "wget": [8, 17], "what": [1, 9, 13, 14, 15, 16, 17], "when": [1, 3, 5, 6, 7, 8, 9, 10, 12, 13, 14, 15, 16, 17], "whenev": 15, "where": [1, 9, 17], "whether": 9, "which": [0, 7, 9, 15, 17], "while": 1, "whose": [12, 13], "wildcard": 9, "window": [8, 10, 13], "without": [1, 5, 6, 7, 8, 9, 13, 14, 15, 16, 17], "word": 17, "work": [8, 9, 13, 14, 17], "workdir": 8, "workflow": [12, 13, 14, 15, 17], "workspac": [13, 17], "workstat": 0, "would": 9, "write": [1, 8, 9, 12, 14, 15, 17], "wrong": 14, "wsl": 10, "x86_64": 10, "yaml": [1, 7, 8, 9, 12, 13, 15, 16, 17], "ye": [3, 8, 9], "yet": 17, "you": [3, 5, 7, 8, 12, 13, 14, 15, 16, 17], "your": [0, 1, 4, 5, 7, 12, 14, 15, 16], "yourself": 16, "zero": 3, "zsh": 7, "zshrc": 7}, "titles": ["How OpenShell Works", "Overview of NVIDIA OpenShell", "NVIDIA OpenShell Release Notes", "Quickstart", "NVIDIA OpenShell", "Configure Inference Routing", "About Inference Routing", "CLI Reference", "Default Policy Reference", "Policy Schema Reference", "Support Matrix", "License", "Community Sandboxes", "Create and Manage Sandboxes", "About Sandboxes", "Customize Sandbox Policies", "Providers", "Set Up a Sandbox of Claude Code with a Custom GitHub Policy"], "titleterms": {"0": 2, "1": [2, 5], "2": 5, "3": 5, "4": 5, "It": 5, "With": 16, "about": [6, 14], "access": [9, 14], "activ": 5, "agent": [8, 10, 14], "api": 6, "appli": 15, "ar": 12, "ask": 17, "attach": 16, "auto": 16, "bare": 16, "binari": 9, "block": 8, "built": [7, 14], "case": 1, "catalog": 12, "check": 17, "claud": 17, "cli": [3, 7], "code": 17, "command": 7, "common": 1, "commun": [12, 13], "compat": [8, 10], "complet": 7, "compon": 0, "config": 5, "configur": 5, "connect": [3, 13], "contain": 10, "contribut": 12, "control": 1, "creat": [3, 5, 7, 13, 16], "credenti": 16, "current": 12, "custom": [13, 15, 17], "debug": 15, "default": [8, 14], "delet": 13, "deni": 15, "denial": 17, "deploy": 0, "diagnos": 17, "diagnost": 7, "discoveri": 16, "editor": 13, "endpoint": [5, 9], "entri": 9, "environ": 7, "exampl": [9, 15], "exist": 1, "explicit": 16, "explor": 4, "file": 13, "filesystem": 9, "first": 3, "flag": 7, "flow": 0, "form": 16, "forward": 7, "from": [5, 13, 16, 17], "full": 9, "gatewai": [3, 7], "get": [4, 7], "github": 17, "glanc": 1, "help": 7, "highlight": 2, "how": [0, 6], "imag": [10, 13], "infer": [5, 6, 7], "inspect": 13, "instal": 3, "interact": 13, "iter": 15, "kei": 16, "kernel": 10, "landlock": 9, "laptop": 17, "launch": 17, "layer": 1, "level": 9, "licens": 11, "lifecycl": 14, "list": 13, "local": [6, 16], "log": [7, 13, 17], "manag": [13, 16], "matrix": 10, "mode": 0, "monitor": 13, "network": [9, 14], "next": [0, 1, 5, 6, 12, 13, 14, 15, 16, 17], "note": 2, "nvidia": [1, 2, 4], "object": 9, "open": 13, "openshel": [0, 1, 2, 3, 4, 7], "option": 3, "other": 12, "overview": 1, "part": 5, "pattern": 6, "platform": 10, "polici": [7, 8, 9, 14, 15, 17], "port": 7, "prerequisit": [3, 10, 17], "process": 9, "protect": 1, "provid": [5, 7, 16], "push": 17, "quick": 15, "quickstart": 3, "refer": [7, 8, 9], "releas": 2, "remot": [3, 13], "request": [0, 15], "requir": 10, "retri": 17, "risk": 1, "rout": [5, 6], "rule": [9, 14], "run": 15, "runtim": 10, "sandbox": [3, 5, 7, 10, 12, 13, 14, 15, 16, 17], "schema": 9, "set": [5, 7, 17], "shell": 7, "shortcut": 16, "softwar": 10, "sourc": 12, "ssh": 13, "start": [4, 15], "statu": 7, "step": [0, 1, 5, 6, 12, 13, 14, 15, 16, 17], "structur": [9, 14], "support": [6, 10, 14, 16], "termin": 7, "top": 9, "transfer": 13, "tree": 7, "type": 16, "up": 17, "updat": [5, 7, 17], "us": [1, 5, 12], "variabl": 7, "verifi": 5, "version": [9, 10], "view": [13, 17], "what": 12, "why": 1, "work": [0, 6], "your": [3, 13, 17]}})
\ No newline at end of file
+Search.setIndex({"alltitles": {"0.1.0": [[2, "id1"]], "About Inference Routing": [[6, null]], "About Sandboxes": [[14, null]], "Access Levels": [[9, "access-levels"]], "Agent Compatibility": [[8, "agent-compatibility"], [10, "agent-compatibility"]], "Apply the Policy": [[17, "apply-the-policy"]], "Ask Claude Code to Check the Sandbox Logs": [[17, "ask-claude-code-to-check-the-sandbox-logs"]], "Attach Providers to Sandboxes": [[16, "attach-providers-to-sandboxes"]], "Auto-Discovery Shortcut": [[16, "auto-discovery-shortcut"]], "Bare Key Form": [[16, "bare-key-form"]], "Binary Object": [[9, "binary-object"]], "Built-in Default Policy": [[14, "built-in-default-policy"]], "Built-in Help": [[7, "built-in-help"]], "CLI Reference": [[7, null]], "Clean Up": [[17, "clean-up"]], "Command Tree": [[7, "command-tree"]], "Common Risks and Controls": [[1, "common-risks-and-controls"]], "Common Use Cases": [[1, "common-use-cases"]], "Community Sandboxes": [[12, null]], "Components": [[0, "components"]], "Configure Inference Routing": [[5, null]], "Connect to a Remote Gateway (Optional)": [[3, "connect-to-a-remote-gateway-optional"]], "Connect to a Sandbox": [[13, "connect-to-a-sandbox"]], "Container Images": [[10, "container-images"]], "Contribute a Community Sandbox": [[12, "contribute-a-community-sandbox"]], "Create Your First OpenShell Sandbox": [[3, "create-your-first-openshell-sandbox"]], "Create a Provider": [[16, "create-a-provider"]], "Create a Sandbox": [[13, "create-a-sandbox"]], "Create and Manage Sandboxes": [[13, null]], "Create from a Community Sandbox or Custom Image": [[13, "create-from-a-community-sandbox-or-custom-image"]], "Current Catalog": [[12, "current-catalog"]], "Customize Sandbox Policies": [[15, null]], "Debug Denied Requests": [[15, "debug-denied-requests"]], "Default Policy Blocks": [[8, "default-policy-blocks"]], "Default Policy Reference": [[8, null]], "Delete Sandboxes": [[13, "delete-sandboxes"]], "Deployment Modes": [[0, "deployment-modes"]], "Diagnose the Denial": [[17, "diagnose-the-denial"]], "Diagnostic Commands": [[7, "diagnostic-commands"]], "Endpoint Object": [[9, "endpoint-object"]], "Environment Variables": [[7, "environment-variables"]], "Examples": [[15, "examples"]], "Explore": [[4, "explore"]], "Filesystem Policy": [[9, "filesystem-policy"]], "From Local Credentials": [[16, "from-local-credentials"]], "Full Example": [[9, "full-example"]], "Gateway Commands": [[7, "gateway-commands"]], "Get Started": [[4, "get-started"]], "Highlights": [[2, "highlights"]], "How OpenShell Works": [[0, null]], "How a Request Flows": [[0, "how-a-request-flows"]], "How inference.local Works": [[6, "how-inference-local-works"]], "Inference Commands": [[7, "inference-commands"]], "Install the OpenShell CLI": [[3, "install-the-openshell-cli"]], "Interactive SSH": [[13, "interactive-ssh"]], "Iterate on a Running Sandbox": [[15, "iterate-on-a-running-sandbox"]], "Kernel Requirements": [[10, "kernel-requirements"]], "Landlock": [[9, "landlock"]], "License": [[11, null]], "List and Inspect Sandboxes": [[13, "list-and-inspect-sandboxes"]], "Manage Providers": [[16, "manage-providers"]], "Monitor Your Sandbox": [[13, "monitor-your-sandbox"]], "NVIDIA OpenShell": [[4, null]], "NVIDIA OpenShell Release Notes": [[2, null]], "Network Access Rules": [[14, "network-access-rules"]], "Network Policies": [[9, "network-policies"]], "Network Policy Entry": [[9, "network-policy-entry"]], "Next Steps": [[0, "next-steps"], [1, "next-steps"], [5, "next-steps"], [6, "next-steps"], [12, "next-steps"], [13, "next-steps"], [14, "next-steps"], [15, "next-steps"], [16, "next-steps"], [17, "next-steps"]], "Open in a remote editor": [[13, "open-in-a-remote-editor"]], "Other Sources": [[12, "other-sources"]], "Overview of NVIDIA OpenShell": [[1, null]], "Policy Commands": [[7, "policy-commands"]], "Policy Schema Reference": [[9, null]], "Policy Structure": [[14, "policy-structure"]], "Port Forwarding Commands": [[7, "port-forwarding-commands"]], "Prerequisites": [[3, "prerequisites"], [17, "prerequisites"]], "Process": [[9, "process"]], "Protection Layers at a Glance": [[1, "protection-layers-at-a-glance"]], "Provider Commands": [[7, "provider-commands"]], "Provider Create Flags": [[7, "provider-create-flags"]], "Providers": [[16, null]], "Push Code to GitHub": [[17, "push-code-to-github"]], "Quick Start: Apply a Custom Policy": [[15, "quick-start-apply-a-custom-policy"]], "Quickstart": [[3, null]], "Retry the Push": [[17, "retry-the-push"]], "Review the Generated Policy": [[17, "review-the-generated-policy"]], "Rule Object": [[9, "rule-object"]], "Sandbox Commands": [[7, "sandbox-commands"]], "Sandbox Create Flags": [[7, "sandbox-create-flags"]], "Sandbox Lifecycle": [[14, "sandbox-lifecycle"]], "Sandbox Runtime Versions": [[10, "sandbox-runtime-versions"]], "Set Up a Sandbox of Claude Code with a Custom GitHub Policy": [[17, null]], "Set Up a Sandbox with Your GitHub Token": [[17, "set-up-a-sandbox-with-your-github-token"]], "Shell Completions": [[7, "shell-completions"]], "Software Prerequisites": [[10, "software-prerequisites"]], "Status, Logs, and Terminal": [[7, "status-logs-and-terminal"]], "Step 1: Create a Provider": [[5, "step-1-create-a-provider"]], "Step 2: Set Inference Routing": [[5, "step-2-set-inference-routing"]], "Step 3: Verify the Active Config": [[5, "step-3-verify-the-active-config"]], "Step 4: Update Part of the Config": [[5, "step-4-update-part-of-the-config"]], "Support Matrix": [[10, null]], "Supported API Patterns": [[6, "supported-api-patterns"]], "Supported Agents": [[14, "supported-agents"]], "Supported Platforms": [[10, "supported-platforms"]], "Supported Provider Types": [[16, "supported-provider-types"]], "Top-Level Structure": [[9, "top-level-structure"]], "Transfer Files": [[13, "transfer-files"]], "Update the Policy from Your Machine": [[17, "update-the-policy-from-your-machine"]], "Use It from a Sandbox": [[5, "use-it-from-a-sandbox"]], "Use a Community Sandbox": [[12, "use-a-community-sandbox"]], "Verify the Endpoint from a Sandbox": [[5, "verify-the-endpoint-from-a-sandbox"]], "Version": [[9, "version"]], "View Logs": [[13, "view-logs"]], "View the Logs from Your Machine": [[17, "view-the-logs-from-your-machine"]], "What Are Community Sandboxes": [[12, "what-are-community-sandboxes"]], "Why OpenShell Exists": [[1, "why-openshell-exists"]], "With Explicit Credentials": [[16, "with-explicit-credentials"]], "openshell inference get": [[7, "openshell-inference-get"]], "openshell inference set": [[7, "openshell-inference-set"]], "openshell inference update": [[7, "openshell-inference-update"]]}, "docnames": ["about/architecture", "about/overview", "about/release-notes", "get-started/quickstart", "index", "inference/configure", "inference/index", "reference/cli", "reference/default-policy", "reference/policy-schema", "reference/support-matrix", "resources/eula", "sandboxes/community-sandboxes", "sandboxes/create-and-manage", "sandboxes/index", "sandboxes/policies", "sandboxes/providers", "tutorials/github-sandbox"], "envversion": {"sphinx": 62, "sphinx.domains.c": 3, "sphinx.domains.changeset": 1, "sphinx.domains.citation": 1, "sphinx.domains.cpp": 9, "sphinx.domains.index": 1, "sphinx.domains.javascript": 3, "sphinx.domains.math": 2, "sphinx.domains.python": 4, "sphinx.domains.rst": 2, "sphinx.domains.std": 2, "sphinx.ext.intersphinx": 1, "sphinx.ext.viewcode": 1}, "filenames": ["about/architecture.md", "about/overview.md", "about/release-notes.md", "get-started/quickstart.md", "index.md", "inference/configure.md", "inference/index.md", "reference/cli.md", "reference/default-policy.md", "reference/policy-schema.md", "reference/support-matrix.md", "resources/eula.md", "sandboxes/community-sandboxes.md", "sandboxes/create-and-manage.md", "sandboxes/index.md", "sandboxes/policies.md", "sandboxes/providers.md", "tutorials/github-sandbox.md"], "indexentries": {}, "objects": {}, "objnames": {}, "objtypes": {}, "terms": {"": [6, 7, 8, 9, 12, 14, 16, 17], "0": [9, 10, 15], "1": [9, 10, 14, 15, 17], "10": [5, 10], "11": 10, "111": 10, "12": [3, 10], "124": 15, "13": 10, "15": 5, "168": 5, "17": 10, "18": 10, "192": 5, "2": [10, 15, 17], "22": 10, "256": 9, "3": [3, 10], "30b": 5, "35": 10, "4": 15, "4096": 9, "443": [8, 9, 14, 15, 17], "5m": 13, "61": 13, "8": 10, "8080": 3, "9": 10, "A": [5, 6, 7, 8, 9, 13, 14, 17], "At": 12, "For": [0, 1, 2, 3, 9, 10, 13, 14, 15, 17], "If": [3, 6, 7, 8, 12, 13, 14, 15, 16], "In": 17, "It": [1, 2, 4, 6, 8, 14, 17], "No": [6, 9, 10, 14, 17], "On": 10, "One": [6, 9], "Or": 5, "That": 1, "The": [0, 1, 3, 5, 6, 7, 8, 9, 10, 12, 13, 14, 15, 16, 17], "Then": 15, "These": 10, "To": [0, 1, 5, 6, 10, 12, 13, 14, 15, 16, 17], "With": 1, "a3b": 5, "aarch64": 10, "abc123": 16, "abi": [8, 9, 10, 14], "about": [4, 5, 7, 13, 15], "abov": [15, 16, 17], "absolut": 9, "accept": [7, 9, 12], "access": [1, 3, 4, 5, 6, 7, 8, 10, 13, 15, 16, 17], "account": 17, "across": [0, 1], "act": 0, "action": [8, 13, 15], "activ": [3, 4, 7, 9, 13, 14, 16], "ad": [3, 15, 16], "add": [3, 7, 8, 9, 12, 13, 14, 15, 17], "addit": 16, "address": 9, "adjust": 15, "after": [3, 5, 7, 13, 15, 17], "ag": 13, "again": [13, 17], "against": [0, 12, 13, 14, 15], "agent": [0, 1, 2, 3, 4, 7, 9, 12, 13, 16, 17], "ai": [1, 2, 4, 8, 14, 16], "aliv": [7, 13], "all": [0, 1, 3, 6, 7, 8, 9, 10, 12, 13, 14, 15, 16, 17], "allow": [0, 1, 6, 8, 9, 14, 15, 17], "allowed_rout": [14, 15], "allowlist": 15, "alon": 9, "alpha": 15, "alreadi": [16, 17], "also": [0, 12, 13], "altern": 15, "amd64": 10, "an": [0, 1, 3, 6, 7, 8, 9, 12, 13, 14, 15, 16, 17], "ani": [5, 6, 7, 9, 10, 12, 16, 17], "anoth": 13, "anthrop": [5, 6, 8, 16, 17], "anthropic_api_kei": [3, 5, 14, 16], "anyth": [5, 12], "api": [0, 1, 4, 5, 8, 9, 12, 13, 14, 15, 16, 17], "api2": 8, "api_kei": [5, 16], "app": [8, 17], "appear": 17, "appl": 10, "appli": [1, 6, 7, 8, 10, 12, 14], "applic": [0, 5], "appropri": 17, "approv": 1, "ar": [1, 5, 6, 7, 8, 9, 10, 13, 14, 16, 17], "architectur": [0, 1, 4, 10], "argument": 7, "arm64": 10, "assign": 7, "assist": 5, "associ": 9, "attach": [7, 13], "attempt": [1, 17], "audit": [1, 9], "auth": 0, "authent": [5, 17], "auto": [7, 13, 14], "automat": [0, 3, 9, 10, 13, 17], "autonom": [1, 4], "avail": [7, 10, 12, 14], "avoid": 15, "awar": 0, "az764295": 8, "back": [7, 9, 12], "backend": [0, 1, 4, 5, 6, 7], "background": [7, 13], "bare": 7, "base": [0, 3, 10, 12, 14, 17], "base_url": 5, "bash": [7, 8, 17], "been": 17, "befor": [0, 3, 5, 7, 9, 10, 13, 15, 17], "begin": 3, "behav": 13, "behavior": [1, 9, 17], "behind": 6, "being": 14, "belong": 5, "below": [1, 7, 9, 17], "best_effort": [8, 9, 10, 14, 17], "between": [13, 17], "bin": [3, 8, 9, 14, 15, 17], "binari": [0, 8, 14, 15, 17], "blob": 8, "block": [0, 1, 7, 9, 13, 14, 15, 17], "bookworm": 10, "bool": 9, "bootstrap": [7, 10, 13], "both": [0, 7, 8, 14, 17], "boundari": 0, "box": [8, 14], "bravo": 15, "breakdown": [14, 15], "brev": 3, "brevlab": 3, "bring": 1, "broad": 9, "broker": 0, "browser": 17, "build": [7, 8, 10, 12, 13], "built": [1, 3, 12, 13, 16], "bundl": [3, 10, 12, 13, 14], "call": [0, 1, 4, 5, 6, 7, 8, 10, 14, 15, 16], "can": [0, 1, 3, 5, 8, 9, 12, 13, 14, 15, 16, 17], "cannot": [16, 17], "capabl": [1, 4], "case": [0, 17], "catalog": [3, 5, 8, 13, 14, 16], "categori": 9, "caus": [13, 17], "chang": [0, 2, 5, 6, 9, 15, 17], "charact": 9, "chart": 10, "chat": [5, 6], "check": [0, 7, 13, 14, 15], "choos": [3, 5, 17], "ci_job_token": 16, "class": 16, "classic": 17, "claud": [1, 3, 4, 7, 8, 9, 10, 13, 14, 15, 16], "claude_api_kei": 16, "claude_cod": 17, "cli": [0, 1, 2, 4, 5, 10, 12, 13, 15, 16, 17], "client": 5, "clone": [0, 8, 17], "cloud": 1, "cluster": [0, 7, 10, 13, 16, 17], "clutter": 13, "code": [0, 1, 3, 4, 5, 6, 8, 10, 12, 13, 14, 15, 16], "codex": [3, 4, 7, 8, 10, 14, 16], "com": [3, 6, 8, 9, 12, 13, 14, 15, 17], "combin": [1, 9, 13, 15], "come": 6, "command": [3, 4, 5, 10, 12, 13, 14, 15, 16], "common": [8, 14], "commun": [1, 3, 4, 7, 10, 14, 16], "compar": 17, "compat": [5, 6, 9, 14, 17], "complet": [5, 6, 8, 9, 13, 14, 16, 17], "complianc": 1, "compon": [1, 9, 10, 13], "comput": 0, "concept": 4, "config": [7, 13], "configur": [0, 3, 4, 6, 7, 8, 9, 12, 14, 17], "confin": 1, "confirm": [5, 15, 17], "connect": [0, 1, 5, 7, 8, 9, 14, 17], "consid": 12, "consist": 5, "consol": 3, "constrain": 1, "constraint": [0, 9], "contain": [0, 3, 7, 8, 9, 12, 13, 17], "container": 1, "content": [5, 17], "context": [0, 1, 17], "continu": [0, 3, 6, 14], "contribut": 13, "control": [0, 5, 6, 7, 9, 10, 12, 13, 14, 15, 16], "convers": 17, "coordin": 0, "copi": [3, 17], "core": 8, "correct": 17, "correctli": 5, "cost": 0, "count": 7, "cover": [2, 5, 14, 17], "coverag": [8, 10, 14], "creat": [0, 1, 2, 4, 8, 10, 12, 14, 15, 17], "creation": [1, 7, 9, 10, 13, 14, 15, 17], "credenti": [0, 1, 2, 3, 4, 5, 6, 7, 12, 13, 14, 15, 17], "curl": [5, 8, 14, 17], "current": [5, 7, 9, 15, 16], "cursor": [7, 8, 13, 17], "custom": [1, 2, 4, 8, 12, 14, 16], "d": [5, 7], "danger": [1, 10, 14], "dashboard": [7, 8, 13, 15, 17], "data": [1, 4, 7, 12, 14, 17], "debian": 10, "decis": [0, 7, 13, 17], "declar": [1, 4, 8, 9], "decrypt": [0, 9, 15], "deeper": 1, "default": [1, 7, 9, 10, 12, 15, 17], "defens": [0, 1], "defin": [6, 8, 9, 12, 14, 16], "definit": [0, 3, 12, 15], "delet": [7, 14, 16, 17], "demonstr": 17, "deni": [0, 1, 6, 8, 13, 14, 17], "denial": 15, "depend": [6, 17], "deploi": [0, 3, 7, 8], "deploy": [1, 7], "depth": [0, 1, 17], "describ": [0, 12, 15], "descript": [1, 5, 7, 9, 12, 14], "design": [1, 12, 17], "desktop": [3, 10], "destin": [0, 1, 8, 9, 14, 15], "destroi": [7, 9], "detail": [1, 2, 4, 5, 6, 7, 10, 13, 14, 17], "detect": 16, "dev": [8, 9, 12, 13, 17], "develop": [1, 8], "dgx": [0, 3], "diagnos": 13, "differ": 9, "dir": [12, 13], "directli": [0, 5, 6, 12, 13, 16], "directori": [7, 9, 12, 13], "disabl": 8, "disallow": 9, "discov": [7, 16], "discoveri": 6, "disk": [9, 12, 14], "displai": 9, "distinct": 7, "do": [6, 16, 17], "docker": [0, 3, 7, 8, 10, 13], "dockerfil": [7, 12, 13], "doctor": 7, "document": [7, 9], "doe": [5, 16], "domain": 1, "done": 17, "down": [0, 14], "download": [7, 8, 13, 17], "dst_host": 17, "dst_port": 17, "dummi": 5, "dure": [10, 14], "dynam": [9, 14, 17], "e": [7, 14], "each": [0, 3, 7, 8, 9, 12, 14, 15, 16, 17], "edit": [15, 17], "editor": 7, "effect": [9, 17], "egress": 0, "either": 9, "elev": 14, "els": 12, "empti": 5, "enabl": [0, 7, 8, 9, 13, 15, 17], "encrypt": 9, "end": [4, 5, 12, 13, 15], "endpoint": [0, 1, 3, 6, 7, 8, 14, 15, 17], "enforc": [0, 1, 2, 3, 9, 10, 14, 15, 17], "engin": [0, 10, 14, 17], "enterpris": 1, "entiti": 16, "entri": [7, 8, 13, 14, 15, 17], "entrypoint": 12, "env": 7, "environ": [1, 3, 4, 5, 10, 12, 13, 14, 15, 16, 17], "error": [8, 13, 14, 17], "escal": 1, "escap": 9, "especi": 13, "etc": [8, 9, 14, 17], "evalu": 6, "even": 13, "event": 13, "everi": [0, 5, 6, 7, 9, 14, 15, 16], "everyth": 7, "ex": 8, "exact": 17, "exactli": 4, "exampl": [0, 3, 7, 12, 13, 14, 17], "exce": 9, "exclus": 9, "exec": 7, "execut": [1, 2, 4, 7, 8, 9, 14], "exfiltr": [1, 4, 14], "exist": [5, 7, 12, 13, 16, 17], "exit": [7, 13, 15, 17], "expect": 17, "experi": 17, "explain": [13, 17], "explicit": 1, "explicitli": [7, 9, 13, 15], "explor": [1, 5, 12, 13, 15, 16], "export": [15, 17], "expos": 6, "exposur": 14, "extend": 17, "extens": 8, "extern": [0, 1, 5, 6, 16], "f": 7, "fail": [9, 10, 15, 17], "failur": [1, 17], "fall": [7, 9], "fastest": 16, "featur": 8, "fetch": [7, 8, 17], "field": [5, 7, 9, 14, 15, 16], "file": [1, 4, 7, 8, 9, 12, 14, 15, 17], "filesystem": [0, 1, 8, 10, 14], "filesystem_polici": [9, 14, 17], "filter": [7, 10, 13, 14], "final": 13, "find": [3, 16, 17], "fine": 9, "finish": 17, "first": [0, 1, 2, 4, 10, 13, 14, 16], "fish": 7, "fix": 15, "flag": [3, 8, 12, 13, 15, 16, 17], "flow": 5, "follow": [0, 1, 3, 6, 7, 8, 9, 10, 12, 13, 14, 15, 16, 17], "forc": 7, "fork": 12, "format": 7, "forward": [0, 5, 6, 9, 13], "foundat": 12, "four": 0, "free": 17, "from": [0, 3, 4, 6, 7, 10, 12, 14, 15], "full": [7, 8, 10, 13, 14, 15, 17], "fulli": 13, "function": 14, "g": [7, 14], "gallerycdn": [8, 17], "gatewai": [0, 2, 5, 6, 10, 13], "gener": [5, 6, 7, 12, 13, 16], "get": [3, 5, 6, 8, 9, 13, 15, 16, 17], "gh": [8, 9, 15, 16, 17], "gh_token": 16, "ghcr": 10, "gid": 9, "git": [0, 8, 9, 17], "github": [2, 4, 7, 8, 9, 13, 15, 16], "github_api": 17, "github_git": 17, "github_repo": 15, "github_rest_api": [9, 17], "github_ssh_over_http": 17, "github_token": [16, 17], "githubusercont": [8, 17], "gitlab": [7, 16], "gitlab_token": 16, "give": [1, 17], "glab": 16, "glab_token": 16, "glob": 9, "global": 7, "go": [1, 5], "goe": 14, "govern": 4, "gpu": [7, 13], "grain": 9, "grant": [8, 9, 17], "granular": 15, "graphql": [15, 17], "greater": 17, "group": [7, 8, 9, 14], "grow": 12, "guid": [4, 17], "guidelin": 12, "h": 5, "ha": [9, 14, 17], "handl": [6, 9], "happen": 13, "hard_requir": [9, 10], "hash": 15, "have": [3, 12, 13, 17], "head": [7, 9, 15], "header": 15, "health": 7, "healthi": 3, "hello": 5, "hello_world": 17, "helm": 10, "help": 5, "here": [7, 17], "hierarchi": 7, "highest": [8, 9, 10, 14], "hint": [7, 14], "hit": 3, "hold": 5, "host": [0, 1, 3, 4, 5, 6, 7, 8, 9, 10, 13, 14, 15, 17], "hostnam": 9, "hot": [1, 6, 9, 14, 15, 17], "how": [1, 9, 12, 13, 14, 17], "http": [0, 3, 5, 6, 7, 8, 9, 14, 15, 17], "human": 7, "i": [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 12, 13, 14, 15, 16, 17], "id": [5, 7], "ident": [0, 1, 9, 17], "identifi": [0, 7, 8, 9, 17], "ignor": 5, "imag": [1, 3, 4, 7, 12, 14], "immedi": 17, "impli": 7, "import": 5, "improv": 2, "inaccess": 9, "includ": [0, 7, 8, 13, 14, 17], "include_workdir": [9, 17], "indic": 17, "individu": [9, 13], "infer": [0, 1, 4, 8, 13, 14, 15, 17], "info": [7, 8, 9, 17], "inform": [7, 13], "infrastructur": [0, 4], "initi": 15, "inject": [0, 6, 7, 13, 14, 16, 17], "input": 5, "insid": [0, 3, 5, 6, 7, 8, 9, 10, 17], "inspect": [7, 9, 14, 15, 16, 17], "inspect_for_infer": 13, "instal": [0, 1, 4, 7, 8, 10, 13, 14, 15, 17], "instanc": 3, "instead": [5, 13, 17], "instruct": [5, 17], "integ": 9, "integr": [8, 16, 17], "intel": 10, "intend": 9, "interact": [7, 17], "intercept": [0, 5, 13, 17], "intern": 1, "introduc": 2, "invalid_argu": 9, "invok": 12, "io": [8, 10, 17], "ip": 9, "isol": [0, 1, 2, 7, 10, 14], "issu": [7, 8, 15, 17], "iter": [13, 17], "its": [0, 4, 7, 8, 9, 17], "j": [7, 10], "job": 17, "json": 5, "k": 7, "k3": [0, 10], "k3s1": 10, "k9": 7, "keep": [0, 1, 4, 7, 13, 15, 17], "kei": [1, 3, 6, 7, 9, 12, 13, 14], "kernel": [0, 1, 2, 8, 9, 14], "known": 16, "kubectl": 7, "kubernet": [0, 10], "l4": 8, "l7_action": 17, "l7_decis": 17, "l7_deny_reason": 17, "l7_protocol": 17, "l7_target": 17, "label": 13, "landlock": [1, 8, 10, 14, 17], "last": 7, "later": [3, 13, 17], "latest": [2, 10, 12, 13], "launch": [3, 7, 12, 13, 14, 16, 17], "launchabl": 3, "layer": [0, 14], "learn": [0, 1, 4, 15, 17], "let": 16, "level": [1, 2, 7, 10, 13, 14, 15, 17], "lib": [8, 9, 14, 17], "lifecycl": [0, 13], "like": [6, 9, 13], "limit": 7, "line": 7, "link": [3, 17], "linux": 10, "list": [7, 8, 9, 10, 14, 15, 16, 17], "live": [7, 13, 15, 17], "llm": [0, 8], "load": [9, 15, 17], "local": [0, 1, 3, 4, 5, 7, 8, 9, 12, 13, 14, 15, 17], "locat": 0, "lock": [1, 9, 14, 17], "log": [0, 8, 9, 14, 15], "logic": 9, "longer": 13, "look": [13, 16, 17], "lookup": 8, "lsm": [9, 10, 14], "machin": [3, 13], "maco": 10, "mai": [9, 14], "main": 13, "make": [1, 3], "manag": [0, 2, 4, 5, 6, 7, 12, 14, 17], "mandatori": 9, "manifest": 10, "manipul": 12, "map": 9, "marketplac": [8, 17], "match": [0, 3, 6, 8, 9, 14], "materi": 1, "matter": 17, "md": 12, "messag": [5, 6], "metadata": [7, 8, 15], "method": [0, 6, 9, 14, 15, 17], "microsoft": [8, 16, 17], "might": [13, 17], "minimum": [10, 12], "miss": 15, "mitig": 1, "mode": [1, 7, 9, 10], "model": [0, 1, 5, 6, 7, 16], "modern": 10, "modifi": [9, 15], "modul": 10, "monitor": [7, 15], "more": [2, 4, 7, 14, 16], "most": 1, "move": 14, "msecnd": [8, 17], "multi": 10, "multipl": [7, 14], "must": [8, 9, 10, 12, 13, 14, 17], "mutat": 8, "mutual": 9, "my": [5, 12, 13, 14, 15, 16, 17], "my_api": 14, "n": 7, "name": [5, 7, 9, 10, 12, 13, 14, 15, 16, 17], "namespac": 14, "nano": 5, "navig": 7, "need": [4, 6, 12, 13, 15, 16, 17], "neither": 9, "nemotron": 5, "net": [8, 17], "network": [0, 1, 4, 5, 6, 8, 13, 15, 17], "network_polici": [5, 6, 9, 14, 15, 17], "new": [7, 15, 17], "node": [8, 9, 10, 17], "node_modul": 8, "non": 8, "none": [8, 16], "nor": 9, "normal": 9, "note": [8, 10, 14], "noth": 4, "now": 17, "npm": [9, 10], "npm_registri": 9, "npmj": [8, 9], "null": [8, 9, 17], "number": 9, "nvidia": [3, 5, 6, 7, 8, 10, 13, 14, 16, 17], "nvidia_api_kei": [5, 16], "nvidia_infer": 17, "o": [9, 10, 13], "object": [8, 17], "observ": 17, "omit": [7, 9], "omutbound": 13, "onc": 17, "one": [0, 5, 6, 7, 9, 12, 14, 16, 17], "ones": 13, "onli": [0, 1, 5, 6, 7, 8, 9, 14, 15, 17], "open": [0, 1, 7, 12, 14, 17], "openai": [5, 6, 8, 14, 16], "openai_api_kei": [3, 5, 14, 16], "openai_base_url": 5, "openclaw": [1, 3, 4, 12, 13, 14], "opencod": [1, 3, 4, 7, 8, 10, 14, 16, 17], "opencode_api_kei": 16, "openrouter_api_kei": [3, 16], "openshel": [5, 6, 8, 9, 10, 12, 13, 14, 15, 16, 17], "openshell_cluster_imag": 10, "openshell_community_registri": 10, "openshell_gatewai": 7, "openshell_sandbox_polici": [7, 15], "oper": [7, 17], "option": [7, 9, 12, 14, 15], "orchestr": 14, "org": [8, 9, 15, 17], "org_nam": 15, "organ": 17, "origin": [0, 6], "other": [1, 3, 6, 8], "otherwis": [13, 14], "out": [8, 14], "outbound": [0, 1, 6, 8, 14, 17], "outlin": [15, 17], "outlook": [7, 16], "output": [7, 9, 13, 17], "outsid": [1, 17], "over": [1, 3, 8, 17], "overli": 9, "overrid": [7, 10], "overview": 4, "own": [1, 12, 13, 17], "pack": [8, 9, 17], "packag": [0, 1, 3, 8, 12, 13, 17], "page": [2, 3, 5, 10, 13, 15, 17], "pair": [8, 14], "partial": [8, 14], "particular": 12, "pass": [0, 7, 12, 14, 15, 16], "passthrough": [8, 9, 15], "past": 17, "pat": 17, "patch": [9, 15], "path": [0, 1, 6, 7, 8, 9, 12, 13, 14, 15, 17], "pattern": [1, 5, 9], "payload": [14, 15], "per": [0, 9, 15, 17], "perman": 7, "permiss": [4, 9, 17], "permit": [9, 17], "person": 17, "perspect": 17, "phase": [13, 14], "pick": [3, 6], "pid": 8, "pip": [3, 4, 8, 10, 15, 17], "pipe": 7, "plan": 15, "plane": [0, 10], "platform": [0, 8, 17], "pod": [0, 7], "point": [5, 12, 13], "polici": [0, 1, 2, 3, 4, 10, 12, 13, 16], "port": [0, 3, 8, 9, 13, 14, 15, 17], "possibl": 17, "post": [6, 8, 9, 15, 17], "pr": 8, "pre": [3, 8, 12, 13, 14, 16], "preconfigur": 12, "preserv": [1, 7], "press": 7, "prevent": [1, 4, 14], "previou": 17, "previous": 17, "print": [7, 17], "privaci": [0, 1, 5, 6, 14], "privat": [1, 4, 14], "privileg": [1, 14], "problem": 17, "proc": [8, 9, 17], "proceed": 17, "process": [0, 1, 8, 12, 13, 14, 17], "prod": 5, "prompt": [1, 3, 17], "properli": 17, "properti": 6, "protect": [0, 4, 14], "protocol": [9, 14, 15, 17], "provid": [1, 3, 4, 6, 8, 9, 12, 13, 14, 15, 17], "provis": [0, 14], "proxi": [0, 8, 9, 13, 14, 15, 17], "prss": [8, 17], "publish": [10, 12], "pull": [3, 8, 10, 12, 13, 15, 17], "purg": [13, 14], "purpos": [10, 12, 13], "push": [8, 15], "put": [9, 17], "py": 17, "pypi": [8, 15, 17], "python": [3, 8, 10, 17], "python3": [8, 17], "pythonhost": [8, 15, 17], "q": 7, "queri": [0, 14, 17], "quickstart": [0, 1, 4, 17], "quit": 7, "rancher": 10, "rang": 1, "rather": 6, "raw": [8, 17], "re": 3, "reach": [5, 8, 9, 14, 15, 17], "reachabl": [5, 9], "read": [1, 5, 7, 8, 9, 14, 15, 16, 17], "read_onli": [9, 14, 17], "read_writ": [9, 14, 17], "readabl": 7, "readi": [12, 14], "readm": [12, 17], "real": 13, "reason": [5, 15, 17], "receiv": [8, 16, 17], "recogn": [16, 17], "recommend": [10, 17], "reconnect": [13, 17], "record": [5, 6, 7], "recreat": [6, 9, 16, 17], "ref": [8, 9, 17], "refer": [0, 1, 2, 4, 5, 6, 10, 12, 13, 14, 15, 16, 17], "refresh": 6, "refus": 13, "regist": 7, "registri": [3, 8, 9, 10, 12, 13], "reject": 9, "relat": [5, 12, 13, 15, 16, 17], "releas": [8, 13, 14], "relev": 9, "reload": [1, 9, 14, 15, 17], "remain": 17, "remot": [0, 7, 8, 17], "remov": [7, 13], "repeat": [5, 7, 15], "replac": [7, 15, 17], "repo": [4, 8, 15, 17], "report": [8, 17], "repositori": [8, 12, 17], "request": [5, 6, 7, 8, 9, 12, 13, 14, 17], "requir": [5, 7, 8, 9, 14, 16, 17], "rerout": [1, 14], "resolv": [8, 12, 13], "resourc": [13, 14, 17], "respons": [5, 6, 17], "rest": [0, 8, 9, 14, 15, 17], "restart": [9, 17], "restrict": [1, 9, 10, 14, 17], "retriev": 13, "return": [0, 13, 17], "reus": 15, "reusabl": 1, "review": [1, 12, 15], "revis": [15, 17], "rewrit": 5, "role": [0, 5], "root": [9, 17], "rout": [0, 1, 3, 4, 8, 14], "router": [0, 5, 6], "rule": [0, 5, 6, 8, 12, 15, 17], "run": [0, 1, 2, 3, 4, 5, 7, 8, 9, 10, 12, 13, 14, 16, 17], "run_as_group": [9, 14, 17], "run_as_us": [9, 14, 17], "runtim": [0, 1, 4, 7, 13, 14, 16, 17], "safe": [4, 14], "same": [0, 1, 5, 6, 8, 14, 17], "sampl": 17, "sandbox": [0, 1, 2, 4, 6, 8, 9], "save": [5, 17], "schema": [4, 14, 15, 16, 17], "scope": [5, 9, 17], "scratch": 17, "script": [7, 12, 17], "sdg": 12, "seccomp": [1, 10, 14], "secret": [1, 7], "section": [8, 14, 15, 17], "secur": [0, 1, 3, 5, 6, 10], "see": [5, 7, 17], "select": [7, 17], "self": [1, 4, 5, 17], "send": 1, "sensit": [0, 1], "sentri": [8, 17], "separ": [10, 16], "serv": 5, "server": [5, 8, 9, 10, 17], "servic": [0, 2, 16], "session": [7, 8, 13, 17], "set": [3, 4, 6, 8, 9, 10, 12, 13, 14, 15, 16], "setuid": [1, 14], "sever": [10, 13], "sh": [7, 8], "shareabl": 3, "shell": 16, "ship": [10, 14], "should": [5, 6], "show": [3, 7, 8, 13, 15, 17], "sign": 17, "silicon": 10, "similar": 17, "simpl": [15, 17], "simul": 12, "sinc": 13, "singl": [3, 7, 12, 13, 17], "sk": 16, "skill": [3, 12], "skip": 3, "smart": [8, 17], "so": [0, 1, 8, 12, 16, 17], "socket": 8, "someth": 14, "sourc": [1, 3, 7, 13, 14, 15], "spark": [0, 3], "special": 6, "specif": [7, 13, 17], "specifi": [7, 13, 16, 17], "split": 14, "spot": 13, "src": 13, "ssh": [1, 3, 7], "ssid": [0, 3], "stai": [5, 6], "standalon": 8, "start": [0, 3, 7, 9, 10, 13, 17], "startup": [7, 10, 12], "state": [0, 7], "static": [9, 14, 17], "statsig": [8, 17], "statu": [0, 3, 10, 13, 15, 17], "step": 3, "stop": [7, 13], "storag": 9, "store": 16, "stream": [7, 13, 14, 15, 17], "string": 9, "strip": [0, 6, 15], "structur": [15, 17], "subcommand": 7, "subdomain": 9, "submiss": 12, "subsequ": [3, 7], "success": 5, "successfulli": 17, "sudo": [1, 14], "suffici": 17, "summar": [1, 14, 17], "supervis": 0, "suppli": [5, 6, 12, 13, 14, 16], "support": [1, 5, 8, 9, 12], "sure": 3, "switch": 5, "sync": [3, 14], "syntax": 9, "synthet": 12, "syscal": 1, "system": [0, 4, 9, 10, 12, 14], "tab": [3, 7, 17], "tabl": [0, 1, 8, 10, 14, 17], "tail": [7, 13, 15], "tailor": 3, "take": [9, 17], "target": [7, 17], "tcp": [8, 9, 14, 15], "team": 1, "telemetri": 8, "term": [7, 13, 15, 17], "termin": [0, 8, 9, 13, 14, 15, 17], "than": 6, "theft": 1, "thei": [1, 4, 13, 17], "them": [1, 9, 14, 16], "thi": [1, 2, 3, 5, 7, 9, 10, 13, 14, 15, 16, 17], "thing": [14, 17], "those": 14, "threat": 1, "three": [0, 14], "through": [0, 3, 5, 6, 8, 9, 10, 13, 14, 17], "time": [7, 9, 10, 13, 15], "timeout": 15, "tl": [0, 8, 9, 14, 15, 17], "tmp": [8, 9, 14, 17], "togeth": 0, "token": [12, 13, 14, 16], "tool": [12, 16], "topic": [1, 5, 12, 13, 15, 16, 17], "torn": 14, "total": 9, "track": 2, "tradeoff": 1, "traffic": [0, 1, 4, 5, 6, 8, 9, 17], "trail": [7, 13, 14, 16], "travers": 9, "treat": [1, 6], "tree": 9, "triag": 15, "trigger": 13, "troubleshoot": 7, "true": [9, 17], "trust": 17, "try": [13, 17], "tunnel": 3, "tutori": [4, 13, 17], "two": [3, 4, 5, 6, 10, 17], "type": [3, 5, 7, 9, 17], "typic": [9, 16], "ubuntu": 10, "uid": 9, "unapprov": 1, "unauthor": [1, 4, 14], "unavail": [9, 10], "unchang": 17, "uncontrol": 4, "under": [1, 3, 7, 9, 12, 14], "understand": [1, 5], "unexpectedli": 13, "unix": 9, "unlist": 17, "unprivileg": [1, 14], "unrestrict": 1, "untest": 10, "until": 17, "up": [1, 3, 4, 6, 12, 13, 14, 15, 16], "updat": [6, 8, 9, 15, 16], "upload": [1, 7, 8, 9, 13, 17], "upstream": 5, "urandom": [8, 9, 17], "url": [3, 7, 9], "us": [0, 3, 7, 8, 9, 10, 13, 14, 15, 16, 17], "usag": [1, 7], "user": [0, 5, 7, 8, 9, 14, 16], "usernam": [0, 3, 15, 17], "usr": [8, 9, 14, 15, 17], "uv": [3, 4, 8, 10, 15, 17], "v": [8, 13, 14, 17], "v1": [5, 6, 10], "valid": [9, 15], "valu": [5, 7, 8, 9, 16], "var": [8, 17], "vari": 17, "variabl": [4, 10, 15, 16, 17], "venv": [3, 8, 17], "verbos": 7, "verifi": [15, 17], "version": [1, 5, 7, 14, 15, 17], "via": [8, 10], "view": [5, 7, 14, 15, 16], "violat": 9, "virtual": 3, "visualstudio": [8, 17], "vm": 10, "vo": [8, 17], "vsasset": [8, 17], "vscode": [7, 8, 9, 13, 17], "wa": [5, 7], "wai": [6, 16], "wait": [15, 17], "walk": [13, 17], "walkthrough": 15, "want": [5, 12, 13, 17], "warn": 13, "went": 14, "wget": [8, 17], "what": [1, 9, 13, 14, 15, 16, 17], "when": [1, 3, 5, 6, 7, 8, 9, 10, 12, 13, 14, 15, 16, 17], "whenev": 15, "where": [1, 9, 17], "whether": [9, 17], "which": [0, 7, 9, 15, 17], "while": 1, "whose": [12, 13], "wildcard": 9, "window": [8, 10, 13], "without": [1, 5, 6, 7, 8, 9, 13, 14, 15, 16, 17], "word": 17, "work": [8, 9, 13, 14, 17], "workdir": 8, "workflow": [12, 13, 14, 15, 17], "workspac": [13, 17], "workstat": 0, "would": 9, "write": [1, 8, 9, 12, 14, 15, 17], "wrong": 14, "wsl": 10, "x86_64": 10, "yaml": [1, 7, 8, 9, 12, 13, 15, 16, 17], "ye": [3, 8, 9], "you": [3, 5, 7, 8, 12, 13, 14, 15, 16, 17], "your": [0, 1, 4, 5, 7, 12, 14, 15, 16], "yourself": 16, "zero": 3, "zsh": 7, "zshrc": 7}, "titles": ["How OpenShell Works", "Overview of NVIDIA OpenShell", "NVIDIA OpenShell Release Notes", "Quickstart", "NVIDIA OpenShell", "Configure Inference Routing", "About Inference Routing", "CLI Reference", "Default Policy Reference", "Policy Schema Reference", "Support Matrix", "License", "Community Sandboxes", "Create and Manage Sandboxes", "About Sandboxes", "Customize Sandbox Policies", "Providers", "Set Up a Sandbox of Claude Code with a Custom GitHub Policy"], "titleterms": {"0": 2, "1": [2, 5], "2": 5, "3": 5, "4": 5, "It": 5, "With": 16, "about": [6, 14], "access": [9, 14], "activ": 5, "agent": [8, 10, 14], "api": 6, "appli": [15, 17], "ar": 12, "ask": 17, "attach": 16, "auto": 16, "bare": 16, "binari": 9, "block": 8, "built": [7, 14], "case": 1, "catalog": 12, "check": 17, "claud": 17, "clean": 17, "cli": [3, 7], "code": 17, "command": 7, "common": 1, "commun": [12, 13], "compat": [8, 10], "complet": 7, "compon": 0, "config": 5, "configur": 5, "connect": [3, 13], "contain": 10, "contribut": 12, "control": 1, "creat": [3, 5, 7, 13, 16], "credenti": 16, "current": 12, "custom": [13, 15, 17], "debug": 15, "default": [8, 14], "delet": 13, "deni": 15, "denial": 17, "deploy": 0, "diagnos": 17, "diagnost": 7, "discoveri": 16, "editor": 13, "endpoint": [5, 9], "entri": 9, "environ": 7, "exampl": [9, 15], "exist": 1, "explicit": 16, "explor": 4, "file": 13, "filesystem": 9, "first": 3, "flag": 7, "flow": 0, "form": 16, "forward": 7, "from": [5, 13, 16, 17], "full": 9, "gatewai": [3, 7], "gener": 17, "get": [4, 7], "github": 17, "glanc": 1, "help": 7, "highlight": 2, "how": [0, 6], "imag": [10, 13], "infer": [5, 6, 7], "inspect": 13, "instal": 3, "interact": 13, "iter": 15, "kei": 16, "kernel": 10, "landlock": 9, "layer": 1, "level": 9, "licens": 11, "lifecycl": 14, "list": 13, "local": [6, 16], "log": [7, 13, 17], "machin": 17, "manag": [13, 16], "matrix": 10, "mode": 0, "monitor": 13, "network": [9, 14], "next": [0, 1, 5, 6, 12, 13, 14, 15, 16, 17], "note": 2, "nvidia": [1, 2, 4], "object": 9, "open": 13, "openshel": [0, 1, 2, 3, 4, 7], "option": 3, "other": 12, "overview": 1, "part": 5, "pattern": 6, "platform": 10, "polici": [7, 8, 9, 14, 15, 17], "port": 7, "prerequisit": [3, 10, 17], "process": 9, "protect": 1, "provid": [5, 7, 16], "push": 17, "quick": 15, "quickstart": 3, "refer": [7, 8, 9], "releas": 2, "remot": [3, 13], "request": [0, 15], "requir": 10, "retri": 17, "review": 17, "risk": 1, "rout": [5, 6], "rule": [9, 14], "run": 15, "runtim": 10, "sandbox": [3, 5, 7, 10, 12, 13, 14, 15, 16, 17], "schema": 9, "set": [5, 7, 17], "shell": 7, "shortcut": 16, "softwar": 10, "sourc": 12, "ssh": 13, "start": [4, 15], "statu": 7, "step": [0, 1, 5, 6, 12, 13, 14, 15, 16, 17], "structur": [9, 14], "support": [6, 10, 14, 16], "termin": 7, "token": 17, "top": 9, "transfer": 13, "tree": 7, "type": 16, "up": 17, "updat": [5, 7, 17], "us": [1, 5, 12], "variabl": 7, "verifi": 5, "version": [9, 10], "view": [13, 17], "what": 12, "why": 1, "work": [0, 6], "your": [3, 13, 17]}})
\ No newline at end of file
diff --git a/pr-preview/pr-257/tutorials/github-sandbox.html b/pr-preview/pr-257/tutorials/github-sandbox.html
index f99fd7475..7f607e901 100644
--- a/pr-preview/pr-257/tutorials/github-sandbox.html
+++ b/pr-preview/pr-257/tutorials/github-sandbox.html
@@ -387,7 +387,7 @@
 <p aria-level="2" class="caption" role="heading"><span class="caption-text">Get Started</span></p>
 <ul class="current nav bd-sidenav">
 <li class="toctree-l1"><a class="reference internal" href="../get-started/quickstart.html">Quickstart</a></li>
-<li class="toctree-l1 current active"><a class="current reference internal" href="#">Tutorial: GitHub Policy Iteration</a></li>
+<li class="toctree-l1 current active"><a class="current reference internal" href="#">GitHub Policy Tutorial</a></li>
 </ul>
 <p aria-level="2" class="caption" role="heading"><span class="caption-text">Sandboxes</span></p>
 <ul class="nav bd-sidenav">
@@ -469,7 +469,8 @@
 -->
 <section class="tex2jax_ignore mathjax_ignore" id="set-up-a-sandbox-of-claude-code-with-a-custom-github-policy">
 <h1>Set Up a Sandbox of Claude Code with a Custom GitHub Policy<a class="headerlink" href="#set-up-a-sandbox-of-claude-code-with-a-custom-github-policy" title="Link to this heading">#</a></h1>
-<p>This tutorial walks through the iterative policy workflow. You launch a sandbox, ask Claude Code to push code to GitHub, get blocked by the default network policy, diagnose the denial from two angles — the OpenShell Terminal on your laptop and the sandbox logs from inside — and then apply a custom policy to fix it, all without recreating the sandbox.</p>
+<p>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.</p>
 <p>After completing this tutorial, you will have:</p>
 <ul class="simple">
 <li><p>A running sandbox with Claude Code that can push to a GitHub repository.</p></li>
@@ -478,68 +479,70 @@
 </ul>
 <div class="admonition note">
 <p class="admonition-title">Note</p>
-<p>This tutorial shows example prompts and responses from Claude Code. The exact wording you see may differ between sessions — use the examples as a guide for the type of interaction, not as expected output.</p>
+<p>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.</p>
 </div>
 <section id="prerequisites">
 <h2>Prerequisites<a class="headerlink" href="#prerequisites" title="Link to this heading">#</a></h2>
 <p>This tutorial requires the following:</p>
 <ul class="simple">
-<li><p>Completed the <a class="reference internal" href="../get-started/quickstart.html"><span class="doc">Quickstart</span></a> tutorial.</p></li>
-<li><p>A GitHub personal access token (PAT) with <code class="docutils literal notranslate"><span class="pre">repo</span></code> scope. To create one, go to <a class="reference external" href="https://github.com/settings/tokens" rel="noreferer noopener" target="_blank">GitHub Settings &gt; Developer settings &gt; Personal access tokens</a>, select <strong>Generate new token (classic)</strong>, check the <code class="docutils literal notranslate"><span class="pre">repo</span></code> scope, and copy the token.</p></li>
-<li><p>Your own <a class="reference external" href="https://console.anthropic.com/" rel="noreferer noopener" target="_blank">Anthropic account</a> for Claude Code. OpenShell provides the sandbox, not the agent — you need your own account to log in to Claude Code.</p></li>
-<li><p>A public GitHub repository you own (used as the push target). A scratch or test repository works well — the tutorial pushes a small file to it. You can <a class="reference external" href="https://github.com/new" rel="noreferer noopener" target="_blank">create a new repository</a> with a README if you do not have one handy.</p></li>
+<li><p>A working OpenShell installation. Complete the <a class="reference internal" href="../get-started/quickstart.html"><span class="doc">Quickstart</span></a> before proceeding.</p></li>
+<li><p>A GitHub personal access token (PAT) with <code class="docutils literal notranslate"><span class="pre">repo</span></code> scope. Generate one from the <a class="reference external" href="https://github.com/settings/tokens" rel="noreferer noopener" target="_blank">GitHub personal access token settings page</a> by selecting <strong>Generate new token (classic)</strong> and enabling the <code class="docutils literal notranslate"><span class="pre">repo</span></code> scope.</p></li>
+<li><p>An <a class="reference external" href="https://console.anthropic.com/" rel="noreferer noopener" target="_blank">Anthropic account</a> with access to Claude Code. OpenShell provides the sandbox runtime, not the agent. You must authenticate with your own account.</p></li>
+<li><p>A GitHub repository you own to use as the push target. A scratch repository is sufficient. You can <a class="reference external" href="https://github.com/new" rel="noreferer noopener" target="_blank">create one</a> with a README if needed.</p></li>
 </ul>
-<div class="admonition important">
-<p class="admonition-title">Important</p>
-<p>This tutorial uses two terminals throughout:</p>
+<p>This tutorial uses two terminals to demonstrate the iterative policy workflow:</p>
 <ul class="simple">
-<li><p><strong>Terminal 1 (sandbox)</strong> — The terminal where you launch the sandbox. Claude Code runs here. You interact with the agent in this terminal.</p></li>
-<li><p><strong>Terminal 2 (laptop)</strong> — A separate terminal on your laptop. You use this for <code class="docutils literal notranslate"><span class="pre">openshell</span> <span class="pre">term</span></code>, <code class="docutils literal notranslate"><span class="pre">openshell</span> <span class="pre">policy</span> <span class="pre">set</span></code>, and other CLI commands that manage the sandbox from the outside.</p></li>
+<li><p><strong>Terminal 1</strong>: The sandbox terminal. You create the sandbox in this terminal by running <code class="docutils literal notranslate"><span class="pre">openshell</span> <span class="pre">sandbox</span> <span class="pre">create</span></code> and interact with Claude Code inside it.</p></li>
+<li><p><strong>Terminal 2</strong>: A terminal outside the sandbox on your machine. You use this terminal for viewing the sandbox logs with <code class="docutils literal notranslate"><span class="pre">openshell</span> <span class="pre">term</span></code> and applying an updated policy with <code class="docutils literal notranslate"><span class="pre">openshell</span> <span class="pre">policy</span> <span class="pre">set</span></code>.</p></li>
 </ul>
 <p>Each section below indicates which terminal to use.</p>
-</div>
 </section>
-<section id="launch-the-sandbox">
-<h2>Launch the Sandbox<a class="headerlink" href="#launch-the-sandbox" title="Link to this heading">#</a></h2>
-<p><strong>Terminal 1 (sandbox)</strong> — Create a sandbox and start Claude Code. No custom policy is needed yet — the <a class="reference internal" href="../reference/default-policy.html"><span class="doc">default policy</span></a> is applied automatically.</p>
+<section id="set-up-a-sandbox-with-your-github-token">
+<h2>Set Up a Sandbox with Your GitHub Token<a class="headerlink" href="#set-up-a-sandbox-with-your-github-token" title="Link to this heading">#</a></h2>
+<p>Depending on whether you start a new sandbox or use an existing sandbox, choose the appropriate tab and follow the instructions.</p>
 <div class="sd-tab-set docutils">
 <input checked="checked" id="sd-tab-item-0" name="sd-tab-set-0" type="radio">
 <label class="sd-tab-label" for="sd-tab-item-0">
 Starting a new sandbox</label><div class="sd-tab-content docutils">
+<p>In terminal 2, create a new sandbox with Claude Code. The <a class="reference internal" href="../reference/default-policy.html"><span class="doc">default policy</span></a> is applied automatically, which allows read-only access to GitHub.</p>
 <p>Create a <a class="reference internal" href="../sandboxes/providers.html"><span class="doc">credential provider</span></a> that injects your GitHub token into the sandbox automatically. The provider reads <code class="docutils literal notranslate"><span class="pre">GITHUB_TOKEN</span></code> from your host environment and sets it as an environment variable inside the sandbox:</p>
 <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span><span class="nv">GITHUB_TOKEN</span><span class="o">=</span>&lt;your-token&gt;
 <span class="gp">$ </span>openshell<span class="w"> </span>provider<span class="w"> </span>create<span class="w"> </span>--name<span class="w"> </span>my-github<span class="w"> </span>--type<span class="w"> </span>github<span class="w"> </span>--from-existing
 <span class="gp">$ </span>openshell<span class="w"> </span>sandbox<span class="w"> </span>create<span class="w"> </span>--provider<span class="w"> </span>my-github<span class="w"> </span>--keep<span class="w"> </span>--<span class="w"> </span>claude
 </pre></div>
 </div>
+<p>The <code class="docutils literal notranslate"><span class="pre">--keep</span></code> flag keeps the sandbox running after Claude Code exits, so you can apply policy updates later without recreating the environment.</p>
+<p>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 <code class="docutils literal notranslate"><span class="pre">/sandbox</span></code> workspace to allow Claude Code to read and write files.</p>
 </div>
 <input id="sd-tab-item-1" name="sd-tab-set-0" type="radio">
 <label class="sd-tab-label" for="sd-tab-item-1">
 Using an existing sandbox</label><div class="sd-tab-content docutils">
-<p>Connect to a sandbox that is already running and set your GitHub token as an environment variable:</p>
+<p>In terminal 1, connect to a sandbox that is already running and set your GitHub token as an environment variable:</p>
 <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>openshell<span class="w"> </span>sandbox<span class="w"> </span>connect<span class="w"> </span>&lt;sandbox-name&gt;
 <span class="gp">$ </span><span class="nb">export</span><span class="w"> </span><span class="nv">GITHUB_TOKEN</span><span class="o">=</span>&lt;your-token&gt;
 </pre></div>
 </div>
+<p>To find the name of running sandboxes, run <code class="docutils literal notranslate"><span class="pre">openshell</span> <span class="pre">sandbox</span> <span class="pre">list</span></code> in terminal 2.</p>
 </div>
 </div>
-<p>The <code class="docutils literal notranslate"><span class="pre">--keep</span></code> flag keeps the sandbox running after Claude Code exits, so you can apply policy updates later without recreating the environment.</p>
-<p>Claude Code starts inside the sandbox. Log in through your preferred authentication method and trust the <code class="docutils literal notranslate"><span class="pre">/sandbox</span></code> workspace when prompted.</p>
 </section>
 <section id="push-code-to-github">
 <h2>Push Code to GitHub<a class="headerlink" href="#push-code-to-github" title="Link to this heading">#</a></h2>
-<p><strong>Terminal 1 (sandbox)</strong> — Ask Claude Code to write a simple script and push it to your repository:</p>
-<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>Write a hello_world.py script and push it to https://github.com/&lt;org&gt;/&lt;repo&gt;.
-</pre></div>
+<p>In terminal 1, ask Claude Code to write a simple script and push it to your repository. Replace <code class="docutils literal notranslate"><span class="pre">&lt;org&gt;</span></code> with your GitHub organization or username and <code class="docutils literal notranslate"><span class="pre">&lt;repo&gt;</span></code> with your repository name.</p>
+<details class="sd-sphinx-override sd-dropdown sd-card sd-mb-3" open="open">
+<summary class="sd-summary-title sd-card-header">
+<span class="sd-summary-icon"><svg version="1.1" width="1.0em" height="1.0em" class="sd-octicon sd-octicon-terminal" viewBox="0 0 16 16" aria-hidden="true"><path d="M0 2.75C0 1.784.784 1 1.75 1h12.5c.966 0 1.75.784 1.75 1.75v10.5A1.75 1.75 0 0 1 14.25 15H1.75A1.75 1.75 0 0 1 0 13.25Zm1.75-.25a.25.25 0 0 0-.25.25v10.5c0 .138.112.25.25.25h12.5a.25.25 0 0 0 .25-.25V2.75a.25.25 0 0 0-.25-.25ZM7.25 8a.749.749 0 0 1-.22.53l-2.25 2.25a.749.749 0 0 1-1.275-.326.749.749 0 0 1 .215-.734L5.44 8 3.72 6.28a.749.749 0 0 1 .326-1.275.749.749 0 0 1 .734.215l2.25 2.25c.141.14.22.331.22.53Zm1.5 1.5h3a.75.75 0 0 1 0 1.5h-3a.75.75 0 0 1 0-1.5Z"></path></svg></span><span class="sd-summary-text">Prompt</span><span class="sd-summary-state-marker sd-summary-chevron-right"><svg version="1.1" width="1.5em" height="1.5em" class="sd-octicon sd-octicon-chevron-right" viewBox="0 0 24 24" aria-hidden="true"><path d="M8.72 18.78a.75.75 0 0 1 0-1.06L14.44 12 8.72 6.28a.751.751 0 0 1 .018-1.042.751.751 0 0 1 1.042-.018l6.25 6.25a.75.75 0 0 1 0 1.06l-6.25 6.25a.75.75 0 0 1-1.06 0Z"></path></svg></span></summary><div class="sd-summary-content sd-card-body docutils">
+<p class="sd-card-text">Write a <code class="docutils literal notranslate"><span class="pre">hello_world.py</span></code> script and push it to <code class="docutils literal notranslate"><span class="pre">https://github.com/&lt;org&gt;/&lt;repo&gt;</span></code>.</p>
 </div>
-<p>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.</p>
-<p>The push fails. Claude reports an error — but the failure is not an authentication problem. The default sandbox policy does not permit outbound requests to GitHub, so the proxy blocks the connection before the request reaches GitHub’s servers.</p>
+</details><p>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.</p>
+<p>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.</p>
 </section>
 <section id="diagnose-the-denial">
 <h2>Diagnose the Denial<a class="headerlink" href="#diagnose-the-denial" title="Link to this heading">#</a></h2>
-<section id="view-the-logs-from-your-laptop">
-<h3>View the logs from your laptop<a class="headerlink" href="#view-the-logs-from-your-laptop" title="Link to this heading">#</a></h3>
-<p><strong>Terminal 2 (laptop)</strong> — Open a separate terminal on your laptop and launch the OpenShell Terminal:</p>
+<p>In this section, you diagnose the denial from your machine and from inside the sandbox.</p>
+<section id="view-the-logs-from-your-machine">
+<h3>View the Logs from Your Machine<a class="headerlink" href="#view-the-logs-from-your-machine" title="Link to this heading">#</a></h3>
+<p>In terminal 2, launch the OpenShell terminal:</p>
 <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>openshell<span class="w"> </span>term
 </pre></div>
 </div>
@@ -556,36 +559,52 @@ l7_deny_reason: PUT /repos/&lt;org&gt;/&lt;repo&gt;/contents/hello_world.py not
 </div>
 <p>The log shows that the sandbox proxy intercepted an outbound <code class="docutils literal notranslate"><span class="pre">PUT</span></code> request to <code class="docutils literal notranslate"><span class="pre">api.github.com</span></code> and denied it. The <code class="docutils literal notranslate"><span class="pre">github_rest_api</span></code> policy allows read operations (GET) but blocks write operations (PUT, POST, DELETE) to the GitHub API. A similar denial appears for <code class="docutils literal notranslate"><span class="pre">github.com</span></code> if Claude attempted a git push over HTTPS.</p>
 </section>
-<section id="ask-claude-to-check-the-sandbox-logs">
-<h3>Ask Claude to check the sandbox logs<a class="headerlink" href="#ask-claude-to-check-the-sandbox-logs" title="Link to this heading">#</a></h3>
-<p><strong>Terminal 1 (sandbox)</strong> — Switch back to Claude Code. Ask it to check the sandbox logs for denied requests:</p>
-<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>Check the sandbox logs for any denied network requests. What is blocking the push?
-</pre></div>
+<section id="ask-claude-code-to-check-the-sandbox-logs">
+<h3>Ask Claude Code to Check the Sandbox Logs<a class="headerlink" href="#ask-claude-code-to-check-the-sandbox-logs" title="Link to this heading">#</a></h3>
+<p>In terminal 1, ask Claude Code to check the sandbox logs for denied requests:</p>
+<details class="sd-sphinx-override sd-dropdown sd-card sd-mb-3" open="open">
+<summary class="sd-summary-title sd-card-header">
+<span class="sd-summary-icon"><svg version="1.1" width="1.0em" height="1.0em" class="sd-octicon sd-octicon-terminal" viewBox="0 0 16 16" aria-hidden="true"><path d="M0 2.75C0 1.784.784 1 1.75 1h12.5c.966 0 1.75.784 1.75 1.75v10.5A1.75 1.75 0 0 1 14.25 15H1.75A1.75 1.75 0 0 1 0 13.25Zm1.75-.25a.25.25 0 0 0-.25.25v10.5c0 .138.112.25.25.25h12.5a.25.25 0 0 0 .25-.25V2.75a.25.25 0 0 0-.25-.25ZM7.25 8a.749.749 0 0 1-.22.53l-2.25 2.25a.749.749 0 0 1-1.275-.326.749.749 0 0 1 .215-.734L5.44 8 3.72 6.28a.749.749 0 0 1 .326-1.275.749.749 0 0 1 .734.215l2.25 2.25c.141.14.22.331.22.53Zm1.5 1.5h3a.75.75 0 0 1 0 1.5h-3a.75.75 0 0 1 0-1.5Z"></path></svg></span><span class="sd-summary-text">Prompt</span><span class="sd-summary-state-marker sd-summary-chevron-right"><svg version="1.1" width="1.5em" height="1.5em" class="sd-octicon sd-octicon-chevron-right" viewBox="0 0 24 24" aria-hidden="true"><path d="M8.72 18.78a.75.75 0 0 1 0-1.06L14.44 12 8.72 6.28a.751.751 0 0 1 .018-1.042.751.751 0 0 1 1.042-.018l6.25 6.25a.75.75 0 0 1 0 1.06l-6.25 6.25a.75.75 0 0 1-1.06 0Z"></path></svg></span></summary><div class="sd-summary-content sd-card-body docutils">
+<p class="sd-card-text">Check the sandbox logs for any denied network requests. What is blocking the push?</p>
 </div>
-<p>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:</p>
-<blockquote>
-<div><p>The sandbox runs a proxy that enforces policies on outbound traffic. The
-<code class="docutils literal notranslate"><span class="pre">github_rest_api</span></code> 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 via the API will be blocked
-until the policy is updated.</p>
-</div></blockquote>
-<p>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.</p>
-<p>Copy the deny reason from Claude’s response — you will paste it into your laptop agent in the next step.</p>
+</details><p>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:</p>
+<details class="sd-sphinx-override sd-dropdown sd-card sd-mb-3" open="open">
+<summary class="sd-summary-title sd-card-header">
+<span class="sd-summary-icon"><svg version="1.1" width="1.0em" height="1.0em" class="sd-octicon sd-octicon-comment" viewBox="0 0 16 16" aria-hidden="true"><path d="M1 2.75C1 1.784 1.784 1 2.75 1h10.5c.966 0 1.75.784 1.75 1.75v7.5A1.75 1.75 0 0 1 13.25 12H9.06l-2.573 2.573A1.458 1.458 0 0 1 4 13.543V12H2.75A1.75 1.75 0 0 1 1 10.25Zm1.75-.25a.25.25 0 0 0-.25.25v7.5c0 .138.112.25.25.25h2a.75.75 0 0 1 .75.75v2.19l2.72-2.72a.749.749 0 0 1 .53-.22h4.5a.25.25 0 0 0 .25-.25v-7.5a.25.25 0 0 0-.25-.25Z"></path></svg></span><span class="sd-summary-text">Response</span><span class="sd-summary-state-marker sd-summary-chevron-right"><svg version="1.1" width="1.5em" height="1.5em" class="sd-octicon sd-octicon-chevron-right" viewBox="0 0 24 24" aria-hidden="true"><path d="M8.72 18.78a.75.75 0 0 1 0-1.06L14.44 12 8.72 6.28a.751.751 0 0 1 .018-1.042.751.751 0 0 1 1.042-.018l6.25 6.25a.75.75 0 0 1 0 1.06l-6.25 6.25a.75.75 0 0 1-1.06 0Z"></path></svg></span></summary><div class="sd-summary-content sd-card-body docutils">
+<p class="sd-card-text">The sandbox runs a proxy that enforces policies on outbound traffic.
+The <code class="docutils literal notranslate"><span class="pre">github_rest_api</span></code> 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
+will be blocked until the policy is updated.</p>
+</div>
+</details><p>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.</p>
+<p>Copy the deny reason from Claude’s response. You paste it into an agent running on your machine in the next step.</p>
 </section>
 </section>
-<section id="update-the-policy-from-your-laptop">
-<h2>Update the Policy from Your Laptop<a class="headerlink" href="#update-the-policy-from-your-laptop" title="Link to this heading">#</a></h2>
-<p><strong>Terminal 2 (laptop)</strong> — Paste the deny reason from the previous step into your coding agent (for example, Claude Code or Cursor running on your laptop) and ask it to update the sandbox policy. The deny reason gives the agent the context it needs to generate the correct policy rules.</p>
-<p>The agent inspects the deny reasons, writes an updated policy that adds <code class="docutils literal notranslate"><span class="pre">github_git</span></code> and <code class="docutils literal notranslate"><span class="pre">github_api</span></code> blocks for your repository, and runs <code class="docutils literal notranslate"><span class="pre">openshell</span> <span class="pre">policy</span> <span class="pre">set</span></code> to apply it:</p>
-<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>openshell<span class="w"> </span>policy<span class="w"> </span><span class="nb">set</span><span class="w"> </span>&lt;sandbox-name&gt;<span class="w"> </span>--policy<span class="w"> </span>/tmp/sandbox-policy-update.yaml<span class="w"> </span>--wait
-</pre></div>
+<section id="update-the-policy-from-your-machine">
+<h2>Update the Policy from Your Machine<a class="headerlink" href="#update-the-policy-from-your-machine" title="Link to this heading">#</a></h2>
+<p>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.</p>
+<details class="sd-sphinx-override sd-dropdown sd-card sd-mb-3" open="open">
+<summary class="sd-summary-title sd-card-header">
+<span class="sd-summary-icon"><svg version="1.1" width="1.0em" height="1.0em" class="sd-octicon sd-octicon-terminal" viewBox="0 0 16 16" aria-hidden="true"><path d="M0 2.75C0 1.784.784 1 1.75 1h12.5c.966 0 1.75.784 1.75 1.75v10.5A1.75 1.75 0 0 1 14.25 15H1.75A1.75 1.75 0 0 1 0 13.25Zm1.75-.25a.25.25 0 0 0-.25.25v10.5c0 .138.112.25.25.25h12.5a.25.25 0 0 0 .25-.25V2.75a.25.25 0 0 0-.25-.25ZM7.25 8a.749.749 0 0 1-.22.53l-2.25 2.25a.749.749 0 0 1-1.275-.326.749.749 0 0 1 .215-.734L5.44 8 3.72 6.28a.749.749 0 0 1 .326-1.275.749.749 0 0 1 .734.215l2.25 2.25c.141.14.22.331.22.53Zm1.5 1.5h3a.75.75 0 0 1 0 1.5h-3a.75.75 0 0 1 0-1.5Z"></path></svg></span><span class="sd-summary-text">Prompt</span><span class="sd-summary-state-marker sd-summary-chevron-right"><svg version="1.1" width="1.5em" height="1.5em" class="sd-octicon sd-octicon-chevron-right" viewBox="0 0 24 24" aria-hidden="true"><path d="M8.72 18.78a.75.75 0 0 1 0-1.06L14.44 12 8.72 6.28a.751.751 0 0 1 .018-1.042.751.751 0 0 1 1.042-.018l6.25 6.25a.75.75 0 0 1 0 1.06l-6.25 6.25a.75.75 0 0 1-1.06 0Z"></path></svg></span></summary><div class="sd-summary-content sd-card-body docutils">
+<p class="sd-card-text">Based on the following deny reasons, recommend a sandbox policy update that allows GitHub pushes to <code class="docutils literal notranslate"><span class="pre">https://github.com/&lt;org&gt;/&lt;repo&gt;</span></code>, and save to <code class="docutils literal notranslate"><span class="pre">/tmp/sandbox-policy-update.yaml</span></code>:</p>
+<p class="sd-card-text">The <code class="docutils literal notranslate"><span class="pre">filesystem_policy</span></code>, <code class="docutils literal notranslate"><span class="pre">landlock</span></code>, and <code class="docutils literal notranslate"><span class="pre">process</span></code> 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, but only the <code class="docutils literal notranslate"><span class="pre">network_policies</span></code> section takes effect when you apply this to a running sandbox.</p>
 </div>
-<p>Your coding agent generates both the policy file and this command. Network policies are hot-reloadable — the <code class="docutils literal notranslate"><span class="pre">--wait</span></code> 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.</p>
+</details><p>The following steps outline the expected process done by the agent:</p>
+<ol class="arabic simple">
+<li><p>Inspects the deny reasons.</p></li>
+<li><p>Writes an updated policy that adds <code class="docutils literal notranslate"><span class="pre">github_git</span></code> and <code class="docutils literal notranslate"><span class="pre">github_api</span></code> blocks that grant write access to your repository.</p></li>
+<li><p>Saves the policy to <code class="docutils literal notranslate"><span class="pre">/tmp/sandbox-policy-update.yaml</span></code>.</p></li>
+</ol>
+</section>
+<section id="review-the-generated-policy">
+<h2>Review the Generated Policy<a class="headerlink" href="#review-the-generated-policy" title="Link to this heading">#</a></h2>
+<p>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, <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">push</span></code> operations and GitHub REST API access scoped to a single repository.</p>
 <details class="sd-sphinx-override sd-dropdown sd-card sd-mb-3">
 <summary class="sd-summary-title sd-card-header">
-<span class="sd-summary-text">Full reference policy</span><span class="sd-summary-state-marker sd-summary-chevron-right"><svg version="1.1" width="1.5em" height="1.5em" class="sd-octicon sd-octicon-chevron-right" viewBox="0 0 24 24" aria-hidden="true"><path d="M8.72 18.78a.75.75 0 0 1 0-1.06L14.44 12 8.72 6.28a.751.751 0 0 1 .018-1.042.751.751 0 0 1 1.042-.018l6.25 6.25a.75.75 0 0 1 0 1.06l-6.25 6.25a.75.75 0 0 1-1.06 0Z"></path></svg></span></summary><div class="sd-summary-content sd-card-body docutils">
-<p class="sd-card-text">The following YAML shows a complete policy that extends the <a class="reference internal" href="../reference/default-policy.html"><span class="doc">default policy</span></a> with GitHub access for a single repository. This is representative of what a coding agent generates when asked to unblock GitHub pushes. Replace <code class="docutils literal notranslate"><span class="pre">&lt;org&gt;</span></code> with your GitHub organization or username and <code class="docutils literal notranslate"><span class="pre">&lt;repo&gt;</span></code> with your repository name.</p>
+<span class="sd-summary-icon"><svg version="1.1" width="1.0em" height="1.0em" class="sd-octicon sd-octicon-code" viewBox="0 0 16 16" aria-hidden="true"><path d="m11.28 3.22 4.25 4.25a.75.75 0 0 1 0 1.06l-4.25 4.25a.749.749 0 0 1-1.275-.326.749.749 0 0 1 .215-.734L13.94 8l-3.72-3.72a.749.749 0 0 1 .326-1.275.749.749 0 0 1 .734.215Zm-6.56 0a.751.751 0 0 1 1.042.018.751.751 0 0 1 .018 1.042L2.06 8l3.72 3.72a.749.749 0 0 1-.326 1.275.749.749 0 0 1-.734-.215L.47 8.53a.75.75 0 0 1 0-1.06Z"></path></svg></span><span class="sd-summary-text">Full reference policy</span><span class="sd-summary-state-marker sd-summary-chevron-right"><svg version="1.1" width="1.5em" height="1.5em" class="sd-octicon sd-octicon-chevron-right" viewBox="0 0 24 24" aria-hidden="true"><path d="M8.72 18.78a.75.75 0 0 1 0-1.06L14.44 12 8.72 6.28a.751.751 0 0 1 .018-1.042.751.751 0 0 1 1.042-.018l6.25 6.25a.75.75 0 0 1 0 1.06l-6.25 6.25a.75.75 0 0 1-1.06 0Z"></path></svg></span></summary><div class="sd-summary-content sd-card-body docutils">
+<p class="sd-card-text">The following YAML shows a complete policy that extends the <a class="reference internal" href="../reference/default-policy.html"><span class="doc">default policy</span></a> with GitHub access for a single repository. Replace <code class="docutils literal notranslate"><span class="pre">&lt;org&gt;</span></code> with your GitHub organization or username and <code class="docutils literal notranslate"><span class="pre">&lt;repo&gt;</span></code> with your repository name.</p>
+<p class="sd-card-text">The <code class="docutils literal notranslate"><span class="pre">filesystem_policy</span></code>, <code class="docutils literal notranslate"><span class="pre">landlock</span></code>, and <code class="docutils literal notranslate"><span class="pre">process</span></code> 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, but only the <code class="docutils literal notranslate"><span class="pre">network_policies</span></code> section takes effect when you apply this to a running sandbox.</p>
 <div class="highlight-yaml notranslate"><div class="highlight"><pre><span></span><span class="nt">version</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">1</span>
 
 <span class="c1"># ── Static (locked at sandbox creation) ──────────────────────────</span>
@@ -639,54 +658,54 @@ until the policy is updated.</p>
 <span class="w">      </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="p p-Indicator">{</span><span class="nt"> path</span><span class="p">:</span><span class="w"> </span><span class="nv">/bin/bash</span><span class="w"> </span><span class="p p-Indicator">}</span>
 <span class="w">      </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="p p-Indicator">{</span><span class="nt"> path</span><span class="p">:</span><span class="w"> </span><span class="nv">/usr/local/bin/opencode</span><span class="w"> </span><span class="p p-Indicator">}</span>
 
-<span class="w">  </span><span class="c1"># ── GitHub: git operations (clone, fetch, push) ──────────────</span>
-
-<span class="w">  </span><span class="nt">github_git</span><span class="p">:</span>
-<span class="w">    </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">github-git</span>
-<span class="w">    </span><span class="nt">endpoints</span><span class="p">:</span>
-<span class="w">      </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">host</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">github.com</span>
-<span class="w">        </span><span class="nt">port</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">443</span>
-<span class="w">        </span><span class="nt">protocol</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">rest</span>
-<span class="w">        </span><span class="nt">tls</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">terminate</span>
-<span class="w">        </span><span class="nt">enforcement</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">enforce</span>
-<span class="w">        </span><span class="nt">rules</span><span class="p">:</span>
-<span class="w">          </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">allow</span><span class="p">:</span>
-<span class="w">              </span><span class="nt">method</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">GET</span>
-<span class="w">              </span><span class="nt">path</span><span class="p">:</span><span class="w"> </span><span class="s">&quot;/&lt;org&gt;/&lt;repo&gt;.git/info/refs*&quot;</span>
-<span class="w">          </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">allow</span><span class="p">:</span>
-<span class="w">              </span><span class="nt">method</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">POST</span>
-<span class="w">              </span><span class="nt">path</span><span class="p">:</span><span class="w"> </span><span class="s">&quot;/&lt;org&gt;/&lt;repo&gt;.git/git-upload-pack&quot;</span>
-<span class="w">          </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">allow</span><span class="p">:</span>
-<span class="w">              </span><span class="nt">method</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">POST</span>
-<span class="w">              </span><span class="nt">path</span><span class="p">:</span><span class="w"> </span><span class="s">&quot;/&lt;org&gt;/&lt;repo&gt;.git/git-receive-pack&quot;</span>
-<span class="w">    </span><span class="nt">binaries</span><span class="p">:</span>
-<span class="w">      </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="p p-Indicator">{</span><span class="nt"> path</span><span class="p">:</span><span class="w"> </span><span class="nv">/usr/bin/git</span><span class="w"> </span><span class="p p-Indicator">}</span>
-
-<span class="w">  </span><span class="c1"># ── GitHub: REST API ─────────────────────────────────────────</span>
-
-<span class="w">  </span><span class="nt">github_api</span><span class="p">:</span>
-<span class="w">    </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">github-api</span>
-<span class="w">    </span><span class="nt">endpoints</span><span class="p">:</span>
-<span class="w">      </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">host</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">api.github.com</span>
-<span class="w">        </span><span class="nt">port</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">443</span>
-<span class="w">        </span><span class="nt">protocol</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">rest</span>
-<span class="w">        </span><span class="nt">tls</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">terminate</span>
-<span class="w">        </span><span class="nt">enforcement</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">enforce</span>
-<span class="w">        </span><span class="nt">rules</span><span class="p">:</span>
-<span class="w">          </span><span class="c1"># GraphQL API (used by gh CLI)</span>
-<span class="w">          </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">allow</span><span class="p">:</span>
-<span class="w">              </span><span class="nt">method</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">POST</span>
-<span class="w">              </span><span class="nt">path</span><span class="p">:</span><span class="w"> </span><span class="s">&quot;/graphql&quot;</span>
-<span class="w">          </span><span class="c1"># Full read-write access to the repository</span>
-<span class="w">          </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">allow</span><span class="p">:</span>
-<span class="w">              </span><span class="nt">method</span><span class="p">:</span><span class="w"> </span><span class="s">&quot;*&quot;</span>
-<span class="w">              </span><span class="nt">path</span><span class="p">:</span><span class="w"> </span><span class="s">&quot;/repos/&lt;org&gt;/&lt;repo&gt;/**&quot;</span>
-<span class="w">    </span><span class="nt">binaries</span><span class="p">:</span>
-<span class="w">      </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="p p-Indicator">{</span><span class="nt"> path</span><span class="p">:</span><span class="w"> </span><span class="nv">/usr/local/bin/claude</span><span class="w"> </span><span class="p p-Indicator">}</span>
-<span class="w">      </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="p p-Indicator">{</span><span class="nt"> path</span><span class="p">:</span><span class="w"> </span><span class="nv">/usr/local/bin/opencode</span><span class="w"> </span><span class="p p-Indicator">}</span>
-<span class="w">      </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="p p-Indicator">{</span><span class="nt"> path</span><span class="p">:</span><span class="w"> </span><span class="nv">/usr/bin/gh</span><span class="w"> </span><span class="p p-Indicator">}</span>
-<span class="w">      </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="p p-Indicator">{</span><span class="nt"> path</span><span class="p">:</span><span class="w"> </span><span class="nv">/usr/bin/curl</span><span class="w"> </span><span class="p p-Indicator">}</span>
-
+<span class="hll"><span class="w">  </span><span class="c1"># ── GitHub: git operations (clone, fetch, push) ──────────────</span>
+</span><span class="hll">
+</span><span class="hll"><span class="w">  </span><span class="nt">github_git</span><span class="p">:</span>
+</span><span class="hll"><span class="w">    </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">github-git</span>
+</span><span class="hll"><span class="w">    </span><span class="nt">endpoints</span><span class="p">:</span>
+</span><span class="hll"><span class="w">      </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">host</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">github.com</span>
+</span><span class="hll"><span class="w">        </span><span class="nt">port</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">443</span>
+</span><span class="hll"><span class="w">        </span><span class="nt">protocol</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">rest</span>
+</span><span class="hll"><span class="w">        </span><span class="nt">tls</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">terminate</span>
+</span><span class="hll"><span class="w">        </span><span class="nt">enforcement</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">enforce</span>
+</span><span class="hll"><span class="w">        </span><span class="nt">rules</span><span class="p">:</span>
+</span><span class="hll"><span class="w">          </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">allow</span><span class="p">:</span>
+</span><span class="hll"><span class="w">              </span><span class="nt">method</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">GET</span>
+</span><span class="hll"><span class="w">              </span><span class="nt">path</span><span class="p">:</span><span class="w"> </span><span class="s">&quot;/&lt;org&gt;/&lt;repo&gt;.git/info/refs*&quot;</span>
+</span><span class="hll"><span class="w">          </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">allow</span><span class="p">:</span>
+</span><span class="hll"><span class="w">              </span><span class="nt">method</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">POST</span>
+</span><span class="hll"><span class="w">              </span><span class="nt">path</span><span class="p">:</span><span class="w"> </span><span class="s">&quot;/&lt;org&gt;/&lt;repo&gt;.git/git-upload-pack&quot;</span>
+</span><span class="hll"><span class="w">          </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">allow</span><span class="p">:</span>
+</span><span class="hll"><span class="w">              </span><span class="nt">method</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">POST</span>
+</span><span class="hll"><span class="w">              </span><span class="nt">path</span><span class="p">:</span><span class="w"> </span><span class="s">&quot;/&lt;org&gt;/&lt;repo&gt;.git/git-receive-pack&quot;</span>
+</span><span class="hll"><span class="w">    </span><span class="nt">binaries</span><span class="p">:</span>
+</span><span class="hll"><span class="w">      </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="p p-Indicator">{</span><span class="nt"> path</span><span class="p">:</span><span class="w"> </span><span class="nv">/usr/bin/git</span><span class="w"> </span><span class="p p-Indicator">}</span>
+</span><span class="hll">
+</span><span class="hll"><span class="w">  </span><span class="c1"># ── GitHub: REST API ─────────────────────────────────────────</span>
+</span><span class="hll">
+</span><span class="hll"><span class="w">  </span><span class="nt">github_api</span><span class="p">:</span>
+</span><span class="hll"><span class="w">    </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">github-api</span>
+</span><span class="hll"><span class="w">    </span><span class="nt">endpoints</span><span class="p">:</span>
+</span><span class="hll"><span class="w">      </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">host</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">api.github.com</span>
+</span><span class="hll"><span class="w">        </span><span class="nt">port</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">443</span>
+</span><span class="hll"><span class="w">        </span><span class="nt">protocol</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">rest</span>
+</span><span class="hll"><span class="w">        </span><span class="nt">tls</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">terminate</span>
+</span><span class="hll"><span class="w">        </span><span class="nt">enforcement</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">enforce</span>
+</span><span class="hll"><span class="w">        </span><span class="nt">rules</span><span class="p">:</span>
+</span><span class="hll"><span class="w">          </span><span class="c1"># GraphQL API (used by gh CLI)</span>
+</span><span class="hll"><span class="w">          </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">allow</span><span class="p">:</span>
+</span><span class="hll"><span class="w">              </span><span class="nt">method</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">POST</span>
+</span><span class="hll"><span class="w">              </span><span class="nt">path</span><span class="p">:</span><span class="w"> </span><span class="s">&quot;/graphql&quot;</span>
+</span><span class="hll"><span class="w">          </span><span class="c1"># Full read-write access to the repository</span>
+</span><span class="hll"><span class="w">          </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">allow</span><span class="p">:</span>
+</span><span class="hll"><span class="w">              </span><span class="nt">method</span><span class="p">:</span><span class="w"> </span><span class="s">&quot;*&quot;</span>
+</span><span class="hll"><span class="w">              </span><span class="nt">path</span><span class="p">:</span><span class="w"> </span><span class="s">&quot;/repos/&lt;org&gt;/&lt;repo&gt;/**&quot;</span>
+</span><span class="hll"><span class="w">    </span><span class="nt">binaries</span><span class="p">:</span>
+</span><span class="hll"><span class="w">      </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="p p-Indicator">{</span><span class="nt"> path</span><span class="p">:</span><span class="w"> </span><span class="nv">/usr/local/bin/claude</span><span class="w"> </span><span class="p p-Indicator">}</span>
+</span><span class="hll"><span class="w">      </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="p p-Indicator">{</span><span class="nt"> path</span><span class="p">:</span><span class="w"> </span><span class="nv">/usr/local/bin/opencode</span><span class="w"> </span><span class="p p-Indicator">}</span>
+</span><span class="hll"><span class="w">      </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="p p-Indicator">{</span><span class="nt"> path</span><span class="p">:</span><span class="w"> </span><span class="nv">/usr/bin/gh</span><span class="w"> </span><span class="p p-Indicator">}</span>
+</span><span class="hll"><span class="w">      </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="p p-Indicator">{</span><span class="nt"> path</span><span class="p">:</span><span class="w"> </span><span class="nv">/usr/bin/curl</span><span class="w"> </span><span class="p p-Indicator">}</span>
+</span>
 <span class="w">  </span><span class="c1"># ── Package managers ─────────────────────────────────────────</span>
 
 <span class="w">  </span><span class="nt">pypi</span><span class="p">:</span>
@@ -745,18 +764,33 @@ until the policy is updated.</p>
 </tbody>
 </table>
 </div>
-<p class="sd-card-text">The remaining blocks (<code class="docutils literal notranslate"><span class="pre">claude_code</span></code>, <code class="docutils literal notranslate"><span class="pre">nvidia_inference</span></code>, <code class="docutils literal notranslate"><span class="pre">pypi</span></code>, <code class="docutils literal notranslate"><span class="pre">vscode</span></code>) are identical to the <a class="reference internal" href="../reference/default-policy.html"><span class="doc">default policy</span></a>. Sandbox behavior outside of GitHub operations is unchanged.</p>
+<p class="sd-card-text">The remaining blocks (<code class="docutils literal notranslate"><span class="pre">claude_code</span></code>, <code class="docutils literal notranslate"><span class="pre">nvidia_inference</span></code>, <code class="docutils literal notranslate"><span class="pre">pypi</span></code>, <code class="docutils literal notranslate"><span class="pre">vscode</span></code>) are identical to the <a class="reference internal" href="../reference/default-policy.html"><span class="doc">default policy</span></a>. The default policy’s <code class="docutils literal notranslate"><span class="pre">github_ssh_over_https</span></code> and <code class="docutils literal notranslate"><span class="pre">github_rest_api</span></code> blocks are replaced by the <code class="docutils literal notranslate"><span class="pre">github_git</span></code> and <code class="docutils literal notranslate"><span class="pre">github_api</span></code> blocks above, which grant write access to the specified repository. Sandbox behavior outside of GitHub operations is unchanged.</p>
 <p class="sd-card-text">For details on policy block structure, refer to <a class="reference internal" href="../sandboxes/index.html#network-access-rules"><span class="std std-ref">Network Access Rules</span></a>.</p>
 </div>
 </details></section>
+<section id="apply-the-policy">
+<h2>Apply the Policy<a class="headerlink" href="#apply-the-policy" title="Link to this heading">#</a></h2>
+<p>After you have reviewed the generated policy, apply it to the running sandbox:</p>
+<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>openshell<span class="w"> </span>policy<span class="w"> </span><span class="nb">set</span><span class="w"> </span>&lt;sandbox-name&gt;<span class="w"> </span>--policy<span class="w"> </span>/tmp/sandbox-policy-update.yaml<span class="w"> </span>--wait
+</pre></div>
+</div>
+<p>Network policies are hot-reloadable. The <code class="docutils literal notranslate"><span class="pre">--wait</span></code> 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.</p>
+</section>
 <section id="retry-the-push">
 <h2>Retry the Push<a class="headerlink" href="#retry-the-push" title="Link to this heading">#</a></h2>
-<p><strong>Terminal 1 (sandbox)</strong> — Switch back to Claude Code and ask it to retry the push:</p>
+<p>In terminal 1, ask Claude Code to retry the push:</p>
 <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>The sandbox policy has been updated. Try pushing to the repository again.
 </pre></div>
 </div>
 <p>The push completes successfully. The <code class="docutils literal notranslate"><span class="pre">openshell</span> <span class="pre">term</span></code> dashboard now shows <code class="docutils literal notranslate"><span class="pre">l7_decision=allow</span></code> entries for <code class="docutils literal notranslate"><span class="pre">api.github.com</span></code> and <code class="docutils literal notranslate"><span class="pre">github.com</span></code> where it previously showed denials.</p>
 </section>
+<section id="clean-up">
+<h2>Clean Up<a class="headerlink" href="#clean-up" title="Link to this heading">#</a></h2>
+<p>When you are finished, delete the sandbox to free cluster resources:</p>
+<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>openshell<span class="w"> </span>sandbox<span class="w"> </span>delete<span class="w"> </span>&lt;sandbox-name&gt;
+</pre></div>
+</div>
+</section>
 <section id="next-steps">
 <h2>Next Steps<a class="headerlink" href="#next-steps" title="Link to this heading">#</a></h2>
 <p>The following resources cover related topics in greater depth:</p>
@@ -818,15 +852,18 @@ until the policy is updated.</p>
   <nav class="bd-toc-nav page-toc" aria-labelledby="pst-page-navigation-heading-2">
     <ul class="visible nav section-nav flex-column">
 <li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#prerequisites">Prerequisites</a></li>
-<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#launch-the-sandbox">Launch the Sandbox</a></li>
+<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#set-up-a-sandbox-with-your-github-token">Set Up a Sandbox with Your GitHub Token</a></li>
 <li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#push-code-to-github">Push Code to GitHub</a></li>
 <li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#diagnose-the-denial">Diagnose the Denial</a><ul class="nav section-nav flex-column">
-<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#view-the-logs-from-your-laptop">View the logs from your laptop</a></li>
-<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#ask-claude-to-check-the-sandbox-logs">Ask Claude to check the sandbox logs</a></li>
+<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#view-the-logs-from-your-machine">View the Logs from Your Machine</a></li>
+<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#ask-claude-code-to-check-the-sandbox-logs">Ask Claude Code to Check the Sandbox Logs</a></li>
 </ul>
 </li>
-<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#update-the-policy-from-your-laptop">Update the Policy from Your Laptop</a></li>
+<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#update-the-policy-from-your-machine">Update the Policy from Your Machine</a></li>
+<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#review-the-generated-policy">Review the Generated Policy</a></li>
+<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#apply-the-policy">Apply the Policy</a></li>
 <li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#retry-the-push">Retry the Push</a></li>
+<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#clean-up">Clean Up</a></li>
 <li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#next-steps">Next Steps</a></li>
 </ul>
   </nav></div>
diff --git a/pr-preview/pr-257/tutorials/github-sandbox.json b/pr-preview/pr-257/tutorials/github-sandbox.json
index e20db6ba2..8c3cea17f 100644
--- a/pr-preview/pr-257/tutorials/github-sandbox.json
+++ b/pr-preview/pr-257/tutorials/github-sandbox.json
@@ -1 +1 @@
-{"id":"tutorials/github-sandbox","title":"Set Up a Sandbox of Claude Code with a Custom GitHub Policy","url":"tutorials/github-sandbox.html","last_modified":"2026-03-12T09:12:26.652146+00:00","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.1.0"},"product":{"name":"OpenShell","version":"0.1.0"},"description":"Learn the iterative policy workflow by launching a sandbox, diagnosing a GitHub access denial, and applying a custom policy to fix it.","tags":["Tutorial","GitHub","Sandbox","Policy","Claude Code"],"topics":["Generative AI","Cybersecurity"],"content_type":"how_to","learning_level":"technical_intermediate","audience":["engineer"],"content":"Set Up a Sandbox of Claude Code with a Custom GitHub Policy This tutorial walks through the iterative policy workflow. You launch a sandbox, ask Claude Code to push code to GitHub, get blocked by the default network policy, diagnose the denial from two angles — the OpenShell Terminal on your laptop and the sandbox logs from inside — and then apply a custom policy to fix it, all without recreating the sandbox. After completing this tutorial, you will 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 may differ between sessions — use the examples as a guide for the type of interaction, not as expected output. Prerequisites This tutorial requires the following: Completed the Quickstart tutorial. A GitHub personal access token (PAT) with repo scope. To create one, go to GitHub Settings > Developer settings > Personal access tokens , select Generate new token (classic) , check the repo scope, and copy the token. Your own Anthropic account for Claude Code. OpenShell provides the sandbox, not the agent — you need your own account to log in to Claude Code. A public GitHub repository you own (used as the push target). A scratch or test repository works well — the tutorial pushes a small file to it. You can create a new repository with a README if you do not have one handy. This tutorial uses two terminals throughout: Terminal 1 (sandbox) — The terminal where you launch the sandbox. Claude Code runs here. You interact with the agent in this terminal. Terminal 2 (laptop) — A separate terminal on your laptop. You use this for openshell term , openshell policy set , and other CLI commands that manage the sandbox from the outside. Each section below indicates which terminal to use. Launch the Sandbox Terminal 1 (sandbox) — Create a sandbox and start Claude Code. No custom policy is needed yet — the default policy is applied automatically. Starting a new sandbox Create a credential provider 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: $ GITHUB_TOKEN=<your-token\nopenshell provider create --name my-github --type github --from-existing\nopenshell sandbox create --provider my-github --keep -- claude\nUsing an existing sandbox Connect to a sandbox that is already running and set your GitHub token as an environment variable: $ openshell sandbox connect <sandbox-name\nexport GITHUB_TOKEN=<your-token\nThe --keep flag keeps the sandbox running after Claude Code exits, so you can apply policy updates later without recreating the environment. Claude Code starts inside the sandbox. Log in through your preferred authentication method and trust the /sandbox workspace when prompted. Push Code to GitHub Terminal 1 (sandbox) — Ask Claude Code to write a simple script and push it to your repository: Write a hello_world.py script and push it to https://github.com/<org>/<repo\nClaude 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 does not permit outbound requests to GitHub, so the proxy blocks the connection before the request reaches GitHub’s servers. Diagnose the Denial View the logs from your laptop Terminal 2 (laptop) — Open a separate terminal on your laptop and launch the OpenShell Terminal: $ openshell term\nThe 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: l7_action: PUT\nl7_target: /repos/<org>/<repo>/contents/hello_world.py\nl7_decision: deny\ndst_host: api.github.com\ndst_port: 443\nl7_protocol: rest\npolicy: github_rest_api\nl7_deny_reason: PUT /repos/<org>/<repo>/contents/hello_world.py not permitted by policy\nThe 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. Ask Claude to check the sandbox logs Terminal 1 (sandbox) — Switch back to Claude Code. Ask it to check the sandbox logs for denied requests: Check the sandbox logs for any denied network requests. What is blocking the push\nClaude 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: The sandbox runs a proxy that enforces policies on outbound traffic. The\ngithub_rest_api policy allows GET requests (used to read the file) but blocks\nPUT/write requests to GitHub. This is a sandbox-level restriction, not a token\nissue — no matter what token you provide, pushes via the API will be blocked\nuntil the policy is updated. 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 will paste it into your laptop agent in the next step. Update the Policy from Your Laptop Terminal 2 (laptop) — Paste the deny reason from the previous step into your coding agent (for example, Claude Code or Cursor running on your laptop) and ask it to update the sandbox policy. The deny reason gives the agent the context it needs to generate the correct policy rules. The agent inspects the deny reasons, writes an updated policy that adds github_git and github_api blocks for your repository, and runs openshell policy set to apply it: $ openshell policy set <sandbox-name> --policy /tmp/sandbox-policy-update.yaml --wait\nYour coding agent generates both the policy file and this command. 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. Full reference policy The following YAML shows a complete policy that extends the default policy with GitHub access for a single repository. This is representative of what a coding agent generates when asked to unblock GitHub pushes. Replace <org> with your GitHub organization or username and <repo> with your repository name. version: 1\n── Static (locked at sandbox creation)\nfilesystem_policy\ninclude_workdir: true\nread_only\n/usr\n/lib\n/proc\n/dev/urandom\n/app\n/etc\n/var/log\nread_write\n/sandbox\n/tmp\n/dev/null\nlandlock\ncompatibility: best_effort\nprocess\nrun_as_user: sandbox\nrun_as_group: sandbox\n── Dynamic (hot-reloadable)\nnetwork_policies\nClaude Code ↔ Anthropic API\nclaude_code\nname: claude-code\nendpoints\n{ host: api.anthropic.com, port: 443, protocol: rest, enforcement: enforce, access: full, tls: terminate\n{ host: statsig.anthropic.com, port: 443\n{ host: sentry.io, port: 443\n{ host: raw.githubusercontent.com, port: 443\n{ host: platform.claude.com, port: 443\nbinaries\n{ path: /usr/local/bin/claude\n{ path: /usr/bin/node\nNVIDIA inference endpoint\nnvidia_inference\nname: nvidia-inference\nendpoints\n{ host: integrate.api.nvidia.com, port: 443\nbinaries\n{ path: /usr/bin/curl\n{ path: /bin/bash\n{ path: /usr/local/bin/opencode\n── GitHub: git operations (clone, fetch, push)\ngithub_git\nname: github-git\nendpoints\nhost: github.com\nport: 443\nprotocol: rest\ntls: terminate\nenforcement: enforce\nrules\nallow\nmethod: GET\npath: \"/<org>/<repo>.git/info/refs\nallow\nmethod: POST\npath: \"/<org>/<repo>.git/git-upload-pack\nallow\nmethod: POST\npath: \"/<org>/<repo>.git/git-receive-pack\nbinaries\n{ path: /usr/bin/git\n── GitHub: REST API\ngithub_api\nname: github-api\nendpoints\nhost: api.github.com\nport: 443\nprotocol: rest\ntls: terminate\nenforcement: enforce\nrules\nGraphQL API (used by gh CLI\nallow\nmethod: POST\npath: \"/graphql\nFull read-write access to the repository\nallow\nmethod:\npath: \"/repos/<org>/<repo\nbinaries\n{ path: /usr/local/bin/claude\n{ path: /usr/local/bin/opencode\n{ path: /usr/bin/gh\n{ path: /usr/bin/curl\n── Package managers\npypi\nname: pypi\nendpoints\n{ host: pypi.org, port: 443\n{ host: files.pythonhosted.org, port: 443\n{ host: github.com, port: 443\n{ host: objects.githubusercontent.com, port: 443\n{ host: api.github.com, port: 443\n{ host: downloads.python.org, port: 443\nbinaries\n{ path: /sandbox/.venv/bin/python\n{ path: /sandbox/.venv/bin/python3\n{ path: /sandbox/.venv/bin/pip\n{ path: /app/.venv/bin/python\n{ path: /app/.venv/bin/python3\n{ path: /app/.venv/bin/pip\n{ path: /usr/local/bin/uv\n{ path: \"/sandbox/.uv/python/**\"\n── VS Code Remote\nvscode\nname: vscode\nendpoints\n{ host: update.code.visualstudio.com, port: 443\n{ host: \"*.vo.msecnd.net\", port: 443\n{ host: vscode.download.prss.microsoft.com, port: 443\n{ host: marketplace.visualstudio.com, port: 443\n{ host: \"*.gallerycdn.vsassets.io\", port: 443\nbinaries\n{ path: /usr/bin/curl\n{ path: /usr/bin/wget\n{ path: \"/sandbox/.vscode-server/**\"\n{ path: \"/sandbox/.vscode-remote-containers/**\"\nThe following table summarizes the two GitHub-specific blocks: Block Endpoint Behavior github_git github.com:443 Git Smart HTTP protocol with TLS termination. 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 with TLS termination. Permits all HTTP methods for the specified repository and GraphQL queries. Denies API access to unlisted repositories. The remaining blocks ( claude_code , nvidia_inference , pypi , vscode ) are identical to the default policy . Sandbox behavior outside of GitHub operations is unchanged. For details on policy block structure, refer to Network Access Rules . Retry the Push Terminal 1 (sandbox) — Switch back to Claude Code and ask it to retry the push: The sandbox policy has been updated. Try pushing to the repository again\nThe 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. 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 . To learn the full policy iteration workflow (pull, edit, push, verify), refer to /sandboxes/policies . To inject credentials automatically instead of pasting tokens, refer to /sandboxes/providers","format":"text","summary":"This tutorial walks through the iterative policy workflow. You launch a sandbox, ask Claude Code to push code to GitHub, get blocked by the default network policy, diagnose the denial from two angles — the OpenShell Terminal on your laptop and the sandbox logs from inside — and then apply a custo...","headings":[{"text":"Set Up a Sandbox of Claude Code with a Custom GitHub Policy","level":1},{"text":"Prerequisites","level":2},{"text":"Launch the Sandbox","level":2},{"text":"Push Code to GitHub","level":2},{"text":"Diagnose the Denial","level":2},{"text":"View the logs from your laptop","level":3},{"text":"Ask Claude to check the sandbox logs","level":3},{"text":"Update the Policy from Your Laptop","level":2},{"text":"Retry the Push","level":2},{"text":"Next Steps","level":2}]}
\ No newline at end of file
+{"id":"tutorials/github-sandbox","title":"Set Up a Sandbox of Claude Code with a Custom GitHub Policy","url":"tutorials/github-sandbox.html","last_modified":"2026-03-12T23:38:42.433873+00:00","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.1.0"},"product":{"name":"OpenShell","version":"0.1.0"},"description":"Learn the iterative policy workflow by launching a sandbox, diagnosing a GitHub access denial, and applying a custom policy to fix it.","tags":["Tutorial","GitHub","Sandbox","Policy","Claude Code"],"topics":["Generative AI","Cybersecurity"],"content_type":"tutorial","learning_level":"technical_intermediate","audience":["engineer"],"content":"Set Up a Sandbox of Claude Code with a Custom GitHub Policy 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\nYou 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. After completing this tutorial, you will 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. Prerequisites This tutorial requires the following: A working OpenShell installation. Complete the Quickstart before proceeding. A GitHub personal access token (PAT) with repo scope. Generate one from the GitHub personal access token settings page by selecting Generate new token (classic) and enabling the repo scope. An Anthropic account 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 with a README if needed. This tutorial uses two terminals to demonstrate the iterative policy workflow: 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 . Each section below indicates which terminal to use. Set Up a Sandbox with Your GitHub Token Depending on whether you start a new sandbox or use an existing sandbox, choose the appropriate tab and follow the instructions. Starting a new sandbox In terminal 2, create a new sandbox with Claude Code. The default policy is applied automatically, which allows read-only access to GitHub. Create a credential provider 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: $ GITHUB_TOKEN=<your-token\nopenshell provider create --name my-github --type github --from-existing\nopenshell sandbox create --provider my-github --keep -- claude\nThe --keep flag keeps the sandbox running after Claude Code exits, so you can apply policy updates later without recreating the environment. 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. Using an existing sandbox In terminal 1, connect to a sandbox that is already running and set your GitHub token as an environment variable: $ openshell sandbox connect <sandbox-name\nexport GITHUB_TOKEN=<your-token\nTo find the name of running sandboxes, run openshell sandbox list in terminal 2. Push Code to GitHub In terminal 1, ask Claude Code to write a simple script and push it to your repository. Replace <org> with your GitHub organization or username and <repo> with your repository name. Prompt Write a hello_world.py script and push it to https://github.com/<org>/<repo> . 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 In this section, you diagnose the denial from your machine and from inside the sandbox. View the Logs from Your Machine In terminal 2, launch the OpenShell terminal: $ openshell term\nThe 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: l7_action: PUT\nl7_target: /repos/<org>/<repo>/contents/hello_world.py\nl7_decision: deny\ndst_host: api.github.com\ndst_port: 443\nl7_protocol: rest\npolicy: github_rest_api\nl7_deny_reason: PUT /repos/<org>/<repo>/contents/hello_world.py not permitted by policy\nThe 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. Ask Claude Code to Check the Sandbox Logs In terminal 1, ask Claude Code to check the sandbox logs for denied requests: Prompt Check the sandbox logs for any denied network requests. What is blocking the push? 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: Response The sandbox runs a proxy that enforces policies on outbound traffic\nThe github_rest_api policy allows GET requests (used to read the file\nbut blocks PUT/write requests to GitHub. This is a sandbox-level restriction\nnot a token issue. No matter what token you provide, pushes through the API\nwill be blocked until the policy is updated. 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. Update the Policy from Your Machine 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. Prompt Based on the following deny reasons, recommend a sandbox policy update that allows GitHub pushes to https://github.com/<org>/<repo> , and save to /tmp/sandbox-policy-update.yaml : The filesystem_policy , landlock , and process 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, but only the network_policies section takes effect when you apply this to a running sandbox. The following steps outline the expected process done by the agent: Inspects the deny reasons. Writes an updated policy that adds github_git and github_api blocks that grant write access to your repository. Saves the policy to /tmp/sandbox-policy-update.yaml . 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. Full reference policy The following YAML shows a complete policy that extends the default policy with GitHub access for a single repository. Replace <org> with your GitHub organization or username and <repo> with your repository name. The filesystem_policy , landlock , and process 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, but only the network_policies section takes effect when you apply this to a running sandbox. version: 1\n── Static (locked at sandbox creation)\nfilesystem_policy\ninclude_workdir: true\nread_only\n/usr\n/lib\n/proc\n/dev/urandom\n/app\n/etc\n/var/log\nread_write\n/sandbox\n/tmp\n/dev/null\nlandlock\ncompatibility: best_effort\nprocess\nrun_as_user: sandbox\nrun_as_group: sandbox\n── Dynamic (hot-reloadable)\nnetwork_policies\nClaude Code ↔ Anthropic API\nclaude_code\nname: claude-code\nendpoints\n{ host: api.anthropic.com, port: 443, protocol: rest, enforcement: enforce, access: full, tls: terminate\n{ host: statsig.anthropic.com, port: 443\n{ host: sentry.io, port: 443\n{ host: raw.githubusercontent.com, port: 443\n{ host: platform.claude.com, port: 443\nbinaries\n{ path: /usr/local/bin/claude\n{ path: /usr/bin/node\nNVIDIA inference endpoint\nnvidia_inference\nname: nvidia-inference\nendpoints\n{ host: integrate.api.nvidia.com, port: 443\nbinaries\n{ path: /usr/bin/curl\n{ path: /bin/bash\n{ path: /usr/local/bin/opencode\n── GitHub: git operations (clone, fetch, push)\ngithub_git\nname: github-git\nendpoints\nhost: github.com\nport: 443\nprotocol: rest\ntls: terminate\nenforcement: enforce\nrules\nallow\nmethod: GET\npath: \"/<org>/<repo>.git/info/refs\nallow\nmethod: POST\npath: \"/<org>/<repo>.git/git-upload-pack\nallow\nmethod: POST\npath: \"/<org>/<repo>.git/git-receive-pack\nbinaries\n{ path: /usr/bin/git\n── GitHub: REST API\ngithub_api\nname: github-api\nendpoints\nhost: api.github.com\nport: 443\nprotocol: rest\ntls: terminate\nenforcement: enforce\nrules\nGraphQL API (used by gh CLI\nallow\nmethod: POST\npath: \"/graphql\nFull read-write access to the repository\nallow\nmethod:\npath: \"/repos/<org>/<repo\nbinaries\n{ path: /usr/local/bin/claude\n{ path: /usr/local/bin/opencode\n{ path: /usr/bin/gh\n{ path: /usr/bin/curl\n── Package managers\npypi\nname: pypi\nendpoints\n{ host: pypi.org, port: 443\n{ host: files.pythonhosted.org, port: 443\n{ host: github.com, port: 443\n{ host: objects.githubusercontent.com, port: 443\n{ host: api.github.com, port: 443\n{ host: downloads.python.org, port: 443\nbinaries\n{ path: /sandbox/.venv/bin/python\n{ path: /sandbox/.venv/bin/python3\n{ path: /sandbox/.venv/bin/pip\n{ path: /app/.venv/bin/python\n{ path: /app/.venv/bin/python3\n{ path: /app/.venv/bin/pip\n{ path: /usr/local/bin/uv\n{ path: \"/sandbox/.uv/python/**\"\n── VS Code Remote\nvscode\nname: vscode\nendpoints\n{ host: update.code.visualstudio.com, port: 443\n{ host: \"*.vo.msecnd.net\", port: 443\n{ host: vscode.download.prss.microsoft.com, port: 443\n{ host: marketplace.visualstudio.com, port: 443\n{ host: \"*.gallerycdn.vsassets.io\", port: 443\nbinaries\n{ path: /usr/bin/curl\n{ path: /usr/bin/wget\n{ path: \"/sandbox/.vscode-server/**\"\n{ path: \"/sandbox/.vscode-remote-containers/**\" } The following table summarizes the two GitHub-specific blocks: Block Endpoint Behavior github_git github.com:443 Git Smart HTTP protocol with TLS termination. 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 with TLS termination. Permits all HTTP methods for the specified repository and GraphQL queries. Denies API access to unlisted repositories. The remaining blocks ( claude_code , nvidia_inference , pypi , vscode ) are identical to the 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 Network Access Rules . Apply the Policy After you have reviewed the generated policy, apply it to the running sandbox: $ openshell policy set <sandbox-name> --policy /tmp/sandbox-policy-update.yaml --wait\nNetwork 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. Retry the Push In terminal 1, ask Claude Code to retry the push: The sandbox policy has been updated. Try pushing to the repository again\nThe 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. Clean Up When you are finished, delete the sandbox to free cluster resources: $ openshell sandbox delete <sandbox-name\nNext 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 . To learn the full policy iteration workflow (pull, edit, push, verify), refer to /sandboxes/policies . To inject credentials automatically instead of pasting tokens, refer to /sandboxes/providers","format":"text","summary":"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...","headings":[{"text":"Set Up a Sandbox of Claude Code with a Custom GitHub Policy","level":1},{"text":"Prerequisites","level":2},{"text":"Set Up a Sandbox with Your GitHub Token","level":2},{"text":"Push Code to GitHub","level":2},{"text":"Diagnose the Denial","level":2},{"text":"View the Logs from Your Machine","level":3},{"text":"Ask Claude Code to Check the Sandbox Logs","level":3},{"text":"Update the Policy from Your Machine","level":2},{"text":"Review the Generated Policy","level":2},{"text":"Apply the Policy","level":2},{"text":"Retry the Push","level":2},{"text":"Clean Up","level":2},{"text":"Next Steps","level":2}]}
\ No newline at end of file