Agent Sandbox — K8s Orchestration for AI Agent Runtimes
Table of Contents
I recently ran into a Kubernetes SIG project: Agent Sandbox (kubernetes-sigs/agent-sandbox)
The name says Agent, so it’s easy to mistake for another prompt / multi-agent framework. It isn’t — it’s lower-level and ops-shaped: a declarative API on Kubernetes for singleton, stateful, isolated sandbox runtimes, especially when an AI agent needs to run code you wouldn’t trust on the host
Repo: https://github.com/kubernetes-sigs/agent-sandbox
Docs: https://agent-sandbox.sigs.k8s.io
What gap does it fill?
Kubernetes already covers two shapes well:
- Deployment: stateless, replicated, disposable
- StatefulSet: ordinal identity, but oriented toward a set of stateful services
Agent workloads often look like this instead:
- The model emits code / shell you must actually run in-cluster
- That code is untrusted → needs isolation (not bare host kernel)
- The session should live a while: disk, processes, network identity
- Often one user / one task → one singleton container, not a replica set
You can fake it with StatefulSet replicas=1 plus Service + PVC, but it’s noisy and still lacks pause, hibernate, templates, and warm pools for fast claim
Agent Sandbox targets that gap: a proper CRD for singleton stateful sandboxes
What it is / isn’t
Agent Sandbox = a sandbox orchestrator on Kubernetes
You declare a sandbox; the controller creates/manages the Pod;
strong isolation comes from the RuntimeClass (gVisor, Kata, …)
Boundaries:
- It does not reinvent a secure container kernel
- It is not LangChain / AutoGPT
- It is the standard way to open sandboxes, attach storage, keep identity, and manage lifecycle in-cluster
For platform engineering that matters: once agent products scale, you eventually land on tenant-grade isolated runtimes
Core objects
Main resource: Sandbox CRD (API group agents.x-k8s.io):
- Stable identity (hostname / network)
- Persistent volumes across restarts
- Lifecycle: create, TTL delete, suspend / resume, …
Extensions with readable names:
| Resource | Role |
|---|---|
SandboxTemplate |
templates so you don’t copy YAML |
SandboxWarmPool |
warm pool for faster claim |
SandboxClaim |
claim a sandbox (optionally from the pool) |
Flow: create a Sandbox directly, or Claim from a WarmPool → controller starts a Pod → RuntimeClass → gVisor / Kata
Minimal shape:
apiVersion: agents.x-k8s.io/v1beta1
kind: Sandbox
metadata:
name: my-sandbox
spec:
podTemplate:
spec:
containers:
- name: my-container
image: <IMAGE>
Apply the controller manifests, then kubectl apply. Go / Python SDKs exist for programmatic use
Where it sits in an “AI Agent” stack
| Layer | Typical pieces | Agent Sandbox? |
|---|---|---|
| Plan / reason | model, prompts, skills, tool choice | no |
| Tool protocol | MCP, function calling | no |
| Execution | run code, deps, files, network | yes |
| Isolation strength | gVisor / Kata / runc | orchestrate + pick RuntimeClass |
If Cursor / an in-house agent / an enterprise Copilot needs to run generated code on the cluster, you hit sandbox orchestration. Teams used to invent Pod + PVC + NetworkPolicy; SIG Apps is pushing a more standard Sandbox API — that’s why it’s worth watching
The project also calls out cloud IDEs, Jupyter-style sessions, and single-pod services that want stable identity without a full StatefulSet. Agent is the headline, the API isn’t locked to agents
Why glance at it
- Workloads are shifting toward many short/medium stateful, isolated sessions
- LLM-generated code is untrusted by default — Namespace + RBAC alone rarely lets you sleep
- Cold start is product UX — WarmPool / Template / Claim take that seriously
- Programmatic consumption beats hand-rolled YAML — same direction as platform engineering
Living under kubernetes-sigs / SIG Apps means “sandbox workloads” are being treated as a real workload type, not a vendor toy
Install intuition
Official merged manifests (Core + Extensions) via kubectl apply, fine for Argo CD / Kustomize. Details: Getting Started. Read the Threat Model before production
How this ties to what I’m building
I’ve been working on cluster consoles, AI investigate flows, and terminals — how people collaborate with clusters. When agents move from Q&A to acting, platforms ask: where does it run, is isolation enough, how is session state kept and reclaimed? Agent Sandbox answers the infrastructure slice of those three
Takeaway
Agent Sandbox: CRD/controller orchestration for isolated, stateful, singleton sandbox workloads — great for running untrusted agent code. It orchestrates sandboxes; it doesn’t replace gVisor/Kata or write your agent logic