OpenShell
SHA-256OpenShell is NVIDIA's open-source runtime for running autonomous AI agents safely. Unlike plain Docker sandboxes or E2B, it enforces kernel-level policy on every file access, syscall, and network connection, and brokers credentials only to approved endpoints—so agents get real capabilities without ever seeing your secrets.
Smart Download
Download Download Version
v0.1.4 · 72.5 MB
A kernel-enforced, policy-driven sandbox runtime that lets autonomous AI agents work freely without ever touching your real secrets.
Core Features
- Kernel-level sandbox enforcing policy on every file access, syscall, and network connection
- Formally verified policy changes that flag risky new access for human review before applying
- Credential brokering: secrets are injected only into requests bound for approved endpoints
- GPU-capable sandboxes, SDKs for Python/TypeScript/Go/Rust, and Helm-based Kubernetes deployment
What It Can't Do
- •Windows support is experimental and only works through WSL2—there is no native Windows runtime. It is not a standalone app: Docker, Podman, or host virtualization is required. The default sandbox is a minimal Ubuntu image with no agent installed, so you must wire up models and policies yourself. Anonymous telemetry is on by default; disable it with OPENSHELL_TELEMETRY_ENABLED=false. It is not a silver bullet—overly permissive policies can still grant agents too much access, and Kubernetes deployments require a CNI that enforces NetworkPolicy.
Use Cases
- Running coding agents like OpenCode locally without exposing your files or credentials
- Operating fleets of autonomous agents with centralized, auditable access policies
- Letting agents call third-party APIs while real credentials stay brokered by the gateway
Detailed Introduction
OpenShell is NVIDIA's Apache-2.0 licensed runtime for fleets of autonomous AI agents, designed to give agents real capabilities—reading files, installing packages, calling APIs—without unrestricted access to your data, secrets, or network. Compared with generic isolation tools like plain Docker sandboxes or E2B, OpenShell stands out in two ways: it enforces policy at the kernel level on every file access, system call, and network connection, and it formally verifies policy changes before they are applied, flagging risky new access for human review. Credentials are brokered by a gateway and injected only into requests bound for approved endpoints, so agents never see real secrets. The project ships a CLI, declarative filesystem/network/process policies, GPU-capable sandboxes, SDKs for Python, TypeScript, Go, and Rust, and a Helm chart for Kubernetes. It runs on Linux, Apple Silicon macOS, and experimentally on Windows via WSL2, backed by Docker, Podman, or host virtualization. Anonymous telemetry is enabled by default but can be disabled or compiled out entirely.
Troubleshooting & FAQ (2)
ConfigurationDoes the OpenShell sandbox service account require the privileged SCC on OpenShift?
No. Since the SCC-aware UID resolution was added (PR #3110, plus the annotation-wait fix in #4054), the privileged SCC grant for openshell-sandbox is obsolete in most deployments. The Kubernetes driver reads the namespace's sa.scc.uid-range annotation and assigns the sandbox pod a UID from that range (e.g. runAsUser: 1001150000 from range 1001150000/10000), so the pod satisfies the default restricted-v2 SCC admission with zero privileged grants.
To deploy without the grant:
1. Install the gateway via the Helm chart using the values-openshift-scc.yaml overlay, which nulls the hardcoded runAsUser/fsGroup so restricted-v2 can inject the namespace-assigned UID range.
2. Do not run oc adm policy add-scc-to-user privileged -z openshell-sandbox; verify with oc get scc privileged -o jsonpath='{.users}' that no entry exists for the SA.
3. Sandbox create/exec/delete work normally under restricted-v2, with processes running under the expected SELinux container_t label.
Fallback (explicit grant may still be needed): workloads that depend on a fixed UID — for example images that own files as UID 1000, like e2e/python/Dockerfile.workload — will run under the namespace-assigned UID instead. For those cases, set sandbox_uid explicitly or keep the SCC grant for that specific workload. Note the older docs (debug skill skills/debug-openshell-cluster/SKILL.md and e2e/with-kube-gateway.sh) predate the fix and still claim the grant is required.
TroubleshootingWhy does the first Kubernetes conformance test time out waiting for a workload Pod right after guest boot, and how do I fix it?
Cause: The conformance playbook only waits for gateway connectivity after each guest boot, but gateway connectivity and controller Deployment availability do not prove the Agent Sandbox workload controller can create Pods. After a fresh boot the controller may still be recovering — restarting on Kubernetes API certificate verification errors, then waiting for leader election — leaving a ~11 second gap before it reconciles workload Pods. The first sandbox creation then hits its 30-second timeout while later scenarios pass.
Workaround: Rerun the CI lane. The failure is intermittent and unchanged reruns typically pass, but this wastes CI resources.
Permanent fix: Add a bounded readiness check after each guest boot that verifies controller-owned Pod creation before running any scenario. Configure the probe Pod so it cannot actually run or pull an image (keeps it gated), and clean it up on both success and failure. On readiness failure, skip conformance and collect diagnostics: controller state, leader leases, events, and bounded startup plus recent controller logs. Do not change production provisioning deadlines.
Reproduce locally with: nix run .#tmachine -- test ubuntu-k3s k3s conformance, then compare gateway connectivity timing against controller restarts, leader leases, and first workload Pod creation.
Tags
Getting Started
Download installer
Click the button above to download the installer for your system
Install the software
Install the appropriate package for your distro (dpkg / rpm / AppImage)
Make sure you are on Linux, an Apple Silicon Mac, or Windows with WSL2, and have Docker or Podman installed
Run curl -LsSf https://raw.githubusercontent.com/NVIDIA/OpenShell/main/install.sh | sh to install the CLI and a local gateway
Create your first sandbox with openshell sandbox create --name demo
- Make sure you are on Linux, an Apple Silicon Mac, or Windows with WSL2, and have Docker or Podman installed
- Run curl -LsSf https://raw.githubusercontent.com/NVIDIA/OpenShell/main/install.sh | sh to install the CLI and a local gateway
- Create your first sandbox with openshell sandbox create --name demo
SHA-256 checksum verified
Checksum extracted from GitHub official Release page
SHA256 Checksum
43f43554bcaabff2a8147444410d1ad0b7f51bdae7589c2d249982bc8b260b91This checksum is extracted from the GitHub Release page. Verify file integrity after download.
All SHA-256 checksums on this platform are extracted from the project's official GitHub Release page, without any modification. You can independently verify them on the GitHub Releases page.
Open Source Transparency
View GitHub SourceUninstall Info
No official uninstall script is documented. To remove OpenShell manually: delete the openshell CLI binary, remove the ~/.openshell configuration directory, stop and remove the local gateway container, and prune sandbox images from Docker/Podman. For Helm-based deployments, run helm uninstall in the release namespace.
No Extra Dependencies
Ready to use after download. No additional runtime required.
Having issues? Check the FAQ below
2 FAQs
Similar Projects
gemini-cli
Google's open-source terminal AI agent for coding, debugging, and workflow automation powered by Gemini models.
ollama
Ollama lets you download, run, and manage large language models locally. One command, multiple platforms, endless possibilities.
ComfyUI
ComfyUI is a modular AI engine with a node-based graph interface for generating images, video, 3D models, and audio. Unlike traditional webui tools, it gives pixel-level control over every model and parameter, making it the preferred choice for professionals.