OpenShell vs Agent Substrate vs Kubernetes Agent Sandbox
OpenShell is an open-source runtime that confines each AI agent with kernel controls and a declarative YAML policy. Agent Substrate runs stateful agent actors on pre-warmed workers and checkpoints idle ones. Kubernetes Agent Sandbox, from the kubernetes-sigs project, manages isolated, stateful, singleton Sandbox workloads. They solve different problems, so compare them by what each one controls.
Checked against the NVIDIA OpenShell docs at commit a28f59b, the Agent Substrate README and quickstart on its main branch, and the Agent Sandbox README and quickstart on its main branch, as fetched on 2026-11-09. This post is part of our AI agent governance work, and it builds on our OpenShell on Kubernetes guide.
What each project manages
Each project draws its boundary at a different place. Read the table before you read the sections below, because the same word, sandbox, means a different thing in each one.
OpenShell
OpenShell governs what an agent can touch. The gateway is the control plane. For each sandbox, a compute driver starts a workload and a separate supervisor. The supervisor is the trusted side: it checks each network request against policy and adds credentials only where policy allows.
Agent Substrate
Agent Substrate separates the actor from the worker. The project describes an actor as a stateful agent or workload instance, and a worker as a pre-warmed sandbox. Idle actors are checkpointed to object storage and evicted from compute, and the node-level supervisor restores them when the next request arrives. The README calls it a low-opinion runtime, not an agent SDK.
Agent Sandbox
Agent Sandbox centers on a Sandbox resource. The README describes a Sandbox as a single stateful pod with a stable identity and persistent storage. Extensions add SandboxTemplate, SandboxClaim and SandboxWarmPool, so you can create Sandboxes from a warm pool without writing each pod spec yourself.
Comparison table
| Project | Unit it manages | Where it runs (as documented) | Isolation mechanism (as documented) | Policy model | Kubernetes requirement |
|---|---|---|---|---|---|
| OpenShell | A sandbox with one agent workload and a supervisor beside it | Docker, Podman, Kubernetes, VM compute runtimes | Landlock for filesystem access, seccomp user notification for network operations, one non-root identity with no Linux capabilities on the Linux backend | Declarative YAML policy for files, processes, network destinations and API calls | None; Kubernetes is one runtime |
| Agent Substrate | A stateful actor mapped onto a pre-warmed worker | Kubernetes; the quickstart uses a local kind cluster | Described as zero-trust sandboxing; the quickstart names a default-deny credential namespace policy | Credential provider with a default-deny namespace policy; namespaces are granted to an atespace | Yes |
| Agent Sandbox | A Sandbox: one stateful pod with stable identity and storage | Kubernetes 1.25 or later | Default kind cluster has no container isolation; gVisor or Kata Containers optional through runtimeClassName | Not described in the pages checked | Yes |
Sources: OpenShell architecture and OpenShell overview, Agent Substrate README, Agent Substrate overview, Agent Substrate quickstart, Agent Sandbox README, Agent Sandbox quickstart.
How OpenShell enforces policy
OpenShell applies policy in layers, and each layer has a different timing rule. The overview page sets out which controls lock when the sandbox starts and which can change while it runs. That timing matters when you plan a rollout, because a filesystem rule you need to change means a new sandbox.
| Layer | What it protects | When it applies |
|---|---|---|
| Filesystem | Reads and writes outside allowed paths | Locked at sandbox creation |
| Network | Unauthorized outbound connections | Hot-reloadable at runtime |
| Process | Privilege escalation and dangerous syscalls | Locked at sandbox creation |
| Provider credentials | Opaque credential placeholders, resolved only at profile-authorized endpoints | Attachments, rotation and revocation update at runtime |
The architecture page adds one control that neither of the other two projects documents in these pages. A policy change proposed by the agent goes through a policy prover in the gateway. The prover flags new credentialed reach, new HTTP methods and access to cloud metadata endpoints, and any finding blocks auto-approval. The same prover ships as the standalone openshell-prover command, so you can check a policy in CI.
Where Agent Substrate and Agent Sandbox differ
Both projects run on Kubernetes and both keep state for an agent between requests. They keep it in different ways. Agent Sandbox keeps a pod alive with a stable identity and persistent storage. Agent Substrate moves the actor’s memory and filesystem to object storage when it goes idle, then restores it on the next request on a worker pod.
The Agent Substrate overview states the restore time as under 500 ms. The quickstart says the counter actor resumes with its state intact, and that snapshots are stored in an in-cluster S3-compatible service. The Agent Sandbox pages checked do not describe a checkpoint or restore step, so do not assume one exists.
Try the Agent Sandbox quickstart
The Agent Sandbox README pins its example to release v1.0.2. Use the same tag in your install, or replace it with the release you choose and verify.
These commands come from the upstream README. We have not run them yet.
kind create cluster --name agent-sandbox-demo
export VERSION="v1.0.2"
kubectl apply -f https://github.com/kubernetes-sigs/agent-sandbox/releases/download/${VERSION}/sandbox-with-extensions.yaml
kubectl wait --for=condition=Ready pod -l app=agent-sandbox-controller -n agent-sandbox-system --timeout=120s
kubectl create namespace agent-sandbox-demo
pip install k8s-agent-sandboxThe cluster is created first, so the controller is installed into it and not into whatever context your kubeconfig already points to.
The quickstart creates a demo cluster, waits for the controller, and deploys a router that the Python client uses to reach sandboxes.
The quickstart prerequisites are Docker 20.10 or later, kubectl 1.28 or later, kind 0.20 or later and Python 3.9 or later. After the cluster is ready, the Python client creates a Sandbox from a warm pool and runs a command in it. The client README gives this example in tunnel mode. It uses the python-warmpool pool and the agent-sandbox-demo namespace that the quickstart creates; the quickstart’s SandboxTemplate and router must be in place first.
from k8s_agent_sandbox import SandboxClient
from k8s_agent_sandbox.models import SandboxLocalTunnelConnectionConfig
client = SandboxClient(
connection_config=SandboxLocalTunnelConnectionConfig()
)
sandbox = client.create_sandbox(warmpool="python-warmpool", namespace="agent-sandbox-demo")
print(sandbox.commands.run("echo 'Hello from Local!'").stdout)
sandbox.terminate()The README describes the client as a simple, high-level interface for creating and interacting with sandboxes. Its install command for the published package is pip install k8s-agent-sandbox.
Try the Agent Substrate quickstart
The Agent Substrate quickstart deploys the control plane and a stateful counter sample onto a local kind cluster. It names Go, kubectl and Docker as prerequisites, and it notes that a Linux host running more than about a thousand sandboxes needs a larger kernel neighbor table. The page does not state a release version, so record the commit you use.
These commands come from the upstream quickstart. We have not run them yet. Clone the repository and run everything from its root.
git clone https://github.com/agent-substrate/substrate.git
cd substrate
hack/create-kind-cluster.sh
export ATE_INSTALL_KIND=true
go run ./cmd/ate-setup deploy ate-system --credential-provider='{"name":"k8s.io"}' \
--ingress-allowed-spiffe-ids=spiffe://cluster.local/ns/ate-system/sa/atenet-client
go run ./cmd/ate-setup deploy demo counter
go install ./cmd/kubectl-ate
kubectl ate create actor my-counter-1 -a ate-demo-counter --template counter
kubectl ate proxy actor my-counter-1 -a ate-demo-counterThe proxy command forwards traffic to the actor, and the last step sends a POST with curl to http://localhost:8000/. The page says the bundled credential provider has an empty, default-deny namespace policy, and that an atespace must be granted namespaces before credentials can be injected.
Maturity and what to verify before you adopt
The three projects are at different stages, and the pages do not all agree on maturity. Agent Substrate’s README says it has reached 1.0, while its Developing section calls the project very young. Agent Sandbox publishes version numbers and install paths, and its README gives a minimum Kubernetes version. OpenShell’s overview refers to a stable release cadence starting with 0.1.x.
Before you adopt any of the three, check these items in order:
- The release you plan to run, and the version your install command pins.
- The minimum Kubernetes version and the CRDs that version installs.
- The default isolation: whether the default runtime class provides any container isolation.
- Which network path an agent’s traffic takes, and where the policy decision happens.
- Whether a checkpoint or restore step exists, and where its state is stored.
Decision checklist
Choose by the control you need first, then by the platform.
- If you need per-request network and credential decisions for an agent process on any host, start with OpenShell.
- If you need many stateful agent actors that sleep and wake on demand, look at Agent Substrate.
- If you want a Kubernetes-native Sandbox resource with warm pools and a Python client, look at Agent Sandbox.
- If you already run Kubernetes policy engines, plan how the sandbox pods are admitted and how their egress is limited, whichever project you pick.
- Test the project you pick on the release you will run in production, and record the version in your rollout notes.
Where governance fits
None of the three projects replaces a governance layer for every agent in your organization. The AI agent governance pillar sets out the controls, and the sandboxing guide for Kubernetes shows how a Sandbox pod gets a RuntimeClass and a default-deny NetworkPolicy, and how RBAC and admission control limit who can create Sandbox resources. Use these posts with the project you choose, because each project covers part of the path an agent takes from request to action.
Frequently asked questions
Does OpenShell need Kubernetes?
No. The OpenShell architecture page lists four compute runtimes: Docker, Podman, Kubernetes and VM. Each runtime places the supervisor, connects it to the sandbox and builds the network fence with its own tools. The shared supervisor and policy engine make the same policy decisions on every runtime. If you run agents on a laptop or a single host, Docker or Podman is a valid choice.
Does Agent Sandbox isolate the agent by itself?
Not by default. The quickstart runs on a basic kind cluster without container isolation. To get stronger isolation, the quickstart says you can configure gVisor or Kata Containers as the runtime, by uncommenting the runtimeClassName line in the SandboxTemplate before you apply it. The quickstart does not describe the default runtime class, so do not assume the default adds isolation.
Which Kubernetes version does Agent Sandbox need?
The README says Agent Sandbox requires Kubernetes 1.25 or later and recommends 1.29 or later. The Gateway API v1.5.0 CRD bundle that the README references needs Kubernetes 1.31 or later, because of its TLSRoute validation. Check these numbers against the release you install, since the README is the source for the minimum.
Is Agent Substrate ready for production?
The README says Agent Substrate has reached 1.0 and commits to stability of its public API, CLI and configuration formats. Its Developing section also calls the project very young. The two statements conflict, so read the current release notes and the project status text before you depend on it in production.