> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.nvidia.com/openshell/v0.1.3/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/openshell/_mcp/server. # NVIDIA OpenShell Developer Guide > OpenShell is the safe, private runtime for fleets of autonomous AI agents. Run agents in sandboxed environments that protect your data, credentials, and infrastructure. NVIDIA OpenShell is the safe, private runtime for fleets of autonomous AI agents. It provides sandboxed execution environments that protect your data, credentials, and infrastructure. Agents run with exactly the permissions they need and nothing more, governed by declarative policies that prevent unauthorized file access, data exfiltration, and uncontrolled network activity. > **Note** > > New in OpenShell 0.1.x: a [stable release cadence](/about/support-matrix#releases), new [isolation primitives](/about/architecture), and an expanded [extension surface](/extensibility/overview), along with much more. > > See our [upgrade guide](/upgrade/0-1-0) for everything that's changed. ## Get Started Install OpenShell and create your first sandbox in two commands. ```shell curl -LsSf https://raw.githubusercontent.com/NVIDIA/OpenShell/main/install.sh | sh openshell sandbox create ``` Refer to [Run Your First Agent](/about/run-your-first-agent) for the complete image, provider, and policy workflow. --- ## Explore #### [About OpenShell](/about/overview) Learn about OpenShell and its capabilities. Concept #### [Run Your First Agent](/about/run-your-first-agent) Prepare an image, attach providers, and launch an agent in a sandbox. Tutorial #### [Tutorials](/tutorials) Hands-on walkthroughs from first sandbox to custom policies. Concept #### [Gateways and Sandboxes](/how-it-works/gateways/overview) Deploy gateways, create sandboxes, configure policies, providers, and workload images for your AI agents. Concept #### [Inference](/how-it-works/inference) Attach model providers to selected sandboxes and call their native endpoints without exposing credentials. Concept #### [Observability](/observability) Understand sandbox logs, access them with the CLI and TUI, and export OCSF JSON records. How-To #### [Policies](/how-it-works/policies/overview) Define filesystem, process, and network controls for sandbox workloads. Reference #### [Security Best Practices](/security/best-practices) Every configurable security control, its default, and the risk of changing it. Concept --- > **Notice and Disclaimer** > > This software automatically retrieves, accesses or interacts with external > materials. Those retrieved materials are not distributed with this software > and are governed solely by separate terms, conditions and licenses. You are > solely responsible for finding, reviewing and complying with all applicable > terms, conditions, and licenses, and for verifying the security, integrity and > suitability of any retrieved materials for your specific use case. This > software is provided "AS IS", without warranty of any kind. The author makes > no representations or warranties regarding any retrieved materials, and > assumes no liability for any losses, damages, liabilities or legal > consequences from your use or inability to use this software or any retrieved > materials. Use this software and the retrieved materials at your own risk. > OpenShell is the safe, private runtime for fleets of autonomous AI agents. Run agents in sandboxed environments that protect your data, credentials, and infrastructure. ## Docs - [Overview of NVIDIA OpenShell](https://docs.nvidia.com/openshell/v0.1.3/about/overview.md): OpenShell is the safe, private runtime for fleets of autonomous AI agents. Run agents in sandboxed environments that protect your data, credentials, and infrastructure. - [Architecture](https://docs.nvidia.com/openshell/v0.1.3/about/architecture.md): Understand the OpenShell control plane, sandbox boundary, runtime isolation, and policy-enforced network path. - [Installation](https://docs.nvidia.com/openshell/v0.1.3/about/installation.md): Install OpenShell on a local workstation or Kubernetes. - [Run Your First Agent](https://docs.nvidia.com/openshell/v0.1.3/about/run-your-first-agent.md): Configure a provider, image, and policy to run an AI agent in an OpenShell sandbox. - [Support Matrix](https://docs.nvidia.com/openshell/v0.1.3/about/support-matrix.md): - [Manage Gateways](https://docs.nvidia.com/openshell/v0.1.3/how-it-works/gateways/overview.md): Register OpenShell gateways, switch between environments, inspect gateway status, and troubleshoot gateway access. - [Gateway Authentication](https://docs.nvidia.com/openshell/v0.1.3/how-it-works/gateways/authentication.md): Gateway resolution, authentication modes, connection flow, OIDC support, and credential file layout. - [Gateway Configuration File](https://docs.nvidia.com/openshell/v0.1.3/how-it-works/gateways/configuration.md): Reference for the OpenShell gateway TOML configuration file (RFC 0003). - [Running the Gateway as a Container](https://docs.nvidia.com/openshell/v0.1.3/how-it-works/gateways/container-deployment.md): Run the OpenShell gateway using docker run or docker-compose without the installer. - [Workspaces](https://docs.nvidia.com/openshell/v0.1.3/how-it-works/workspaces.md): Create OpenShell workspaces, assign members, and understand platform and workspace roles. - [Manage Sandboxes](https://docs.nvidia.com/openshell/v0.1.3/how-it-works/sandboxes/overview.md): Create sandboxes, understand sandbox isolation, and manage the full sandbox lifecycle. - [Sandbox Templates](https://docs.nvidia.com/openshell/v0.1.3/how-it-works/sandboxes/templates.md): Define reusable sandbox workload settings and create sandboxes from templates. - [Sandbox Runtimes](https://docs.nvidia.com/openshell/v0.1.3/how-it-works/sandboxes/runtimes.md): Configure the Docker, Podman, MicroVM, or Kubernetes runtime that runs OpenShell sandboxes. - [Providers](https://docs.nvidia.com/openshell/v0.1.3/how-it-works/providers/overview.md): Create and manage credential providers that inject API keys and tokens into OpenShell sandboxes. - [Profiles](https://docs.nvidia.com/openshell/v0.1.3/how-it-works/providers/profiles.md): Use provider profiles to attach credentials, network policy, and refresh metadata to OpenShell sandboxes. - [AWS SigV4 Credential Signing](https://docs.nvidia.com/openshell/v0.1.3/how-it-works/providers/aws.md): Configure proxy-side AWS SigV4 request signing so sandbox agents can reach AWS services through CONNECT tunnels without holding real credentials. - [Google](https://docs.nvidia.com/openshell/v0.1.3/how-it-works/providers/google.md): Authenticate with Google Cloud APIs and Vertex AI inside OpenShell sandboxes. - [Sandbox Policies](https://docs.nvidia.com/openshell/v0.1.3/how-it-works/policies/overview.md): Understand what sandbox policies control and where a sandbox's policy comes from. - [Network Rules](https://docs.nvidia.com/openshell/v0.1.3/how-it-works/policies/network-rules.md): Understand how OpenShell evaluates network rules, and adapt examples for REST APIs, package registries, internal services, WebSocket, GraphQL, MCP, and native TCP. - [Manage Sandbox Policies](https://docs.nvidia.com/openshell/v0.1.3/how-it-works/policies/manage-policies.md): Use the OpenShell CLI to set, inspect, change, verify, and roll back sandbox policies, apply a global policy, and troubleshoot policy problems. - [Policy Prover](https://docs.nvidia.com/openshell/v0.1.3/how-it-works/policies/prover.md): Understand how OpenShell uses the policy prover, and check that a policy grants no more access than a boundary policy you define. - [Policy Advisor](https://docs.nvidia.com/openshell/v0.1.3/how-it-works/policies/advisor.md): Let an agent in a sandbox propose the network rule it needs when OpenShell blocks a request, and control which proposals take effect. - [Default Policy and Baseline Paths](https://docs.nvidia.com/openshell/v0.1.3/how-it-works/policies/default-policy.md): The restrictive fallback policy used when a sandbox has no explicit or embedded policy, and the baseline paths OpenShell adds to sandbox policies. - [Policy Schema Reference](https://docs.nvidia.com/openshell/v0.1.3/how-it-works/policies/schema.md): Fields, defaults, and constraints for the sandbox policy schema. - [Inference](https://docs.nvidia.com/openshell/v0.1.3/how-it-works/inference.md): Grant a sandbox access to model providers through provider profiles, attachments, and native endpoints. - [Extensibility](https://docs.nvidia.com/openshell/v0.1.3/extensibility/overview.md): Understand how OpenShell adapts to deployment-specific infrastructure, governance, and workload requirements. - [Supervisor Middleware](https://docs.nvidia.com/openshell/v0.1.3/extensibility/supervisor-middleware.md): Inspect, block, or change sandbox requests and responses with supervisor middleware. - [Supervisor Middleware Configuration](https://docs.nvidia.com/openshell/v0.1.3/extensibility/supervisor-middleware/configure.md): Attach supervisor middleware to sandbox traffic, register your own middleware services, and observe middleware decisions. - [Supported Operations](https://docs.nvidia.com/openshell/v0.1.3/extensibility/supervisor-middleware/operations.md): Build a middleware service that inspects and changes sandbox HTTP requests, HTTP responses, and WebSocket messages. - [Gateway Interceptors](https://docs.nvidia.com/openshell/v0.1.3/extensibility/gateway-interceptors.md): Extend OpenShell gateway operations with deployment-specific governance and business logic. - [Drivers](https://docs.nvidia.com/openshell/v0.1.3/extensibility/drivers.md): Understand the compute and credential driver extension points in OpenShell. - [Isolation Backends](https://docs.nvidia.com/openshell/v0.1.3/extensibility/isolation-backends.md): Understand the runtime boundary used to launch and supervise sandboxed workloads. - [Accessing Logs](https://docs.nvidia.com/openshell/v0.1.3/observability/accessing-logs.md): How to view sandbox logs through the CLI, TUI, supervisor files, and container logs. - [Gateway Metrics](https://docs.nvidia.com/openshell/v0.1.3/observability/gateway-metrics.md): Scrape Prometheus metrics from the OpenShell gateway, including supervisor session, relay capacity, and peer routing signals for multi-replica deployments. - [Sandbox Logging](https://docs.nvidia.com/openshell/v0.1.3/observability/logging.md): How OpenShell logs sandbox activity using standard tracing and OCSF structured events. - [OCSF JSON Export](https://docs.nvidia.com/openshell/v0.1.3/observability/ocsf-json-export.md): How to enable full OCSF JSON logging for SIEM integration, compliance, and structured analysis. Includes schema version downgrade for AWS Security Lake, Splunk, and CrowdStrike compatibility. - [Telemetry](https://docs.nvidia.com/openshell/v0.1.3/observability/telemetry.md): What anonymous telemetry OpenShell collects and how to disable it at runtime or compile it out. - [Set Up OpenShell on Kubernetes](https://docs.nvidia.com/openshell/v0.1.3/kubernetes/setup.md): Deploy the OpenShell gateway to a Kubernetes cluster using the official Helm chart from GHCR. - [High Availability](https://docs.nvidia.com/openshell/v0.1.3/kubernetes/high-availability.md): Run multiple OpenShell gateway replicas on Kubernetes with shared PostgreSQL, authenticated peer routing, capacity metrics, and optional autoscaling. - [Managing Certificates](https://docs.nvidia.com/openshell/v0.1.3/kubernetes/managing-certificates.md): Configure the OpenShell Helm chart to use cert-manager for mTLS certificate issuance and automatic renewal. - [Ingress](https://docs.nvidia.com/openshell/v0.1.3/kubernetes/ingress.md): Expose the OpenShell gateway externally using the Kubernetes Gateway API and a GRPCRoute. - [Access Control](https://docs.nvidia.com/openshell/v0.1.3/kubernetes/access-control.md): Configure OIDC user authentication or reverse-proxy auth termination for a Kubernetes-deployed OpenShell gateway. - [OpenShift](https://docs.nvidia.com/openshell/v0.1.3/kubernetes/openshift.md): Install the OpenShell Helm chart on OpenShift with capability-free sandbox workloads. - [Migrate Gateway Config](https://docs.nvidia.com/openshell/v0.1.3/kubernetes/migrate-gateway-config.md) - [Tutorials](https://docs.nvidia.com/openshell/v0.1.3/tutorials.md): Step-by-step walkthroughs for OpenShell, from first sandbox to production-ready policies. - [Run Pi with OpenRouter](https://docs.nvidia.com/openshell/v0.1.3/tutorials/run-pi-with-openrouter.md): Build a Pi coding-agent image, configure OpenRouter access, and run Pi inside an OpenShell sandbox. - [Write Your First Sandbox Network Policy](https://docs.nvidia.com/openshell/v0.1.3/tutorials/first-network-policy.md): Learn how OpenShell network policies work by creating a sandbox, observing default-deny in action, and applying a fine-grained L7 read-only rule. - [Grant GitHub Push Access to a Sandboxed Agent](https://docs.nvidia.com/openshell/v0.1.3/tutorials/github-push-access.md): Launch an agent with a GitHub provider, diagnose a denied push, and grant repository-scoped write access. - [Refresh Microsoft Graph Credentials with a Provider Profile](https://docs.nvidia.com/openshell/v0.1.3/tutorials/microsoft-graph-provider-refresh.md): Configure a Microsoft Graph provider profile with gateway-managed OAuth2 refresh-token rotation. - [Go SDK](https://docs.nvidia.com/openshell/v0.1.3/sdk/go.md): Install the OpenShell Go SDK, connect to a gateway, and manage a sandbox. - [Rust SDK](https://docs.nvidia.com/openshell/v0.1.3/sdk/rust.md): Install the OpenShell Rust SDK, connect to a gateway, and manage a sandbox asynchronously. - [Python SDK](https://docs.nvidia.com/openshell/v0.1.3/sdk/python.md): Install the OpenShell Python SDK, reuse a registered gateway, and manage a sandbox. - [TypeScript SDK](https://docs.nvidia.com/openshell/v0.1.3/sdk/typescript.md): Install the OpenShell TypeScript SDK, connect to a gateway, and manage a sandbox. - [API Errors](https://docs.nvidia.com/openshell/v0.1.3/sdk/api-errors.md): Inspect structured gateway failures and choose an appropriate recovery action. - [Protobuf time types](https://docs.nvidia.com/openshell/v0.1.3/sdk/protobuf-time-types.md): Timestamp and duration representation in the OpenShell API - [OpenShell Security Best Practices for Controls, Risks, and Configuration Guidance](https://docs.nvidia.com/openshell/v0.1.3/security/best-practices.md): A guide to every configurable security control in OpenShell: defaults, what you can change, and the risks of each choice. - [Verify the Contents of Published OpenShell Images](https://docs.nvidia.com/openshell/v0.1.3/security/verify-image-contents.md): Read the SBOM attestation attached to published gateway and supervisor images to audit what each image contains. - [Upgrade to NVIDIA OpenShell 0.1.0](https://docs.nvidia.com/openshell/v0.1.3/upgrade/0-1-0.md): Prepare OpenShell operators and users for the breaking changes in version 0.1.0. - [License](https://docs.nvidia.com/openshell/v0.1.3/resources/license.md): NVIDIA OpenShell is licensed under the Apache License, Version 2.0.