Kubernetes Agent Sandbox Explained

What it claims

Agent Sandbox, a Kubernetes SIG Apps project, exposes its resources under the API group agents.x-k8s.io/v1beta1. A single Sandbox resource can be applied directly. Alternatively, a platform admin can publish templates and pre-warmed pools that applications claim, a split the author, Bibin Wilson, compares to PersistentVolumes and PersistentVolumeClaims. Isolation comes from the cluster's sandboxed runtime (gVisor or Kata Containers), not from the controller itself.

How it works

The spec.operatingMode field controls the lifecycle. Setting it from Running to Suspended deletes the Pod but keeps its persistent storage. Switching it back to Running recreates the Pod and reattaches that storage. Scheduled deletion uses a shutdownTime combined with a Delete policy.

In the reusable workflow, a SandboxTemplate holds the image and pod configuration. A SandboxWarmPool references the template and keeps replicas ready Pods running. An application creates a SandboxClaim against the pool, and the controller assigns an existing sandbox, then creates a replacement. Requests reach the assigned Pod through the Sandbox Router, a lightweight proxy.

flowchart LR
  subgraph Admin
    T[SandboxTemplate] --> W[SandboxWarmPool]
  end
  subgraph App
    C[SandboxClaim]
    A[Agent app]
  end
  W --> P[Ready sandbox Pod]
  C --> P
  P -. replacement .-> W
  A --> R[Sandbox Router] --> P

How to use it

After installing the CRD and controller, a standalone sandbox is created with this resource, reproduced from the page:

apiVersion: agents.x-k8s.io/v1beta1
kind: Sandbox
metadata:
  name: python-sandbox
spec:
  operatingMode: Running
  podTemplate:
    spec:
      restartPolicy: Never
      containers:
        - name: workspace
          image: python:3.12-slim
          command: ["sleep", "infinity"]
          workingDir: /workspace
          volumeMounts:
            - name: workspace
              mountPath: /workspace
      volumes:
        - name: workspace
          emptyDir: {}

A linked guide covers installing the controller and router, running a Kubernetes troubleshooting agent inside a sandbox, executing code through the Agent Sandbox SDK, and testing deletion and hibernation. The newsletter gives no install commands or SDK calls itself.

Limits

A gVisor or Kata Containers runtime must already be configured in the cluster. Without one, the sandbox has no stronger isolation than an ordinary Pod.

A standalone Sandbox means waiting for Pod startup each time and defining every configuration individually. Warm pools remove the wait, but idle pool Pods still consume resources.

Suspension saves compute only if the freed capacity lets the cluster scale nodes down. Persistent storage may still incur cost while a sandbox is suspended. The example uses emptyDir, which is not persistent storage.