OpenShell is NVIDIA's open-source runtime for running AI agents without handing them the keys to everything. The README sums up the problem: agents are most useful when they can "read files, install packages, call APIs, and use credentials," and that's exactly what makes them dangerous. OpenShell lets you write down what each agent may touch, then enforces it.
It's on GitHub Trending today with about 18,700 stars, and it's licensed under Apache-2.0.
What it does
Every agent runs in its own isolated sandbox. A policy you write decides which files it can read and write, which processes and system calls it can use, and which network hosts and APIs it can reach. When an agent wants something new, say a package registry it hasn't touched before, the change goes through an approval step instead of just happening.
The part I like best is how it handles credentials. Agents never see your real API keys or tokens. OpenShell adds credentials to outgoing requests only when those requests are headed for endpoints you've approved. An agent that gets talked into sending its secrets somewhere has no secrets to send.
How it works
The README describes two layers.
Kernel-level enforcement. OpenShell instruments the kernel to check every file access, system call and network connection at runtime. Network traffic passes through a policy check before it leaves the sandbox. These rules aren't suggestions in the agent's system prompt. They're enforced whether the agent cooperates or not.
Formally verified policy changes. When a policy changes, OpenShell uses formal verification to work out what new access the change would actually grant, flagging things like "this lets the agent reach a new host with credentials" or "this allows a new API method." Risky changes wait for a human to review them. The docs call these tools the policy advisor and the prover.
Around that sits a gateway, the control plane that manages sandboxes, policies and access. It can run locally or on Kubernetes via Helm. Sandboxes run under Docker, Podman or host virtualization, and the docs cover custom images, GPUs and lifecycle management. Credentials are handled by "providers," which also route model inference traffic.
Trying it
You need Linux, macOS on Apple Silicon, or Windows with WSL 2 (experimental), plus Docker, Podman or host virtualization. Then:
curl -LsSf https://raw.githubusercontent.com/NVIDIA/OpenShell/main/install.sh | sh
openshell sandbox create --name demoThat installs the CLI and a local gateway, then creates a sandbox. The default image is a minimal Ubuntu with no agent inside, so it's an empty room until you put something in it. The "Run Your First Agent" guide runs the OpenCode coding agent against a free OpenRouter model and walks through approving new access as the agent asks for it.
There are SDKs for driving a gateway from your own code in Python (uv add openshell), TypeScript, Go and Rust. There's also a set of agent skills that teach coding assistants to use the CLI and write policies:
npx skills add NVIDIA/OpenShellThe fine print
- It's young. The 0.1.x series just introduced a stable release cadence, new isolation primitives and new APIs, with an upgrade guide for people coming from earlier builds. Expect things to keep shifting.
- Telemetry is on by default. The project says it collects only anonymous operational counts, with no prompts, paths, hostnames, credentials or model names. You can turn it off with
OPENSHELL_TELEMETRY_ENABLED=falseon the gateway, or compile it out entirely. - Kubernetes needs real network policy. If you deploy the gateway on a cluster, your CNI has to enforce
NetworkPolicy, or the network rules don't mean much. - A sandbox is only as good as its policy. OpenShell gives you the enforcement and the review tooling, but deciding what an agent should be allowed to do is still your job.
Who it's for
OpenShell is for anyone letting AI agents run unattended: teams running coding agents in CI, companies running fleets of agents that touch internal systems, and individuals who want to try an agent without giving it their home directory and every API key on the machine. If you've ever approved an agent's shell command and hoped for the best, this replaces hope with a policy.
The GitHub repo and the documentation are the places to start, and it's in the resource index now.
End of transmission.