Kubernetes Agent Sandbox Controller: Architecture Explained

AI agents that run generated code need a place to execute it without sharing a long-lived process, filesystem, or set of credentials with every other task. The Kubernetes Agent Sandbox project adds a declarative controller for isolated, stateful, single-Pod workspaces. This explainer is for platform engineers and developers deciding how to provision agent environments, preserve their files, and keep execution isolation separate from the application that schedules the work.

Why Kubernetes Agent Sandboxes Are Being Discussed

Tool-using agents can compile code, run tests, inspect repositories, and invoke command-line programs. These operations need compute and a filesystem, but a reusable service container is a poor fit when each task should have its own identity, lifecycle, and boundaries. Creating a Deployment and a collection of storage and networking objects for every task can work, but leaves the application responsible for coordinating those pieces.

The Kubernetes SIG Agent Sandbox project packages that coordination as Kubernetes APIs. Its controller can create individual workspaces, while optional template and warm-pool APIs support repeated provisioning. The result is an orchestration layer for agent execution, not a new container runtime or a guarantee that arbitrary code is safe.

What Is the Kubernetes Agent Sandbox Controller?

The Agent Sandbox controller watches a custom resource named Sandbox and reconciles the requested state into Kubernetes resources, chiefly a Pod and, when configured, storage and networking resources. Instead of directly creating and tracking a Pod for every agent task, a caller submits a higher-level object describing the workspace. Kubernetes stores that object in the API server; the controller observes it and works toward the requested state.

The Kubernetes documentation on custom resources explains the general extension model: a CRD adds a resource type to the API, and a controller supplies behavior for that type. Agent Sandbox follows this pattern with its own API group and controller. An object in the API records intent; the controller’s status and the Pod’s state show what has actually happened.

The project’s core Sandbox API represents one stateful workload with a stable identity. A SandboxTemplate packages reusable Pod and storage configuration, and the opt-in extensions add SandboxWarmPool and SandboxClaim for pre-created workspaces. These types are useful when an agent platform needs to request isolated execution repeatedly without embedding Kubernetes object assembly into each user-facing service.

The Problem It Solves

Kubernetes already has workload controllers, but their common abstractions do not map exactly to a per-task workspace. A Deployment treats replicas as interchangeable and is designed to keep a replicated application available. A StatefulSet gives a group of Pods stable ordinals and ordered lifecycle behavior. A development shell or agent session often needs one independently named Pod, its own scratch or persistent files, and a way to pause or expire that one environment.

Without a higher-level API, a platform may need to create a Pod, PVC, Service, labels, and cleanup timers as a coupled workflow. Partial failure can leave orphaned resources, and each application can implement subtly different retry and deletion behavior. The Sandbox controller centralizes reconciliation for the supported resource lifecycle. It does not replace Kubernetes scheduling, storage drivers, network policy enforcement, or the application’s own authorization and cleanup policies.

How the Controller Architecture Works

The control loop begins when a client creates or updates a Sandbox resource. The API server validates it against the installed CRD schema and persists the desired specification. The controller watches for changes, compares desired state with current resources, and creates or updates the backing Pod and any configured companion resources. It then reports progress through status and conditions. If the Pod is still scheduling or starting, the Sandbox is not yet ready; a successful API write alone is not proof that the workspace can accept work.

The controller manages Kubernetes objects, while the kube-scheduler places the Pod and the node’s container runtime starts its containers. PersistentVolumeClaims are provisioned through the cluster’s storage configuration. Network traffic is governed by the cluster networking implementation and any configured policy. This separation matters operationally: a Sandbox can be accepted by the API and still remain Pending because there is no matching node, a volume cannot be provisioned, or an image cannot be pulled.

The design has several layers:

1. Sandbox API: Expresses the desired single-workload configuration and lifecycle.
2. Sandbox controller: Reconciles that API object with backing Kubernetes resources and updates observed status.
3. Kubernetes control plane: Performs scheduling, Pod lifecycle, volume binding, and networking through its existing components.
4. Container runtime: Starts the workload using the runtime configured for the selected node.
5. Optional extensions: Provide templates for repeated configuration and warm pools that claims can draw from.

These models can use similar Kubernetes primitives underneath, but their APIs communicate different operational intent. A Sandbox is not a miniature virtual machine: its isolation depends on its Pod configuration, cluster policy, and runtime.

Key APIs and Lifecycle Concepts

• Sandbox: The core resource for a single workload. It includes a Pod template and can define persistent volume claim templates. The backing Pod receives the Sandbox’s identity; a headless Service can be enabled when stable in-cluster DNS is required.
• SandboxTemplate: An extension resource for reusable workload configuration. It can include Pod settings, volume claims, and policy choices used by generated Sandboxes.
• SandboxWarmPool: Maintains a requested number of prepared Sandboxes from a template. Keeping ready workspaces available can reduce provisioning delay, but it consumes cluster resources before a claim arrives.
• SandboxClaim: Requests a workspace from a warm pool. The claim controller associates the request with a Sandbox, and ownership moves to the claim; pool capacity must then be replenished.
• Operating mode and expiration: A Sandbox can be requested in Running or Suspended mode. Suspension stops the backing Pod while retaining the Sandbox and its volumes for a later resume. A configured shutdown time expires the workload; the shutdown policy determines whether the Sandbox object itself is retained or deleted after its Pod and Service are removed.
• Persistent storage: A volume claim template requests a PVC for the workspace. Whether data survives depends on the volume, storage class, access mode, retention, and deletion policy. Persistence is not the same as backup or replication.

Warm pools trade resource cost for lower wait time. They are most useful when the expected request rate and startup delay justify keeping Pods ready. A claim that needs per-request configuration or storage that is not present in a warm Pod may require a cold start instead, so benchmark the real workload rather than assuming every request can use a pre-warmed instance.

Real-World Use Cases

An agent platform can assign a workspace to a coding task, mount a repository volume, run tests, and retain files while a user reviews the result. A hosted development environment can provide a persistent single-user session without modeling each user as a replica in a shared Deployment. Reinforcement-learning or evaluation systems can use claims to allocate execution environments repeatedly, with a warm pool for latency-sensitive bursts.

For applications that need durable conversational or task progress, the Kubernetes workspace complements rather than replaces an application checkpoint store. See agent memory and state management for the distinction between saved workflow state and a running execution environment.

Getting Started with Agent Sandbox

The following workflow assumes a functioning Kubernetes cluster, permission to install cluster-scoped CRDs and a controller, and a default StorageClass that can provision a 5 GiB volume. The release bundle includes the core controller and optional extensions. Pin the version rather than relying on a moving latest URL:

kubectl apply -f https://github.com/kubernetes-sigs/agent-sandbox/releases/download/v1.0.7/sandbox-with-extensions.yaml

# Confirm the API and controller are installed
kubectl get crd sandboxes.agents.x-k8s.io
kubectl get deployment agent-sandbox-controller -n agent-sandbox-system
kubectl get storageclass

Save this resource as workspace.yaml. It runs a simple idle container and mounts a controller-created claim at /workspace. Replace the image and command with a workload image you have reviewed and published to a registry reachable by the cluster:

apiVersion: agents.x-k8s.io/v1beta1
kind: Sandbox
metadata:
  name: agent-workspace
spec:
  service: true
  volumeClaimTemplates:
    - metadata:
        name: workspace-volume
      spec:
        accessModes:
          - ReadWriteOnce
        resources:
          requests:
            storage: 5Gi
  podTemplate:
    spec:
      automountServiceAccountToken: false
      containers:
        - name: workspace
          image: python:3.12-slim
          command: ["sh", "-c", "sleep infinity"]
          volumeMounts:
            - name: workspace-volume
              mountPath: /workspace

Apply the object and check the controller’s observed state rather than treating a successful apply as readiness:

kubectl apply -f workspace.yaml
kubectl get sandbox agent-workspace
kubectl describe sandbox agent-workspace
kubectl get pod agent-workspace
kubectl get pvc

The example deliberately disables automatic ServiceAccount token mounting because a build or code-execution workspace usually does not need the Kubernetes API credential. service: true requests a headless Service for stable in-cluster discovery; it does not expose the workspace publicly. Network access and egress still need to be configured according to the threat model. If the Pod remains Pending, inspect its events, PVC status, node capacity, and image-pull errors. A cluster without a usable StorageClass cannot satisfy the volume request.

For a warm-pool workflow, create a SandboxTemplate, configure a SandboxWarmPool to reference it, then create a SandboxClaim with that pool’s name. The project getting-started guide and examples show extension-specific manifests and client flows. When using those extensions, check both claim status and the backing Sandbox before dispatching work.

Common Misconceptions

“A Sandbox is itself a security boundary.” The CRD is an orchestration API. Isolation comes from the Pod’s security settings, node configuration, network policies, and runtime. Kubernetes authorization must also limit who can create or modify Sandbox resources.

“Persistent means safe.” A PVC can keep files when a Pod is replaced or suspended, but it does not provide a backup, protect against deletion, or ensure that a volume can attach to every node. Define retention and recovery separately.

“A warm pool is free capacity.” Warm Pods use CPU, memory, storage, and possibly IP addresses before a task claims them. Pool size, refill behavior, cold-start requirements, and cleanup all affect cost and capacity.

The controller can select a runtime through Kubernetes RuntimeClass, but it does not implement that runtime. The Open Container Initiative Runtime Specification describes a low-level container runtime configuration format; Kubernetes’ RuntimeClass documentation explains how a cluster selects configured runtimes for Pods. For an example of a separate runtime-level isolation design, see gVisor’s sandboxed container architecture.

Related Articles

• Agent memory and state management explains how task checkpoints differ from a live workspace.
• gVisor sandboxed container runtime covers an optional runtime isolation layer below the Sandbox controller.
• Kubernetes StatefulSets and persistent workloads compares stable single workspaces with ordered groups of stateful Pods.
• Kubernetes Pod Security Admission explains how cluster policy can constrain Pod security settings.

Changelog and Last Updated

• Initial publication.