Agent Sandbox (kubernetes-sigs) — Summary

Agent Sandbox is a Kubernetes SIG Apps project that defines a Sandbox Custom Resource Definition (CRD) and controller, providing a declarative API for managing isolated, stateful, singleton workloads ideal for AI agent runtimes. It fills a gap in Kubernetes primitives: Deployments are stateless/replicated, StatefulSets are numbered, but development environments / agent runtimes need a different abstraction — a stable-identity, single-container, persistent, resumable environment. Extensions add SandboxTemplate, SandboxClaim, and SandboxWarmPool for reusable templates, user-facing claims, and pre-warming. A Python SDK provides programmatic access. Agent Sandbox is the only Kubernetes-native sandbox in this batch — it targets organizations already running Kubernetes who want standardized agent execution primitives. Like all sandbox infrastructure projects, it operates below the agent loop (providing the execution environment, not agent behavior), making it fundamentally different from all 11 seed frameworks.

Agent Sandbox (kubernetes-sigs) — Overview

Origin

kubernetes-sigs/agent-sandbox is under the Kubernetes Special Interest Group (SIG) Apps umbrella. It is a community-driven, vendor-neutral Kubernetes project. As of May 2026: 2,453 stars, 77 contributors (largest contributor base in this batch), licensed Apache-2.0. Active development with CI, roadmap, and community channels.

Philosophy

From the README: "agent-sandbox enables easy management of isolated, stateful, singleton workloads, ideal for use cases like AI agent runtimes."

Core thesis: Kubernetes lacks a first-class primitive for "development environments" and "AI agent runtimes" — workloads that are:

• Single-instance (not replicated)
• Stateful with persistent storage
• Need stable network identity
• Benefit from hibernation (sleep/wake without losing state)
• Need lifecycle management beyond what Deployments or StatefulSets provide

Design Approach

Rather than inventing a new virtualization technology, Agent Sandbox uses Kubernetes primitives (Pod, PersistentVolumeClaim, Service) orchestrated by a controller. It is intentionally runtime-agnostic — supports gVisor, Kata Containers, or any Kubernetes-supported runtime, with the security guarantees depending on the chosen runtime.

Motivation Examples (from README)

• Development environments: isolated, persistent, network-accessible cloud environments for developers
• AI Agent Runtimes: isolated environments for executing untrusted, LLM-generated code
• Notebooks and Research Tools: persistent, single-container sessions (Jupyter Notebooks)
• Stateful Single-Pod Services: hosting single-instance apps needing stable identity without StatefulSet overhead

Community

• Kubernetes Slack: #agent-sandbox
• SIG Apps Mailing List
• GitHub Issues + PRs with stale PR management (30-day auto-stale, 15-day auto-close)
• AI-assisted code review via GitHub Copilot (experimental)

Agent Sandbox (kubernetes-sigs) — Architecture

Distribution

• Type: Kubernetes operator (CRD + controller)
• Install: kubectl apply -f https://github.com/kubernetes-sigs/agent-sandbox/releases/download/${VERSION}/manifest.yaml
• Extensions: kubectl apply -f https://github.com/kubernetes-sigs/agent-sandbox/releases/download/${VERSION}/extensions.yaml
• Python SDK: pip install agentic-sandbox-client (from clients/python/agentic-sandbox-client/)

Repo Structure

kubernetes-sigs/agent-sandbox/
├── api/                 — CRD type definitions (Go)
├── controllers/         — Kubernetes controller logic (Go)
├── cmd/                 — Controller binary entry point
├── clients/
│   ├── python/          — Python SDK (agentic-sandbox-client)
│   ├── go/              — Go client library
│   └── k8s/             — Kubernetes client helpers
├── extensions/          — SandboxTemplate, SandboxClaim, SandboxWarmPool
│   └── examples/        — Extension usage examples
├── examples/            — Basic Sandbox YAML examples
├── helm/                — Helm chart for installation
├── k8s/                 — Raw Kubernetes manifests
├── docs/                — Documentation (Netlify-deployed)
├── site/                — Documentation site (static)
├── test/                — Integration tests
├── AGENTS.md            — Agent contributor guide
└── Makefile             — Build targets

Core CRD: Sandbox

apiVersion: agents.x-k8s.io/v1alpha1
kind: Sandbox
metadata:
  name: my-sandbox
spec:
  podTemplate:
    spec:
      containers:
      - name: my-container
        image: <IMAGE>

Creates a stable-identity pod with persistent storage. Controller manages the pod lifecycle (creation, restart, scheduled deletion, pause/resume).

Extension CRDs

Architecture Diagram (Mermaid from README)

User → creates → Sandbox → creates Pod → Runtime
User → creates → SandboxClaim → references Template → adopts Sandbox
SandboxWarmPool → pre-warms → Sandbox

Required Runtime

• Kubernetes cluster (any version supporting CRDs)
• Optional: gVisor or Kata Containers for enhanced isolation
• Python ≥ 3.x (for Python SDK)

Agent Sandbox (kubernetes-sigs) — Components

Core CRD Operations

The Sandbox CRD supports these lifecycle operations via kubectl or SDK:

• Create a Sandbox (apply YAML or SDK call)
• Get sandbox details and stable hostname
• Pause / resume (hibernate / wake)
• Scheduled deletion
• Persistent storage attach/detach

Python SDK (agentic-sandbox-client)

High-level interface for creating and managing sandboxes programmatically. From clients/python/agentic-sandbox-client/:

from agentic_sandbox_client import SandboxClient

client = SandboxClient()
sandbox = client.create_sandbox(name="my-sandbox", image="python:3.11")
result = sandbox.execute("python -c 'print(\"Hello\")'")
sandbox.delete()

Go Client Library

clients/go/ — Go bindings for the Sandbox API.

Extension CRDs

Controller

The Kubernetes controller (in controllers/) watches Sandbox custom resources and reconciles them with Pods, PersistentVolumeClaims, and Services. Implements:

• Stable hostname assignment
• Storage lifecycle management
• Pod restart / crash recovery
• Scheduled deletion
• Pause (scale-to-zero) and resume

Helm Chart

helm/ directory provides a Helm chart for easy operator installation on clusters.

AGENTS.md

Contains contributor guidance for AI coding agents working on the agent-sandbox codebase itself. Standard Kubernetes project structure guidance.

Makefile Targets

Standard Kubernetes project Makefile:

• make generate — generate CRD types and deepcopy
• make manifests — generate CRD manifests
• make build — build controller binary
• make test — run unit tests
• make deploy — deploy to cluster

Agent Sandbox (kubernetes-sigs) — Uniqueness & Positioning

differs_from_seeds

Agent Sandbox is architecturally orthogonal to all 11 seed frameworks. Seeds operate within the agent loop (skills, hooks, personas, MCP tools, spec files). Agent Sandbox operates as the Kubernetes infrastructure layer for agent runtimes — it provides a declarative CRD abstraction over Kubernetes Pods+PVCs for stable-identity, stateful, singleton workloads. No seed framework targets the Kubernetes control plane or provides CRD-based agent isolation. The isolation_mechanism differs sharply: seeds use none/git-worktree; Agent Sandbox uses Kubernetes container primitives (with optional gVisor/Kata for stronger isolation). It is also the only project in this batch that is a CNCF-ecosystem (Kubernetes SIG) project, making it vendor-neutral and governance-structured rather than company-backed.

Positioning Within This Batch

Agent Sandbox is uniquely Kubernetes-native:

• vs E2B/Daytona: Cloud API products; Agent Sandbox is self-hosted Kubernetes infrastructure
• vs Brood Box/Microsandbox: Local microVM CLIs/SDKs; Agent Sandbox requires a Kubernetes cluster
• vs Arrakis: Self-hosted REST API; Agent Sandbox is a Kubernetes operator with CRD-driven declarative lifecycle

The target user is a platform/infrastructure engineer or organization that already operates Kubernetes and wants to add standardized AI agent execution capabilities to their cluster.

Distinctive Opinion

AI agent runtimes need a dedicated Kubernetes primitive — neither Deployments (stateless/replicated) nor StatefulSets (numbered) are the right abstraction. The "singleton stateful pod with stable identity and hibernation" pattern deserves a first-class Kubernetes CRD.

Explicit Antipatterns

• Using StatefulSets (size 1) + Services + PVCs as a cumbersome workaround for agent runtimes
• Running AI-generated code in Pods without proper isolation runtime (gVisor/Kata recommended for untrusted code)

Observable Failure Modes

1. Kubernetes dependency: Requires a running cluster — not usable in local-only or simple scenarios
2. Alpha/v1alpha1 API: agents.x-k8s.io/v1alpha1 — API is not stable; breaking changes expected
3. No built-in isolation: Default container runtime (containerd/Docker) shares the host kernel; gVisor/Kata must be configured separately
4. Warm pool cost: Pre-warmed sandboxes consume cluster resources (CPU/memory) continuously
5. PR velocity: Auto-stale (30-day) + auto-close (15-day) may be aggressive for community contributors

Cross-References

• Explicitly supports gVisor and Kata Containers as enhanced isolation runtimes
• Part of the Kubernetes SIG Apps ecosystem
• Community governance via Kubernetes Code of Conduct and CLA