Deploy preview for PR 291 🛫

pr-preview/pr-291/about/architecture.json

@@ -1 +1 @@
-{"id":"about/architecture","title":"How OpenShell Works","url":"about/architecture.html","last_modified":"2026-03-14T00:12:41.691001+00:00","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.0.1"},"product":{"name":"OpenShell","version":"0.0.1"},"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}]}
+{"id":"about/architecture","title":"How OpenShell Works","url":"about/architecture.html","last_modified":"2026-03-14T00:20:51.606263+00:00","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.0.1"},"product":{"name":"OpenShell","version":"0.0.1"},"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}]}

pr-preview/pr-291/about/overview.json

@@ -1 +1 @@
-{"id":"about/overview","title":"Overview of NVIDIA OpenShell","url":"about/overview.html","last_modified":"2026-03-14T00:12:41.696175+00:00","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.0.1"},"product":{"name":"OpenShell","version":"0.0.1"},"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}]}
+{"id":"about/overview","title":"Overview of NVIDIA OpenShell","url":"about/overview.html","last_modified":"2026-03-14T00:20:51.611939+00:00","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.0.1"},"product":{"name":"OpenShell","version":"0.0.1"},"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}]}

pr-preview/pr-291/about/release-notes.json

@@ -1 +1 @@
-{"id":"about/release-notes","title":"NVIDIA OpenShell Release Notes","url":"about/release-notes.html","last_modified":"2026-03-14T00:12:41.701612+00:00","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.0.1"},"product":{"name":"OpenShell","version":"0.0.1"},"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}]}
+{"id":"about/release-notes","title":"NVIDIA OpenShell Release Notes","url":"about/release-notes.html","last_modified":"2026-03-14T00:20:51.617016+00:00","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.0.1"},"product":{"name":"OpenShell","version":"0.0.1"},"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}]}

pr-preview/pr-291/get-started/quickstart.json

@@ -1 +1 @@
-{"id":"get-started/quickstart","title":"Quickstart","url":"get-started/quickstart.html","last_modified":"2026-03-14T00:12:41.708132+00:00","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.0.1"},"product":{"name":"OpenShell","version":"0.0.1"},"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}]}
+{"id":"get-started/quickstart","title":"Quickstart","url":"get-started/quickstart.html","last_modified":"2026-03-14T00:20:51.623500+00:00","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.0.1"},"product":{"name":"OpenShell","version":"0.0.1"},"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}]}

pr-preview/pr-291/inference/configure.json

@@ -1 +1 @@
-{"id":"inference/configure","title":"Configure Inference Routing","url":"inference/configure.html","last_modified":"2026-03-14T00:12:41.715434+00:00","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.0.1"},"product":{"name":"OpenShell","version":"0.0.1"},"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 set and openshell inference update save immediately by default. Add --verify when you want the gateway to probe the resolved upstream endpoint before persisting the configuration. --no-verify is also accepted and is currently equivalent to the default; it exists so automation can opt out explicitly before a future default switch. openshell inference get confirms the current saved configuration. To confirm end-to-end connectivity from a sandbox, 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","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}]}
+{"id":"inference/configure","title":"Configure Inference Routing","url":"inference/configure.html","last_modified":"2026-03-14T00:20:51.630573+00:00","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.0.1"},"product":{"name":"OpenShell","version":"0.0.1"},"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 set and openshell inference update save immediately by default. Add --verify when you want the gateway to probe the resolved upstream endpoint before persisting the configuration. --no-verify is also accepted and is currently equivalent to the default; it exists so automation can opt out explicitly before a future default switch. openshell inference get confirms the current saved configuration. To confirm end-to-end connectivity from a sandbox, 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","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}]}

pr-preview/pr-291/reference/default-policy.json

@@ -1 +1 @@
-{"id":"reference/default-policy","title":"Default Policy Reference","url":"reference/default-policy.html","last_modified":"2026-03-14T00:12:41.720508+00:00","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.0.1"},"product":{"name":"OpenShell","version":"0.0.1"},"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 baked into the community base image ( ghcr.io/nvidia/openshell-community/sandboxes/base ) and defined in the community repo’s dev-sandbox-policy.yaml . 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 default policy blocks are defined in the community base image. See the openshell-community repository for the full dev-sandbox-policy.yaml source","format":"text","summary":"The default policy is the policy applied when you create an OpenShell sandbox without --policy. It is baked into the community base image (ghcr.io/nvidia/openshell-community/sandboxes/base) and defined in the community repo’s dev-sandbox-policy.yaml.","headings":[{"text":"Default Policy Reference","level":1},{"text":"Agent Compatibility","level":2},{"text":"Default Policy Blocks","level":2}]}
+{"id":"reference/default-policy","title":"Default Policy Reference","url":"reference/default-policy.html","last_modified":"2026-03-14T00:20:51.635777+00:00","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.0.1"},"product":{"name":"OpenShell","version":"0.0.1"},"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 baked into the community base image ( ghcr.io/nvidia/openshell-community/sandboxes/base ) and defined in the community repo’s dev-sandbox-policy.yaml . 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 default policy blocks are defined in the community base image. See the openshell-community repository for the full dev-sandbox-policy.yaml source","format":"text","summary":"The default policy is the policy applied when you create an OpenShell sandbox without --policy. It is baked into the community base image (ghcr.io/nvidia/openshell-community/sandboxes/base) and defined in the community repo’s dev-sandbox-policy.yaml.","headings":[{"text":"Default Policy Reference","level":1},{"text":"Agent Compatibility","level":2},{"text":"Default Policy Blocks","level":2}]}

pr-preview/pr-291/reference/support-matrix.json

@@ -1 +1 @@
-{"id":"reference/support-matrix","title":"Support Matrix","url":"reference/support-matrix.html","last_modified":"2026-03-14T00:12:41.737505+00:00","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.0.1"},"product":{"name":"OpenShell","version":"0.0.1"},"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 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 Docker Desktop or Docker Engine 28.04 Must be running before any openshell command. Sandbox Runtime Versions Sandbox container images are maintained in the openshell-community repository. Refer to that repository for the current list of installed components and their versions. Container Images OpenShell publishes two container images. Both are published for linux/amd64 and linux/arm64 . Image Reference Pulled When Cluster ghcr.io/nvidia/openshell/cluster:latest openshell gateway start Gateway ghcr.io/nvidia/openshell/gateway:latest Cluster startup (via Helm chart) The cluster image bundles the Helm charts, Kubernetes manifests, and the openshell-sandbox supervisor binary required to bootstrap the control plane. The supervisor binary is side-loaded into sandbox pods at runtime via a read-only host volume mount. The gateway image is pulled at cluster startup and runs the API server. Sandbox images are maintained separately in the openshell-community repository. 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}]}
+{"id":"reference/support-matrix","title":"Support Matrix","url":"reference/support-matrix.html","last_modified":"2026-03-14T00:20:51.652281+00:00","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.0.1"},"product":{"name":"OpenShell","version":"0.0.1"},"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 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 Docker Desktop or Docker Engine 28.04 Must be running before any openshell command. Sandbox Runtime Versions Sandbox container images are maintained in the openshell-community repository. Refer to that repository for the current list of installed components and their versions. Container Images OpenShell publishes two container images. Both are published for linux/amd64 and linux/arm64 . Image Reference Pulled When Cluster ghcr.io/nvidia/openshell/cluster:latest openshell gateway start Gateway ghcr.io/nvidia/openshell/gateway:latest Cluster startup (via Helm chart) The cluster image bundles the Helm charts, Kubernetes manifests, and the openshell-sandbox supervisor binary required to bootstrap the control plane. The supervisor binary is side-loaded into sandbox pods at runtime via a read-only host volume mount. The gateway image is pulled at cluster startup and runs the API server. Sandbox images are maintained separately in the openshell-community repository. 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}]}

pr-preview/pr-291/resources/eula.json

@@ -1 +1 @@
-{"id":"resources/eula","title":"License","url":"resources/eula.html","last_modified":"2026-03-14T00:12:41.740573+00:00","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.0.1"},"product":{"name":"OpenShell","version":"0.0.1"},"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}]}
+{"id":"resources/eula","title":"License","url":"resources/eula.html","last_modified":"2026-03-14T00:20:51.655606+00:00","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.0.1"},"product":{"name":"OpenShell","version":"0.0.1"},"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}]}

pr-preview/pr-291/sandboxes/community-sandboxes.json

@@ -1 +1 @@
-{"id":"sandboxes/community-sandboxes","title":"Community Sandboxes","url":"sandboxes/community-sandboxes.html","last_modified":"2026-03-14T00:12:41.745917+00:00","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.0.1"},"product":{"name":"OpenShell","version":"0.0.1"},"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 the following files: Dockerfile that defines the container image. README.md that describes the sandbox and how to use it. You can also include the following optional files: policy.yaml that defines the default policy applied when the sandbox launches. skills/ that contains agent skill definitions bundled with the sandbox. Startup scripts that are 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}]}
+{"id":"sandboxes/community-sandboxes","title":"Community Sandboxes","url":"sandboxes/community-sandboxes.html","last_modified":"2026-03-14T00:20:51.660937+00:00","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.0.1"},"product":{"name":"OpenShell","version":"0.0.1"},"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 the following files: Dockerfile that defines the container image. README.md that describes the sandbox and how to use it. You can also include the following optional files: policy.yaml that defines the default policy applied when the sandbox launches. skills/ that contains agent skill definitions bundled with the sandbox. Startup scripts that are 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}]}

pr-preview/pr-291/sandboxes/providers.json

@@ -1 +1 @@
-{"id":"sandboxes/providers","title":"Providers","url":"sandboxes/providers.html","last_modified":"2026-03-14T00:12:41.767293+00:00","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.0.1"},"product":{"name":"OpenShell","version":"0.0.1"},"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}]}
+{"id":"sandboxes/providers","title":"Providers","url":"sandboxes/providers.html","last_modified":"2026-03-14T00:20:51.682401+00:00","book":{"title":"NVIDIA OpenShell Developer Guide","version":"0.0.1"},"product":{"name":"OpenShell","version":"0.0.1"},"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}]}