OpenShell on Kubernetes: A guide for platform engineers | CNCF

Enroll your company as a CNCF End User and save more than $10K in training and conference costs
Posted on November 11, 2026 by Jim Bugwadia, Nirmata
CNCF projects highlighted in this post
AI agents do more than call APIs. They run shells, install packages, read files, and open network connections. Often they act on text they pulled from the internet a minute earlier. So every agent is untrusted code that holds real credentials.
OpenShell, started by NVIDIA and now a CNCF Sandbox project, is a runtime for running agents like this safely. OpenShell runs each agent in a sandbox. A trusted supervisor outside the sandbox decides what the agent may reach. You declare four kinds of control in YAML:
For Kubernetes admins, a key point is that OpenShell does not bring its own scheduler. Its Kubernetes backend uses Agent Sandbox, the agents.x-k8s.io Sandbox resource from SIG Apps. Agents show up as Pods, Services, PVCs, Secrets, and NetworkPolicies, which you already know how to run. OpenShell adds what Kubernetes can’t see: which agent is calling, which binary made the request, and whether a given POST may leave the cluster.
A NetworkPolicy can say “this Pod may reach api.github.com on 443.” It cannot say “curl may read issues but not create them.” OpenShell can, and it can change that rule on a running sandbox without a restart.
On Kubernetes, the OpenShell gateway owns every sandbox, and Agent Sandbox turns each one into Pods. The nirmata/demo-openshell repo runs the whole flow on a two-node kind cluster with Kubernetes 1.35, Cilium 1.20, Agent Sandbox v1.0.5, OpenShell 0.1.3, and Kyverno 1.18.2. Its openshell-sandbox-lifecycle.md file describes each step in detail.
Note 1: Currently, OpenShell sandboxes can only be created by calling the Gateway API and not via the Kubernetes API. There is an open issue (openshell/#1719) for a Kubernetes OpenShellSandbox CRD, and an operator.
Note 2: a Supervisor Pod per agent provides strong isolation, but may not scale well in large environments. The roadmap includes flexible deployment options (see RFC 0018).
The gateway creates the Kubernetes objects, and Agent Sandbox creates the agent Pod. The agent Pod has no outbound network access of its own. The supervisor opens the only connection to it, and every request the agent makes goes back over that connection for a policy check. Kyverno checks the Kubernetes objects at admission.
OpenShell checks only the Pod settings it needs to stay safe. Which images run, how big a sandbox can get, which credentials it gets, and who can change OpenShell’s RBAC are left to the platform team.
Agent Substrate is another CNCF project that provides sandboxed execution for agents. Both projects applied, and were accepted, to the CNCF Sandbox in September, 2026 (#522 and #523). Both run each agent in its own sandbox on Kubernetes, but they are built differently. OpenShell uses the SIG Apps Agent Sandbox project. Substrate has its own scheduler, controller, and sandbox runtime.
Lin Sun’s CNCF post, Why sandboxing your agent is not enough, makes the case for Substrate: “Sandboxing your agents is necessary, but not sufficient.” Agent Sandbox is about running agents securely. Substrate is about running them securely and cheaply at scale, by suspending idle agents instead of giving each one a Pod.
Agent Substrate is not meant to be used directly, but requires an orchestration layer like Agent Executor, Kagent, or possibly in the future OpenShell (more on that below).
Three areas that will matter most to Kubernetes cluster admins::
Scaling follows from this. With OpenShell, your application decides how many sandboxes to run, and you size each one when you create it, as the demo does with Kyverno defaults and caps. With Substrate, HPA scales the worker pools, and the number of agents is separate from the number of Pods.
For now, choose based on your workload. If you have many bursty, mostly idle agents, such as one assistant per user, and cost per agent matters most, look at Substrate. If your agents hold real credentials and reach production systems, and you need per-request control and policy on Kubernetes objects, look at OpenShell.
Many large enterprises will likely need a mix eventually, and in the future, you may be able to use both. OpenShell’s RFC 0012, merged Sep 10, 2026, makes isolation a pluggable isolation backend, separate from the supervisor that enforces policy. The team has proposed building a Substrate backend (NVIDIA/OpenShell#3362). OpenShell would keep the policy, credential, and audit controls, and Substrate would add gVisor isolation and suspend and resume that keeps memory.
One blocker is fixed. #3366, merged Sep 21, means the shared contract no longer requires Landlock or seccomp evidence, so a gVisor backend can supply its own. Two pieces are still open: a versioned transport for a backend that runs in a separate process, and a lifecycle operation that keeps memory. As of Oct 11 the issue is open. A contributor has +1’d it and asked whether the maintainers would accept it, but no maintainer has replied yet.
If it is accepted, you would get OpenShell’s per-request policy with Substrate’s density. Until then, the difference for admins is where policy runs. With OpenShell, Kyverno checks the sandboxes themselves. With Substrate, Kyverno checks the worker pools, and per-agent policy is set in Substrate’s own API.
Kubernetes settings decide the sandbox Pod’s image, privileges, resources, credentials, and network rules. OpenShell checks some of these itself (step 6 above). RBAC and Kyverno, or other Kubernetes policy engines, help cover the rest.
Start with RBAC. If only the gateway’s ServiceAccount and the Agent Sandbox controller can create Sandbox resources, other users cannot go around the gateway. Cluster-admins still can. RBAC decides who can use which verb on which resource type. It does not look at what a request contains, and it cannot add defaults. So these questions remain:
Kyverno checks these at admissi