NVIDIA OpenShell: a policy-gated runtime for autonomous agents
OpenShell is the safe, private runtime for autonomous AI agents.
At a glance
- What is it?
- OpenShell sandboxes agent workloads in containers and MicroVMs, then enforces filesystem, network, process and credential rules written in YAML. It is alpha software aimed at engineers who need to run coding agents without handing them the host.
- Who is it for?
- Adopt OpenShell if you already run coding agents such as claude, codex or opencode on developer machines and want their outbound traffic filtered at the HTTP method and path level rather than by a blanket network cut. Do not adopt it if you need a stable interface: the project ships a dev release, the Kubernetes path is marked experimental, and filesystem and process policy is locked at sandbox creation, so a wrong path list means recreating the sandbox.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository received new commits within the last day.
- What is it written in?
- Mainly Rust, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem OpenShell is built around
An autonomous agent that can run shell commands, read files and call HTTP APIs has the same reach as the user account it runs under. The README frames the goal as protecting "your data, credentials, and infrastructure" through sandboxed execution governed by declarative YAML. That is a narrower and more concrete claim than general agent orchestration. OpenShell does not decide what the agent should do. It decides what the agent is allowed to touch while doing it.
The target user is an engineer who wants to run an existing agent binary (the sandbox image ships claude, opencode, codex and copilot) without giving it the host filesystem, the host network, or long-lived API keys. The README's own example makes the failure mode explicit: a fresh sandbox cannot even reach api.github.com, and the proxy answers with a 403 after CONNECT. That default is the product. Everything else is a matter of opening specific holes.
Gateway, sandbox, policy engine, provider access
The architecture has four named parts. The gateway is a control-plane API that coordinates sandbox lifecycle and, per the README, "acts as the auth boundary". The sandbox is the isolated runtime with container supervision and policy-enforced egress routing. The policy engine enforces filesystem, network and process constraints, and the README describes that enforcement as running "from application layer down to kernel". Provider access covers profile-defined endpoints, binary policy, and credential injection bound to a specific endpoint.
The data flow for an outbound request is the interesting part. Every connection is intercepted by the policy engine, which does one of three things: allow it when the destination and binary match a policy block; inject provider credentials only after policy admits a request to a profile-authorized endpoint; or deny it and log the denial. That ordering matters. Credentials are not handed to the sandbox at startup and left there. They are attached at the moment a permitted request reaches an authorized endpoint, which limits what a compromised or confused agent can exfiltrate.
Compute is pluggable. The gateway manages sandboxes through a configured compute driver, and the README lists Docker, Podman, MicroVM and Kubernetes as supported platforms. The release list includes a build tagged vm-runtime-capability-free, which suggests the MicroVM path is under active change rather than settled.
Four policy domains and their reload behaviour
OpenShell splits protection into filesystem, network, process and providers. The reload semantics differ by domain, and this is the single most important detail for anyone planning a workflow around it. Filesystem and process policy are locked at sandbox creation. Network policy and provider attachments are hot-reloadable at runtime.
The practical consequence: you can iterate on which HTTP endpoints an agent may reach without tearing anything down, but you cannot widen a path allowlist after the fact. If an agent needs /tmp/build and you did not grant it, the fix is a new sandbox, not a policy edit. The README's quickstart leans on the hot-reloadable half, applying a read-only GitHub API policy to a running sandbox with openshell policy set demo --policy examples/sandbox-policy-quickstart/policy.yaml --wait and then reconnecting.
Enforcement granularity for network traffic is stated as HTTP method and path level. The README's example shows GET https://api.github.com/zen succeeding while POST to the issues endpoint returns a JSON body with error policy_denied and a detail string naming the method and path. That is L7 filtering, not a port allowlist, and it is why the same host can be partly open.
Getting it running: installer, sandbox create, policy set
Prerequisites are a supported host (Linux, macOS on Apple Silicon, or Windows with WSL 2, which the README marks experimental) plus a local runtime: Docker, Podman, or host virtualization for MicroVM-backed sandboxes. The recommended install is the shell installer:
curl -LsSf https://raw.githubusercontent.com/NVIDIA/OpenShell/main/install.sh | sh
The installer takes the latest stable release unless OPENSHELL_VERSION is set. A dev release tracks the tip of main. Note the packaging split: the openshell package on PyPI is the Python SDK only and does not install the CLI, so uv add openshell and the installer are not substitutes for each other.
Creating a sandbox is one command with the agent as an argument:
openshell sandbox create -- claude
The base image carries python 3.14, node 22, gh, git, vim, nano, and a set of network diagnostics including ping, dig, nslookup, nc, traceroute and netstat. That diagnostic set is a deliberate choice: you can debug why a connection failed from inside the sandbox rather than guessing from the host.
Policy changes go through openshell policy set with a name, a --policy path and --wait, followed by openshell sandbox connect to re-enter. For Kubernetes, the README offers helm install openshell oci://ghcr.io/nvidia/openshell/helm-chart and flags the whole deployment path as experimental, with breaking changes expected. OpenShift has a documented variant in the chart README.
Where OpenShell is the wrong tool
The project labels itself alpha, and the release names reinforce that. Alongside v0.0.116 there is a dev build and a MicroVM runtime build, and the version numbering has not reached 0.1. Anyone treating the CLI or policy schema as a frozen interface is reading the repository against its own stated status.
The locked-at-creation domains are a real operational constraint. Filesystem and process policy cannot be adjusted on a live sandbox, so an agent that discovers mid-task that it needs a new writable directory cannot be accommodated without a rebuild. Teams that expect to tune permissions interactively will find the network domain flexible and the other two rigid, which is an asymmetry worth knowing before designing a workflow.
There is also a scope limit: OpenShell constrains what an agent can reach, not what it decides to do. A policy that permits GET on a wide API surface still permits the agent to read anything that API returns. The README says nothing about inspecting or redacting response bodies, so egress filtering is a boundary on destinations, not on content. And the Kubernetes path is explicitly described as under active development, which makes it unsuitable as a production control plane today.
How this differs from container isolation alone
The obvious alternative is running the agent in a plain Docker or Podman container with restricted network access, which is what many teams do now. The difference is where the decision is made. A container with --network=none or a fixed set of reachable hosts decides at the connection level: an endpoint is open or it is not. OpenShell moves the decision up to HTTP method and path, so api.github.com can be readable while writes to it are refused, and the refusal comes back as structured JSON rather than a connection reset.
A second difference is credential handling. In a plain container, API keys are typically injected as environment variables at start, available to any process for the container's lifetime. OpenShell's provider access injects credentials only after policy admits a request to a profile-authorized endpoint, which the README lists as a separate protection layer from network and filesystem. That is a meaningfully different trust model for anyone running agents against paid model APIs.
The cost is complexity. A container with a network flag is one line of configuration. OpenShell adds a gateway process, a compute driver, a policy engine and YAML policy files that must be authored and kept in sync with what the agent actually needs.
Maintenance, licensing and what to check first
OpenShell is Apache-2.0, which permits commercial use, modification and redistribution provided the licence text and notices are preserved. That is a permissive choice, but it is not legal advice, and anyone embedding the runtime in a shipped product should read the LICENSE file and the SECURITY.md disclosure process rather than relying on the badge in the README.
Upgrade cost is hard to estimate from the material available. The project publishes both stable and dev releases and the last push date is recent, so the surface is moving. The presence of a separately tagged MicroVM runtime build suggests that compute path in particular may change shape between versions. Pin OPENSHELL_VERSION in any automated install rather than tracking latest, since the installer defaults to stable but the dev channel exists and is easy to opt into by accident.
Before adopting, the concrete first step is to run the quickstart demo (bash examples/sandbox-policy-quickstart/demo.sh) and then read examples/sandbox-policy-quickstart/policy.yaml to see exactly which methods and paths the example grants. That file, not the README prose, defines the granularity you will actually be working with. If your agent needs writes to a host directory, verify the filesystem policy syntax supports it before building anything around the tool, because that domain cannot be adjusted after the sandbox is created.
Editorial conclusion
Adopt OpenShell if you already run coding agents such as claude, codex or opencode on developer machines and want their outbound traffic filtered at the HTTP method and path level rather than by a blanket network cut. Do not adopt it if you need a stable interface: the project ships a dev release, the Kubernetes path is marked experimental, and filesystem and process policy is locked at sandbox creation, so a wrong path list means recreating the sandbox. Before committing, run the quickstart demo script, then inspect the policy YAML it applies and confirm which rules are hot-reloadable and which require a new sandbox.
Community notes