Tech Teardown 029 | NVIDIA OpenShell: The Secure Runtime for AI Agents

I. What is this?

OpenShell is an open-source security runtime launched by NVIDIA in 2026, specifically designed to restrict autonomous AI agents. Its core principle is that agents can perform tasks but cannot access your files, network, and credentials without limit. The project’s repository is located at NVIDIA/OpenShell on GitHub, with approximately 17,700 stars and 1,800 forks as of October 2026, under the Apache-2.0 license. The repository is primarily built in Rust, consisting of 745 .rs files and about 651,000 lines of code, distributed across 36 crates.

It is neither a chat model nor an agent framework; rather, it serves as a “cage” beneath the agent. You can think of it as an isolation layer for coding agents like Claude Code, Codex, OpenCode, and Copilot CLI. The agent remains responsible for reasoning and calling tools, but whether it can read files, connect to the network, or use API keys is determined by OpenShell’s policies.

NVIDIA positions it as the software foundation for the “Open Agent Safety Platform.” The complete reference architecture also includes Sentry monitoring on Vera CPUs and BlueField-4 DPUs. The software part can run independently on any Linux, macOS Apple Silicon, or WSL2; the hardware-enhancing part requires NVIDIA’s chip stack.

Why is this needed now? Because the way agents work is changing. Previous AI tools were mostly “question-and-answer” models, while today’s coding agents can run continuously for dozens of minutes, calling shells, reading code, installing dependencies, and invoking APIs. Once prompts are injected or the model generates hallucinations, the agent may send internal code to the public network, use up your cloud quota, or even modify production configurations. What OpenShell aims to do is provide an auditable and enforceable boundary for this type of long-term, high-privilege operation.

From a broader perspective, OpenShell also addresses an industry concern: when agents transition from “auxiliary tools” to “automated employees,” who decides what they can and cannot do? Relying solely on the model’s own security alignment is clearly insufficient, as the agent’s tasks may require performing dangerous operations. OpenShell’s answer is to externalize privilege policies and enforce them at runtime, allowing security teams to manage agent boundaries just like managing firewall rules.

II. Core Mechanism

The core architecture of OpenShell can be broken down into three layers: Gateway, Supervisor, and Sandbox.

Gateway is the control plane, responsible for managing the sandbox lifecycle, user authentication, and policy deployment. Supervisor pairs with each sandbox and runs outside of workloads, being the necessary path for all outbound requests. Sandbox, on the other hand, is the isolated environment where agents execute. The main crates in the source code are openshell-gateway, openshell-supervisor, and openshell-sandbox. Among them, openshell-supervisor/src/lib.rs has over 7200 lines, while src/linux/landlock.rs and src/linux/seccomp.rs under openshell-sandbox handle kernel-level restrictions on Linux.

Policies are written in declarative YAML. A simple network policy looks like this: it specifies which binaries can access certain hosts, ports, HTTP methods, and whether they should read or write. Policies are divided into static and dynamic domains: file systems and process identities are locked when the sandbox is created; network, provider, and inference rules can be hot-loaded at runtime. The official quickstart examples/sandbox-policy-quickstart/policy.yaml is a complete example, defaulting to allowing only curl to read-only access to the GitHub API.

At runtime, OpenShell has made a key design change in network paths. Each outbound connection sent by the agent goes through the HTTP CONNECT proxy in supervisor. The source code crates/openshell-supervisor-network/src/proxy.rs handles this process, while crates/openshell-supervisor-network/src/opa.rs embeds an OPA engine that compiles YAML policies into Rego, then makes decisions on Allow/Deny/Route for each request. The OPA evaluation is designed to be in microseconds, preventing the proxy from becoming a bottleneck.

Credential handling is another key point. OpenShell does not write API keys into the sandbox image or file system; instead, it binds them at runtime through the Provider mechanism. Only when a request matches the endpoint allowed by the policy will the corresponding credentials be injected as environment variables. This ensures that even if the agent is compromised, the number of paths to obtain the key is reduced. The related implementation is in crates/openshell-core/src/provider_credentials.rs.

Finally, there is a formal verification layer. openshell-prover encodes policies, binary capabilities, and credential scopes into Z3 SMT constraints to check for unauthorized access or data leakage before policy changes. The source code can be found in crates/openshell-prover/src/lib.rs, which relies on the z3 crate at its core. This means that before a policy takes effect, a proof can be run to confirm no new risks are introduced.

From the perspective of isolation implementation, Linux uses Landlock for file system restrictions, seccomp for filtering system calls, and namespace for process isolation. openshell-sandbox/src/linux/landlock.rs handles path permission lists, while src/linux/seccomp.rs manages seccomp notifications, allowing the supervisor to arbitrate some sensitive calls in user mode. This combination enables tight constraints without a complete virtual machine.

The computational backend is also modular. openshell-gateway/src/lib.rs compiles different compute drivers for platform-specific conditions: Docker, Podman, Kubernetes, VM (libkrun), and Windows MXC. This design allows the same policy model to run on different isolation backends—Docker for development and testing, and Kubernetes or MicroVM for production.

Binary identity is another often overlooked mechanism. OpenShell identifies the identity of executable files that initiate network requests, combining process tree information with /proc/<pid>/cmdline to determine whether a request comes from an allowed binary. This allows policies to track the true source of scripts even if the agent starts a child process through an interpreter. This logic is implemented in openshell-binary-identity and the supervisor’s network proxy.

III. Technical Evaluation

OpenShell’s technical approach is very clear: placing security boundaries outside the agent, using the kernel and policy engine for mandatory isolation, rather than relying on model self-restrictions. The biggest difference from traditional “container isolation” lies in the level of detail and credential management.

Standard containers typically only ensure network connectivity or disconnection, while OpenShell goes into detail regarding HTTP methods, paths, and binary identities. For example, it can allow GET /zen but reject POST issue requests. In containers, API keys are visible throughout once injected, whereas in OpenShell, credentials are only injected when a request hits an authorized endpoint, reducing the window of leakage.

In terms of code size, with 36 crates and 650,000 lines of Rust documentation, this is a serious large-scale project, not just a proof of concept. Among them, the network proxy and OPA integration openshell-supervisor-network accounts for nearly 15,000 lines, the OPA engine files exceed 12,000 lines, the code related to sandbox boundaries amounts to over 7,000 lines, and the prover has several thousand lines. NVIDIA’s official blog provides CoreWeave data: Vera CPU-based sandbox startup is more than 3 times faster than x86, the agentic loop completion time is 1.8 times faster, and a single rack can support over 11,000 concurrent agent environments. These numbers come from vendor self-tests and can serve as a reference but should not be used as a general benchmark.

Compared to other isolation solutions, OpenShell positions itself between containers and full virtual machines. Docker offers only process-level isolation with simple but coarse granularity; Firecracker MicroVM provides near-virtual machine-level isolation but has higher startup and integration costs; gVisor intercepts system calls in user mode with good compatibility but at the cost of performance. OpenShell has chosen a middle path: using Landlock/seccomp for lightweight isolation, supervisor for L7 proxy and credential management, and OPA for policy expression. This approach is particularly suitable for coding agent scenarios because agents need frequent file access and network calls but cannot have full host privileges.

Its weaknesses are also evident. First is maturity: the current version is 0.1.x, and although the README has been changed to a stable release line, Kubernetes support remains labeled as experimental, and some early promotional pages still state “Alpha software — single-player mode”. Second is the coverage of formal verification: the prover can prove properties within the policy model, but the uncertainty of LLMs, prompt injection, and unmodeled interaction paths are not within its scope. Third is deployment complexity: to run effectively, it requires a Linux kernel supported by Docker or Podman, Landlock, or the complete reference architecture of Vera/BlueField-4. Ordinary developers can experience it locally, but enterprise implementation requires significant integration costs.

In terms of ecosystem, OpenShell has made installable agent skills available in the skills/ directory, which can be installed using npx skills add NVIDIA/OpenShell. These skills teach coding agents how to write policies, debug gateways, and troubleshoot inference issues. The repository itself is also developed with an agent-driven workflow, with automated processes like triage, security review, and spike-build in .agents/skills/.

IV. Value Judgment

OpenShell addresses a real issue: when an agent can write code, call APIs, and run for long periods, how to prevent it from “accidentally” leaking internal code to external sources, writing API keys into logs, or executing unauthorized commands due to prompts.

Its value lies in three main scenarios. First is secure coding agents: providing tools like Claude Code and Codex with a restricted environment, allowing only access to specified repositories and APIs. Second is preventing leaked inference routing: forcing model calls to enterprise-controlled endpoints instead of letting the agent decide which models to connect to. Third is compliance auditing: all allow/deny actions are logged in OCSF format, meeting security teams’ requirements for observability.

For users, those most in need of OpenShell are teams that have already allowed agents to access real code repositories, real APIs, and real infrastructure. For individual developers, the risk is low, and whether to install it makes little difference; but for enterprises with large amounts of private code, customer data, and cloud resources, a single mistake by the agent can cause real damage. OpenShell transforms this risk from “uncontrollable” to “strategizable.”

However, its boundaries are clear. It cannot prevent agents from doing bad things within authorized ranges, such as when allowed files contain sensitive content; nor can it replace code review, model security testing, or supply chain security. In other words, OpenShell ensures “whether it can be done,” not “whether it’s done correctly.”

Another point to note is that its true power is amplified when combined with a hardware stack. OpenShell alone provides software boundaries, but when paired with BlueField-4 DPU and Sentry, it enables hardware-level monitoring and isolation beyond the reach of agents. For high-risk scenarios like finance, healthcare, and chip design, this combination of software and hardware is particularly attractive.

V. How to Implement

Installation is simple, just one command:

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

Then create a sandbox:

openshell sandbox create --name demo --policy examples/sandbox-policy-quickstart/policy.yaml

By default, the sandbox hardly allows external network access. To allow an agent to access a service, you need to edit the YAML policy and execute openshell policy set or openshell policy update. If you want to run a real agent, use openshell sandbox create --claude or --codex, and OpenShell will automatically recognize locally configured credentials like ANTHROPIC_API_KEY and OPENAI_API_KEY.

The custom processes of Providers also deserve understanding. First, use openshell provider profile import to import a provider profile, declaring the endpoints allowed access to and the required credentials; then use openshell provider create to create a provider instance; finally, add it through --provider when creating a sandbox. In this way, the agents within the sandbox see placeholder variables, and the actual keys are injected by the supervisor after the request passes the policy check.

For teams wishing to integrate with CI/CD, OpenShell provides GitHub Actions examples: install the CLI in the workflow step, create a sandbox using version-controlled YAML policies, and automatically terminate it with --no-keep after the agent runs. This allows security policies to be reviewed and audited by code.

Selection advice: If you are already using coding agents such as Claude Code / Codex / OpenCode and worried about their unlimited access to local files or networks, OpenShell is worth trying out. If you are an ordinary developer who only occasionally uses AI-assisted editing, its benefits may not outweigh the deployment cost. If your goal is to build a large-scale agent cluster in production environments, it is recommended to wait until Kubernetes support is more mature before evaluating.

VI. How to Build a Similar Solution Yourself

If you do not use OpenShell and want to build your own agent security runtime, you can start with these six steps:

1. Choose a lightweight isolation backend, such as Docker, Podman, or Firecracker MicroVM, and assign an independent container to each agent.
2. By default, deny all outbound network traffic, then use a proxy to intercept all HTTP/HTTPS requests.
3. Write the policy in YAML or JSON, declaring which binaries, users, and endpoints can be accessed, as well as read, write, POST, GET, and other permissions.
4. Place the API key outside the sandbox, with the proxy injecting it when requests hit the white list, rather than inserting it into the container at startup.
5. Use seccomp or Landlock to limit file system access scope, prohibiting setuid, sudo, and other privilege escalation behaviors, while only exposing the read-only paths truly needed by the agent.
6. Record all allow/deny logs and regularly audit policy changes.

Step 3 is often underestimated. Many teams think that writing “allow access to api.github.com” is enough, but when actually putting it into use, it needs to be refined to method, path, and binary identity. Without these dimensions, agents can still bypass the original intention through different tools or scripts. Step 5 also requires attention: read-only paths that contain .env or ~/.ssh may still leak keys, so the principle of least privilege must be fully implemented.

This solution may not match the depth, formal verification, and NVIDIA hardware ecosystem of OpenShell’s OPA/Rego, but it can cover 80% of typical risks for small to medium-sized teams.

Conclusion

OpenShell is a noteworthy initiative in agent security infrastructure. It does not focus on model security or application security; instead, it establishes security boundaries at the runtime layer. For teams that want agents to truly perform tasks, this step is inevitable. The current 0.1.x version is suitable for experimentation and small-scale trials. For large-scale implementation, it is recommended to continuously monitor the maturity of K8s and the community ecosystem.

Reference Sources

• GitHub Repository: NVIDIA/OpenShell, https://github.com/NVIDIA/OpenShell
• NVIDIA Official Introduction: https://www.nvidia.com/en-us/ai/openshell/
• Official Documentation: https://docs.nvidia.com/openshell/latest
• NVIDIA Technical Blog: Inside NVIDIA Sentry: Secure AI Agents at Runtime, https://developer.nvidia.com/blog/inside-nvidia-sentry-secure-ai-agents-at-runtime
• NVIDIA Technical Blog: How NVIDIA OpenShell Reference Architecture Secures and Governs AI Agent Workloads at Scale, https://developer.nvidia.com/blog/how-nvidia-openshell-reference-architecture-secures-and-governs-ai-agent-workloads-at-scale
• NVIDIA Press Release: NVIDIA Launches Open Agent Safety Platform, https://nvidianews.nvidia.com/news/open-agent-safety-platform