> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.nvidia.com/openshell/v0.0.116/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 autonomous AI agents. Run agents in sandboxed environments that protect your data, credentials, and infrastructure. NVIDIA OpenShell is the safe, private runtime for autonomous AI agents. It provides sandboxed execution environments that protect your data, credentials, and infrastructure. Agents run with exactly the permissions they need and nothing more, governed by declarative policies that prevent unauthorized file access, data exfiltration, and uncontrolled network activity. ## 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 -- claude ``` Refer to the [Quickstart](/get-started/quickstart) for more details. --- ## Explore #### [About OpenShell](/about/overview) Learn about OpenShell and its capabilities. Concept #### [Quickstart](/get-started/quickstart) Install OpenShell and create your first sandbox in two commands. Tutorial #### [Tutorials](/get-started/tutorials) Hands-on walkthroughs from first sandbox to custom policies. Concept #### [Gateways and Sandboxes](/sandboxes/manage-gateways) Deploy gateways, create sandboxes, configure policies, providers, and community images for your AI agents. Concept #### [Inference Routing](/sandboxes/inference-routing) Keep inference traffic private by routing API calls to local or self-hosted backends. Concept #### [Observability](/observability) Understand sandbox logs, access them with the CLI and TUI, and export OCSF JSON records. How-To #### [Reference](/reference/default-policy) Policy schema, environment variables, and default policy details. 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 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.0.116/about/overview.md): OpenShell is the safe, private runtime for autonomous AI agents. Run agents in sandboxed environments that protect your data, credentials, and infrastructure. - [How OpenShell Works](https://docs.nvidia.com/openshell/v0.0.116/about/how-it-works.md): Understand the OpenShell architecture, runtime boundaries, gateways, sandboxes, and ecosystem integration points. - [Installation](https://docs.nvidia.com/openshell/v0.0.116/about/installation.md): Install OpenShell, choose a compute driver, and connect to a gateway. - [Running the Gateway as a Container](https://docs.nvidia.com/openshell/v0.0.116/about/container-gateway.md): Run the OpenShell gateway using docker run or docker-compose without the installer. - [Supported Agents](https://docs.nvidia.com/openshell/v0.0.116/about/supported-agents.md): AI agent frameworks and runtimes compatible with OpenShell sandboxes. - [NVIDIA OpenShell Release Notes](https://docs.nvidia.com/openshell/v0.0.116/about/release-notes.md): Track the latest changes and improvements to NVIDIA OpenShell. - [Quickstart](https://docs.nvidia.com/openshell/v0.0.116/get-started/quickstart.md): Install the OpenShell CLI, connect to a gateway, and create your first sandboxed AI agent. - [Tutorials](https://docs.nvidia.com/openshell/v0.0.116/get-started/tutorials.md): Step-by-step walkthroughs for OpenShell, from first sandbox to production-ready policies. - [Run the Gateway with Docker Compose](https://docs.nvidia.com/openshell/v0.0.116/get-started/tutorials/docker-compose.md): Run the OpenShell gateway as a Docker Compose service and create agent sandboxes. - [Write Your First Sandbox Network Policy](https://docs.nvidia.com/openshell/v0.0.116/get-started/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.0.116/get-started/tutorials/github-sandbox.md): Learn the iterative policy workflow by launching a sandbox, diagnosing a GitHub access denial, and applying a custom policy to fix it. - [Run Local Inference with Ollama](https://docs.nvidia.com/openshell/v0.0.116/get-started/tutorials/inference-ollama.md): Run local and cloud models inside an OpenShell sandbox using the Ollama community sandbox, or route sandbox requests to a host-level Ollama server. - [Route Local Inference Requests to LM Studio](https://docs.nvidia.com/openshell/v0.0.116/get-started/tutorials/local-inference-lmstudio.md): Configure inference.local to route sandbox requests to a local LM Studio server running on the gateway host. - [Refresh Microsoft Graph Credentials with Providers v2](https://docs.nvidia.com/openshell/v0.0.116/get-started/tutorials/microsoft-graph-provider-refresh.md): Configure a Providers v2 Microsoft Graph profile with gateway-managed OAuth2 refresh-token rotation. - [Manage Sandboxes](https://docs.nvidia.com/openshell/v0.0.116/sandboxes/manage-sandboxes.md): Create sandboxes, understand sandbox isolation, and manage the full sandbox lifecycle. - [Manage Gateways](https://docs.nvidia.com/openshell/v0.0.116/sandboxes/manage-gateways.md): Register OpenShell gateways, switch between environments, inspect gateway status, and troubleshoot gateway access. - [Manage Workspaces and Access](https://docs.nvidia.com/openshell/v0.0.116/sandboxes/manage-workspaces.md): Create OpenShell workspaces, assign members, and understand platform and workspace roles. - [Providers](https://docs.nvidia.com/openshell/v0.0.116/sandboxes/manage-providers.md): Create and manage credential providers that inject API keys and tokens into OpenShell sandboxes. - [Providers v2](https://docs.nvidia.com/openshell/v0.0.116/sandboxes/providers-v2.md): Use provider profiles to attach credentials, network policy, and refresh metadata to OpenShell sandboxes. - [Customize Sandbox Policies](https://docs.nvidia.com/openshell/v0.0.116/sandboxes/policies.md): Apply, iterate, and debug sandbox network policies with hot-reload on running OpenShell sandboxes. - [Use Policy Advisor](https://docs.nvidia.com/openshell/v0.0.116/sandboxes/policy-advisor.md): Let sandboxed agents propose narrow policy changes through policy.local while keeping developer approval in the loop. - [Inference Routing](https://docs.nvidia.com/openshell/v0.0.116/sandboxes/inference-routing.md): Understand and configure OpenShell inference routing through inference.local and external endpoints. - [AWS SigV4 Credential Signing](https://docs.nvidia.com/openshell/v0.0.116/providers/aws-sigv4.md): Configure proxy-side AWS SigV4 request signing so sandbox agents can reach AWS services through CONNECT tunnels without holding real credentials. - [Google Cloud](https://docs.nvidia.com/openshell/v0.0.116/providers/google-cloud.md): Authenticate with GCP APIs inside OpenShell sandboxes. - [Google Vertex AI](https://docs.nvidia.com/openshell/v0.0.116/providers/google-vertex-ai.md): Configure OpenShell to route inference traffic through Google Vertex AI, including Anthropic Claude and Gemini models. - [Gateway Interceptors](https://docs.nvidia.com/openshell/v0.0.116/extensibility/gateway-interceptors.md): Extend OpenShell gateway operations with deployment-specific governance and business logic. - [Supervisor Middleware](https://docs.nvidia.com/openshell/v0.0.116/extensibility/supervisor-middleware.md): Configure and operate built-in and operator-run middleware for sandbox HTTP requests and WebSocket messages. - [Accessing Logs](https://docs.nvidia.com/openshell/v0.0.116/observability/accessing-logs.md): How to view sandbox logs through the CLI, TUI, and directly on the sandbox filesystem. - [Sandbox Logging](https://docs.nvidia.com/openshell/v0.0.116/observability/logging.md): How OpenShell logs sandbox activity using standard tracing and OCSF structured events. - [OCSF JSON Export](https://docs.nvidia.com/openshell/v0.0.116/observability/ocsf-json-export.md): How to enable full OCSF JSON logging for SIEM integration, compliance, and structured analysis. - [Set Up OpenShell on Kubernetes](https://docs.nvidia.com/openshell/v0.0.116/kubernetes/setup.md): Deploy the OpenShell gateway to a Kubernetes cluster using the official Helm chart from GHCR. - [Kubernetes Sandbox Topology](https://docs.nvidia.com/openshell/v0.0.116/kubernetes/topology.md): Choose between combined and sidecar supervisor topology for Kubernetes sandbox pods. - [Managing Certificates](https://docs.nvidia.com/openshell/v0.0.116/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.0.116/kubernetes/ingress.md): Expose the OpenShell gateway externally using the Kubernetes Gateway API and a GRPCRoute. - [Access Control](https://docs.nvidia.com/openshell/v0.0.116/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.0.116/kubernetes/openshift.md): Install the OpenShell Helm chart on OpenShift, including the SCC binding and chart overrides required by OpenShift's Security Context Constraints. - [Gateway Authentication](https://docs.nvidia.com/openshell/v0.0.116/reference/gateway-auth.md): Gateway resolution, authentication modes, connection flow, OIDC support, and credential file layout. - [Default Policy Reference](https://docs.nvidia.com/openshell/v0.0.116/reference/default-policy.md): Breakdown of the built-in default policy applied when you create an OpenShell sandbox without a custom policy. - [Policy Schema Reference](https://docs.nvidia.com/openshell/v0.0.116/reference/policy-schema.md): Complete field reference for the sandbox policy YAML including static and dynamic sections. - [Sandbox Compute Drivers](https://docs.nvidia.com/openshell/v0.0.116/reference/sandbox-compute-drivers.md): Reference for Docker, Podman, MicroVM, and Kubernetes sandbox compute drivers. - [Gateway Configuration File](https://docs.nvidia.com/openshell/v0.0.116/reference/gateway-config.md): Reference for the OpenShell gateway TOML configuration file (RFC 0003). - [Support Matrix](https://docs.nvidia.com/openshell/v0.0.116/reference/support-matrix.md): - [OpenShell Security Best Practices for Controls, Risks, and Configuration Guidance](https://docs.nvidia.com/openshell/v0.0.116/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.0.116/security/verify-image-contents.md): Read the SBOM attestation attached to published gateway and supervisor images to audit what each image contains. - [License](https://docs.nvidia.com/openshell/v0.0.116/resources/license.md): NVIDIA OpenShell is licensed under the Apache License, Version 2.0.