NVIDIA OpenShell

OpenShell is the safe, private runtime for autonomous AI agents. It provides sandboxed execution environments that protect your data, credentials, and infrastructure — governed by declarative YAML policies that prevent unauthorized file access, data exfiltration, and uncontrolled network activity.

OpenShell is built agent-first. The project ships with agent skills for everything from gateway troubleshooting to policy generation, and we expect contributors to use them.

Alpha software — single-player mode. OpenShell is proof-of-life: one developer, one environment, one gateway. We are building toward multi-tenant enterprise deployments, but the starting point is getting your own environment up and running. Expect rough edges. Bring your agent.

Quickstart

Prerequisites

• A supported host — macOS, Windows with WSL 2, or Linux.
• A local runtime — Docker, Podman, or host virtualization enabled for MicroVM-backed sandboxes.

Install

Binary (recommended):

curl -LsSf https://raw.githubusercontent.com/NVIDIA/OpenShell/main/install.sh | sh

From PyPI (requires uv):

uv tool install -U openshell

Both methods install the latest stable release by default. To install a specific version, set OPENSHELL_VERSION (binary) or pin the version with uv tool install openshell==<version>. A dev release is also available that tracks the latest commit on main.

Helm chart:

Experimental — the Kubernetes deployment path is under active development. Expect rough edges and breaking changes.

Deploy the OpenShell gateway into a Kubernetes cluster from the OCI chart published to GHCR:

helm install openshell oci://ghcr.io/nvidia/openshell/helm-chart

See deploy/helm/openshell/README.md for available versions, dev tag conventions, and configuration.

For deploying OpenShell on OpenShift, see deploy/helm/openshell/README.md#install-on-openshift.

Create a sandbox

openshell sandbox create -- claude  # or opencode, codex, copilot

The sandbox container includes the following tools by default:

For more details see https://github.com/NVIDIA/OpenShell-Community/tree/main/sandboxes/base.

See network policy in action

Every sandbox starts with minimal outbound access. You open additional access with a short YAML policy that the proxy enforces at the HTTP method and path level, without restarting anything.

# 1. Create a sandbox (starts with minimal outbound access)
openshell sandbox create

# 2. Inside the sandbox — blocked
sandbox$ curl -sS https://api.github.com/zen
curl: (56) Received HTTP code 403 from proxy after CONNECT

# 3. Back on the host — apply a read-only GitHub API policy
sandbox$ exit
openshell policy set demo --policy examples/sandbox-policy-quickstart/policy.yaml --wait

# 4. Reconnect — GET allowed, POST blocked by L7
openshell sandbox connect demo
sandbox$ curl -sS https://api.github.com/zen
Anything added dilutes everything else.

sandbox$ curl -sS -X POST https://api.github.com/repos/octocat/hello-world/issues -d '{"title":"oops"}'
{"error":"policy_denied","detail":"POST /repos/octocat/hello-world/issues not permitted by policy"}

See the full walkthrough or run the automated demo:

bash examples/sandbox-policy-quickstart/demo.sh

How It Works

OpenShell isolates each sandbox in its own container with policy-enforced egress routing. A lightweight gateway coordinates sandbox lifecycle, and every outbound connection is intercepted by the policy engine, which does one of three things:

• Allows — the destination and binary match a policy block.
• Routes for inference — strips caller credentials, injects backend credentials, and forwards to the managed model.
• Denies — blocks the request and logs it.

OpenShell runs a gateway control plane that manages sandbox lifecycle through a configured compute driver. Supported compute platforms include Docker, Podman, MicroVM, and Kubernetes.

Protection Layers

OpenShell applies defense in depth across four policy domains:

Policies are declarative YAML files. Static sections (filesystem, process) are locked at creation; dynamic sections (network, inference) can be hot-reloaded on a running sandbox with openshell policy set.

Providers

Agents need credentials — API keys, tokens, service accounts. OpenShell manages these as providers: named credential bundles that are injected into sandboxes at creation. The CLI auto-discovers credentials for recognized agents (Claude, Codex, OpenCode, Copilot) from your shell environment, or you can create providers explicitly with openshell provider create. Credentials never leak into the sandbox filesystem; they are injected as environment variables at runtime.

GPU Support (Experimental)

Experimental — GPU passthrough works on supported hosts but is under active development. Expect rough edges and breaking changes.

OpenShell can pass host GPUs into sandboxes for local inference, fine-tuning, or any GPU workload. Add --gpu when creating a sandbox:

openshell sandbox create --gpu --from [gpu-enabled-sandbox] -- claude

Docker-backed GPU sandboxes auto-select CDI when available and otherwise fall back to Docker's NVIDIA GPU request path (--gpus all).

Requirements: NVIDIA drivers and the NVIDIA Container Toolkit must be installed on the host. The sandbox image itself must include the appropriate GPU drivers and libraries for your workload — the default base image does not. See the BYOC example for building a custom sandbox image with GPU support.

Supported Agents

Key Commands

--model | Configure theinference.localendpoint. | |openshell logs [name] --tail| Stream sandbox logs. | |openshell term` | Launch the real-time terminal UI for debugging. |

See the full documentation for command guides, tutorials, and reference material.

Terminal UI

OpenShell includes a real-time terminal dashboard for monitoring gateways, sandboxes, and providers — inspired by k9s.

openshell term

The TUI gives you a live, keyboard-driven view of your gateway and sandboxes. Navigate with Tab to switch panels, j/k to move through lists, Enter to select, and : for command mode. Gateway health and sandbox status auto-refresh every two seconds.

Community Sandboxes and BYOC

Use --from to create sandboxes from the OpenShell Community catalog, a local directory, or a container image:

openshell sandbox create --from gemini             # community catalog
openshell sandbox create --from ./my-sandbox-dir   # local Dockerfile
openshell sandbox create --from registry.io/img:v1 # container image

See the community sandboxes catalog and the BYOC example for details.

Explore with Your Agent

Clone the repo and point your coding agent at it. The project includes agent skills that can answer questions, walk you through workflows, and diagnose problems — no issue filing required.

git clone https://github.com/NVIDIA/OpenShell.git   # or git@github.com:NVIDIA/OpenShell.git
cd OpenShell
# Point your agent here — it will discover the skills in .agents/skills/ automatically

Your agent can load skills for CLI usage (openshell-cli), gateway troubleshooting (debug-openshell-cluster), inference troubleshooting (debug-inference), policy generation (generate-sandbox-policy), and more. See CONTRIBUTING.md for the full