NVIDIA OpenShell is an open source runtime (Apache 2.0, written in Rust) that runs AI agents inside sandboxes and decides, by policy, which files they can touch, which hosts each program can reach and where real credentials are allowed to go. You run an agent such as OpenCode, Claude Code or Codex inside it, and anything the policy does not allow is denied. It runs on your own machine or cluster, it is free, and it does not need an NVIDIA GPU.
The project has existed since early 2026, but it hit the Hacker News front page on Oct 22, 2026 (more than 400 points) and sat on GitHub's trending list the next morning, a few weeks after the 0.1.x line moved to a stable weekly release cadence. This guide explains how it works, walks through setup, and shows what its policy prover actually reports, from our own test of release 0.1.5.
What NVIDIA OpenShell does
Agents get useful when they can read files, install packages, call APIs and use your keys. That is also how they leak source code or a cloud token. OpenShell's answer is to put each agent in an isolated sandbox and route every connection through a component the agent cannot control.
The architecture docs describe four main pieces:
- Gateway: the control plane. It creates and tracks sandboxes, stores policies and credentials, and handles who can do what. A local install serves it on port 17670 of localhost.
- Supervisor: sits on the trusted side of the boundary. It checks each request against policy, resolves DNS, opens approved connections and inserts credentials.
- Sandbox: shares the boundary with the agent. It launches the agent as a child process, runs it as an unprivileged user with no Linux capabilities, and forwards all TCP and DNS traffic to the supervisor. Landlock limits file access and seccomp limits system calls.
- Providers: named credentials (OpenRouter, Anthropic, GitHub, AWS and so on). The agent only ever sees a placeholder; the supervisor swaps in the real secret for requests to endpoints the provider profile approves.
Policy has four layers, and they change at different times:
| Layer | What it controls | Can it change while the agent runs? |
|---|---|---|
| Filesystem | Paths readable, or readable and writable | No, fixed at startup |
| Process | User and group the agent runs as | No, fixed at creation |
| Network | Which binary can reach which host, port, method and path | Yes, reloads live |
| Provider credentials | Where each secret may be sent | Attachments and rotation update live |
With no policy at all, the restrictive default applies: read only access to system paths such as /usr and /etc, read and write access to the working directory and /tmp, and no outbound network access.
How to install OpenShell and run a first agent
The support matrix lists Linux (Debian or Ubuntu, x86_64 and arm64) and macOS on Apple Silicon with Docker Desktop as supported, and Windows through WSL 2 as experimental. You also need a runtime for the sandboxes: Docker 28.0 or newer, Podman 5, Kubernetes 1.29 or newer through the Helm chart, or a MicroVM backend (KVM on Linux, Hypervisor.framework on macOS).
The official installer sets up the CLI and a local gateway, and a bare sandbox (minimal Ubuntu, no agent inside) takes one more command:
curl -LsSf https://raw.githubusercontent.com/NVIDIA/OpenShell/main/install.sh | sh
openshell sandbox create --name demoTo run a real agent, the first agent walkthrough uses OpenCode with a free OpenRouter model. You import a provider profile that lets only /usr/local/bin/opencode reach openrouter.ai, store your key as a provider, then start a sandbox from the OpenCode image with the agent command after --:
openshell profile import \
--url https://raw.githubusercontent.com/NVIDIA/OpenShell/main/providers/openrouter.yaml
openshell provider create --name openrouter --type openrouter --from-existing
openshell sandbox create --name my-agent \
--from ghcr.io/anomalyco/opencode:latest \
--provider openrouter \
-- opencode -m openrouter/nvidia/nemotron-3.5-lightning:freeWhen the agent hits a host the policy does not allow, the request is denied and OpenShell drafts a narrow rule (one binary, one host and port). You review it from the host with openshell rule get my-agent --status pending, then approve or reject it with a reason. Approved rules load into the running sandbox without a restart. openshell rule approve-all skips anything with a security flag unless you add --include-security-flagged.
The repo ships provider profiles for Claude Code, Codex, Copilot, Cursor, Anthropic, OpenAI, AWS Bedrock, Google Vertex AI, GitHub, PyPI and others, so the same pattern works for Claude Code, Codex or GitHub Copilot CLI. Add --gpu (or --gpu 2) to sandbox create if the agent needs GPUs.
Writing an OpenShell sandbox policy
A policy is YAML with version: 1 and sections such as filesystem_policy, process and network_policies. Most of the work is network rules. Each rule lists endpoints and the binaries allowed to reach them, and can inspect requests. This rule, adapted from the network rules docs, lets curl read the GitHub API but blocks writes:
network_policies:
github_readonly:
endpoints:
- host: api.github.com
port: 443
protocol: rest
enforcement: enforce
access: read-only
binaries:
- path: /usr/bin/curlThree details catch people out:
- List the real executable, not the command.
pipis a Python script, so a PyPI rule must list the interpreter (on Ubuntu 24.04,/usr/bin/python3.12, because/usr/bin/python3is a symlink). OpenShell also hashes each binary the first time it connects and denies it later if the file changes. - Enforcement defaults to audit. Without
enforcement: enforce, a request that breaks a rule is logged but allowed. Audit first, readopenshell logs my-sandbox --source sandbox, then switch to enforce. - Deny beats allow. Rules are not an ordered firewall list. Every matching rule adds access, and any matching deny rule wins.
Request inspection understands REST, WebSocket, GraphQL, JSON-RPC and MCP. An MCP rule can allow tools/list and one named tool while denying another, which pairs well with the servers in our guide to running MCP servers locally.
Checking policies with the OpenShell prover
The feature that sets OpenShell apart is the policy prover, an SMT solver based checker that answers one question: does this candidate policy allow anything beyond a boundary policy? It ships as a standalone openshell-prover binary, reads local files and needs no gateway, so you can run it in CI.
We downloaded the 0.1.5 CLI and prover from the v0.1.5 release (Oct 20, 2026), checked them against the published SHA256 files, and used the GitHub read only rule above as the boundary. Results on our Linux box:
| Candidate policy | Result | Exit code |
|---|---|---|
| Same rule as the boundary | within_boundary | 0 |
access: read-write instead of read-only | exceeds_boundary, counterexample method=POST on api.github.com | 1 |
| Boundary plus a rule for pastebin.com | exceeds_boundary, counterexample host=pastebin.com:443 | 1 |
A rule using protocol: mcp | unsupported: only L4 TCP and REST are modeled | 3 |
Network rule but no filesystem_policy | unsupported: depends on an unresolved image workdir | 3 |
Two lessons. Treat anything other than within_boundary as a failure, as the prover docs say, because unsupported means "not checked", not "fine". And spell out your filesystem section, or the prover cannot reason about it. Add --output json for scripts; it returns a result, a reason_code and the counterexample as fields.
The same engine runs inside the gateway on every rule an agent proposes, flagging new credentialed destinations, new HTTP methods or cloud metadata addresses so they wait for a human.
OpenShell vs Docker, NemoClaw and hosted sandboxes
OpenShell vs Docker. They are not alternatives. Docker (or Podman, Kubernetes or a MicroVM) is the runtime OpenShell uses to create the sandbox. A plain container gives you isolation and usually open network access; OpenShell adds a deny by default network path through the supervisor, per binary rules, request inspection, credential placeholders and the approval flow. If you already run agents in containers, OpenShell is the policy layer on top. Docker Agent is a different thing: a way to define agents, not a security boundary.
OpenShell vs NemoClaw. NemoClaw is NVIDIA's reference stack that runs OpenClaw (its default), Hermes or LangChain Deep Agents Code inside OpenShell sandboxes, with guided onboarding, managed inference and preset policies. OpenShell is the general runtime; NemoClaw is one packaged way to use it.
OpenShell vs E2B, Daytona and Modal. E2B, Daytona and Modal sell sandboxes as a cloud API you call from your app, mostly for running generated code. OpenShell is software you host, built around governing a long running agent and its credentials. Our E2B vs Daytona vs Modal comparison covers the hosted side, and Claude Managed Agents covers a fully hosted harness.
Telemetry, upgrades and limits
- Telemetry is on by default. It sends anonymous counts (sandbox lifecycle outcomes, policy decision counts, denial categories), not prompts, paths, hostnames or credentials, per the telemetry docs. Set
OPENSHELL_TELEMETRY_ENABLED=falseon the gateway, orserver.telemetryEnabled=falsefor Helm, or compile it out. This was the most common complaint in the Hacker News thread. - No upgrade in place from 0.0.x. Version 0.1.0 (Sep 25, 2026) changed protocols and stored formats. You remove old sandboxes, export provider profiles, uninstall, then reinstall.
- Release rhythm. Stable releases generally ship weekly, targeting Tuesdays, and security fixes cover the latest and previous minor versions.
- Name clash. Searching "openshell" also returns Open Shell, the unrelated Windows Start menu project.
Who should use it
OpenShell fits teams that want coding agents running unattended with real credentials and need a written, reviewable answer to "what can it reach?". Policy YAML lives in version control and the prover can gate changes in CI. For a solo developer who just wants a safer local agent, it is more setup than a container, but the default policy (no network until you approve it) is a sensible baseline. If you are choosing the agent itself first, start with our open source coding agents roundup or the agent harness explainer, then add OpenCode or your pick inside an OpenShell sandbox.
FAQ
Is NVIDIA OpenShell free and open source?
Yes. The code is on GitHub under the Apache 2.0 license, and there is no paid tier for the runtime. You pay only for whatever model provider or infrastructure your agents use.
Does OpenShell need an NVIDIA GPU?
No. It runs on Linux and on Apple Silicon Macs with Docker Desktop. GPUs are optional: add --gpu when creating a sandbox for an agent that needs one.
What is the difference between OpenShell and NemoClaw?
OpenShell is the sandbox runtime and policy engine. NemoClaw is a reference stack built on it that installs and runs specific agents (OpenClaw by default, Hermes, or LangChain Deep Agents Code) with preset policies and managed inference.
Does OpenShell work on Windows?
Only through WSL 2 with Docker Desktop, and NVIDIA marks that as experimental. Linux and macOS on Apple Silicon are the supported hosts.
Can I run Claude Code inside OpenShell?
Yes. Claude Code is one of the agents the docs list, and the repo includes a claude-code provider profile. Build or pick an image that contains Claude Code, attach the provider, and pass claude as the command after --.
Is OpenShell the same as Open Shell?
No. Open Shell is an older open source project that restores the classic Windows Start menu. NVIDIA OpenShell is the agent sandbox covered here.
