Kubernetes Agent Sandbox CRD: Isolated Stateful AI Agents

The first thing I did with this project was stop reading the announcement and open the manifests, because the Kubernetes blog post and the repository README disagree on a detail that decides whether your install command works. The blog says to apply manifest.yaml from a release; the README today says sandbox-with-extensions.yaml, and the v1.0.7 release page lists exactly three assets: extensions.yaml, sandbox-with-extensions.yaml and sandbox.yaml.

This post is a close reading, not a benchmark I ran. I did not stand up a cluster for it. Everything below comes from the Kubernetes blog announcement of 20 March 2026, the kubernetes-sigs/agent-sandbox repository (README, threat model, performance tuning guide, configuration guide, roadmap and example manifests) and the PyPI page, each fetched on 17 October 2026. Where a number appears, it is the project's own, with the cluster it was measured on.

Why a StatefulSet of one does not cut it

The announcement describes an AI agent as an isolated, stateful, singleton workload: a digital workspace for an LLM that needs a persistent identity and a secure scratchpad for writing and executing, often untrusted, code. Because agents are expected to be mostly idle except for brief bursts, they also need suspension and rapid resumption. The authors, Janet Kuo and Justin Santa Barbara, concede that you could approximate this with a StatefulSet of size 1, a headless Service and a PersistentVolumeClaim per agent, and then call managing that at scale an operational nightmare.

That framing is the reason the project exists, and it is also the test I apply to it. If you run five agents, the StatefulSet recipe is fine and a new CRD is overhead. The CRD earns its place when you are creating and deleting thousands of these per day, need one place to enforce a RuntimeClass, and want a pool of ready ones. The announcement itself says the project is currently in development under SIG Apps.

The four resources and the one install command that matters

The README defines one core resource and three opt-in extensions. The Sandbox kind lives in agents.x-k8s.io/v1beta1 and manages a single stateful pod with a stable hostname, network identity and persistent storage. The extensions live under extensions.agents.x-k8s.io, and the example manifests in the repository use v1beta1 for them as well. The roadmap marks the alpha-to-beta move as done: v1beta1 is the only served version and the v1alpha1 types and conversion webhooks are removed.

Install is two kubectl apply calls, or one if you take the combined manifest. The block below is the README's own sequence, followed by the verification it prescribes. The README recommends pinning a version for production and GitOps; v1.0.7, published on 15 October 2026, was the latest release when I looked.

# From the README. Pin a version for production and GitOps.
export VERSION="v1.0.7"

# Core + extensions in one manifest (SandboxTemplate, SandboxClaim, SandboxWarmPool):
kubectl apply -f https://github.com/kubernetes-sigs/agent-sandbox/releases/download/$VERSION/sandbox-with-extensions.yaml

# Or split it. Core only, then the opt-in extensions:
kubectl apply -f https://github.com/kubernetes-sigs/agent-sandbox/releases/download/$VERSION/sandbox.yaml
kubectl apply -f https://github.com/kubernetes-sigs/agent-sandbox/releases/download/$VERSION/extensions.yaml

# Verify, exactly as the README prescribes:
kubectl get crd sandboxes.agents.x-k8s.io
kubectl get deploy agent-sandbox-controller -n agent-sandbox-system

# The announcement blog (March 2026) still shows the older shape:
#   .../releases/download/vX.Y.Z/manifest.yaml
# v1.0.7 lists sandbox.yaml, extensions.yaml and sandbox-with-extensions.yaml.

# Client SDK (optional):
pip install k8s-agent-sandbox

Isolation is delegated, and the template is where you enforce it

The most important sentence in the threat model is also the easiest to skim past: Agent Sandbox itself does not implement isolation but supports configuring secure runtimes. The announcement says the Sandbox resource natively supports runtimes like gVisor or Kata Containers for kernel and network isolation. In practice that is the ordinary Kubernetes mechanism, a RuntimeClass named in the pod template. The project's gVisor quickstart creates one with handler runsc and tells you to uncomment runtimeClassName: gvisor in the template.

The threat model then says where to enforce it. Platform administrators can define the secure runtimeClassName in a SandboxTemplate used by a SandboxWarmPool, so the tenant who claims a sandbox never chooses the runtime. That is the design decision worth copying: put the isolation choice in the object the platform team owns, not in the object the agent platform creates per session.

Below is a template assembled from two files in the repository: the Python client's template for the runtimeClassName line and resource requests, and the aider example for the network policy and workspace volume. It is my composition of their fields, not a file from the repo, so treat it as a starting point and apply it to a test cluster first.

# 1. RuntimeClass, as in the project's gVisor quickstart (handler = runsc)
apiVersion: node.k8s.io/v1
kind: RuntimeClass
metadata:
  name: gvisor
handler: runsc
---
# 2. Template: the platform team owns this, the claiming tenant never sees it.
#    Fields composed from the Python client template and the aider example.
apiVersion: extensions.agents.x-k8s.io/v1beta1
kind: SandboxTemplate
metadata:
  name: agent-gvisor
  namespace: default
spec:
  networkPolicyManagement: Managed      # the documented default
  networkPolicy:
    ingress:
    - ports: [{protocol: TCP, port: 8888}]
    egress:
    - ports: [{protocol: UDP, port: 53}, {protocol: TCP, port: 53}]
    - ports: [{protocol: TCP, port: 443}]
  volumeClaimTemplates:
  - metadata:
      name: workspace
    spec:
      accessModes: ["ReadWriteOnce"]
      resources:
        requests:
          storage: 1Gi
  podTemplate:
    spec:
      runtimeClassName: gvisor          # isolation chosen here, not by the claim
      automountServiceAccountToken: false   # templates default to this when omitted
      restartPolicy: OnFailure
      containers:
      - name: runtime
        image: registry.example.com/agent-runtime:1.0   # replace with your image
        ports:
        - containerPort: 8888
        resources:
          requests: {cpu: 250m, memory: 512Mi, ephemeral-storage: 512Mi}
          limits:   {cpu: "1",  memory: 1Gi,  ephemeral-storage: 1Gi}

Warm pools: what the one-second claim really buys

The announcement's argument is short. Starting a pod adds about a second of overhead, fine for deploying a microservice and not fine when an idle agent is invoked and the model must wait before it can think or act. SandboxWarmPool maintains pre-provisioned sandbox pods, and a SandboxClaim hands one over. The example claim in the repository sets a single spec field: a warmPoolRef with a name.

# Warm pool: keeps 3 sandboxes ready from the template above.
apiVersion: extensions.agents.x-k8s.io/v1beta1
kind: SandboxWarmPool
metadata:
  name: agent-gvisor-pool
  namespace: default
spec:
  replicas: 3                  # replicas: 0 means every claim cold-starts
  sandboxTemplateRef:
    name: agent-gvisor         # must match the SandboxTemplate metadata.name
---
# Claim: what your agent platform creates per session.
apiVersion: extensions.agents.x-k8s.io/v1beta1
kind: SandboxClaim
metadata:
  name: session-4821
  namespace: default
spec:
  warmPoolRef:
    name: agent-gvisor-pool
  # Wrong: setting spec.env or spec.volumeClaimTemplates here disables warm
  # adoption and forces a cold start from the template.

The performance tuning guide is where the project puts its measurements, and it is more candid than the announcement. It separates two regimes and says so explicitly. Draining an already-ready pool is cheap; keeping a pool full while claims keep arriving is not. The table collects the figures I read, with the environment each came from.

Two caveats from the same guide change how you use it. First, a claim that sets spec.env or spec.volumeClaimTemplates disables warm adoption entirely and always cold-starts a fresh sandbox from the template, because those customisations cannot be applied to a running warm pod. Second, a pool whose spec.replicas is 0 simply cold-starts from its template. A warm pool you size well but claim with a custom env is a pool you pay for and never use.

Stateful lifecycle: what is shipped and what is only promised

The announcement says Agent Sandbox supports scaling idle environments to zero while ensuring they resume exactly where they left off. The roadmap is more precise, and the difference matters if you are planning around it. PVC-based suspend and resume is listed as completed: when scaled to 0, the PVC is persisted and attached again on resume. Automatic suspension of inactive sandboxes, and a separate Scale to Zero item, are listed as planned.

The stable identity part is shipped and simple: every Sandbox gets a stable hostname and network identity so coordinated agents can find each other. The controller backs each Sandbox with a headless Service whose selector is a name-hash label, which is a detail that matters in the next section.

Where it bites: security defaults and tuning traps

The threat model is unusually frank about what is and is not covered, and the performance guide records a failed configuration rather than hiding it. I read both for the places a platform team would get hurt. The table lists five, each with the evidence in the project's own words.

The label spoofing issue deserves its own paragraph because it is the sort of bug a CRD like this invites. A tenant controls spec.podTemplate metadata, and the Service for Sandbox A selects pods by the agents.x-k8s.io/sandbox-name-hash label. If a malicious tenant copied that label value onto its own pod, traffic meant for Sandbox A could reach the attacker. The threat model documents the fix: the controller filters keys under agents.x-k8s.io and extensions.agents.x-k8s.io out of user templates and assigns the name-hash after merging user labels. It also lists strengthening the FNV-1a hash as tracked separately.

One more drift to keep in mind: the roadmap lists API-versus-runtime decoupling, rolling updates for templates and warm pools, and smarter warm pool selection as in progress. A KEP in the repository proposes reducing SandboxClaim to a single warmPoolRef field. I treat that as a proposal, not a shipped API, but it tells you to keep claim manifests small and generated from one place.

Tuning the controller before the pool becomes the bottleneck

The configuration guide has a high-throughput Deployment example, and the performance guide explains each flag. The summary I took away: defaults are safe for small deployments, and most flags only matter once you hit the API server concurrency ceiling. At 75 concurrent claims several of them were neutral. The one with a consistent effect was max refill rate, which cut p50 and p90 by about 15 percent versus the baseline in the GKE test, and rate 80 and rate 100 performed identically.

The snippet shows only flags I read in the two guides, with their documented reasons. Do not copy the numbers as a recommendation for your cluster: the guide ties them to its own profiles, and one of its worker sweeps showed that too few workers regress (50, 50, 1, 1 workers cost about 11 percent on p50 against 200, 150, 2, 1).

# Fragment of the agent-sandbox-controller container args.
# Every flag below is named in docs/configuration.md or docs/performance-tuning.md.
# The values are the guides' examples for their own profiles: measure before copying.
args:
- --leader-elect=true
- --extensions=true
# Keep write traffic from starving the watch events that clear a pool's expectations gate.
- --separate-watch-connection=true
- --api-connections=4
# Pace refill as a steady stream instead of 300-sandbox bursts (default rate is 0 = unpaced).
- --sandbox-warm-pool-max-refill-rate=100
- --sandbox-warm-pool-max-batch-size=200
# Parallelism is across distinct SandboxWarmPool objects, not within one pool.
- --sandbox-warm-pool-concurrent-workers=4
# Fewer redundant writes per lifecycle transition.
- --disable-sandbox-events=true
- --disable-claim-events=true
- --disable-claim-observability-annotations=true

# Wrong: --sandbox-warm-pool-replenish-delay=20s. In the GKE test one failed
# claim creation drained the pool and p90 went from 74.2 s to 204.7 s.

What to do on Monday

I would not put this in front of production traffic yet, and the announcement says as much by calling the project in development. But it is good enough to evaluate on a scratch cluster this week. In order:

1. Install on a disposable cluster with the pinned release, and verify the CRD and the controller deployment with the two commands from the README.
2. Get isolation working first: create the gVisor or Kata RuntimeClass, put runtimeClassName in a SandboxTemplate, and confirm the pod actually runs under it before anything else.
3. Measure your own claim latency with a SandboxWarmPool of a few replicas against a replicas 0 pool built on the same template, so the warm-versus-cold difference is a number from your nodes.
4. Test the failure modes: a tenant pod that tries to reach 169.254.169.254, a pod that tries to read a service account token, and a claim that sets spec.env.
5. Write down which lifecycle pieces you must own yourself (idle detection, cleanup of abandoned sandboxes) because the roadmap lists them as planned.

# Does the claimed pod really run under the sandbox runtime?
kubectl get pod -n default -o custom-columns=NAME:.metadata.name,RUNTIME:.spec.runtimeClassName

# Warm versus cold on your own nodes: time a claim against each pool.
time kubectl apply -f claim-warm.yaml
kubectl get sandboxclaim session-4821 -o yaml   # read status.conditions for when it was bound

# Failure probes from inside a sandbox: metadata endpoint and API token.
kubectl exec <sandbox-pod> -- curl -m 3 -s http://169.254.169.254/ ; echo "exit=$?"
kubectl exec <sandbox-pod> -- ls /var/run/secrets/kubernetes.io/serviceaccount

The Python SDK is on PyPI as k8s-agent-sandbox, and the Go SDK ships from the repository's root module. Both are the client side. The roadmap lists expanding the Python SDK to read and write files and run commands as in progress, so expect that surface to move.

The rule I take from this: an agent sandbox is only as isolated as the RuntimeClass in the template, and only as fast as the warm pool you size and the claims that are allowed to use it. Agent Sandbox gives you the objects to enforce both in one place, and its own documentation is honest that several pieces, from auto-suspend to claim-time network policy, are still ahead of it.