# Agent Sandbox Developer Reference Wiki

> A developer reference for kubernetes-sigs/agent-sandbox: a Kubernetes controller and SDK ecosystem that delivers a Sandbox CRD plus extensions (SandboxClaim, SandboxTemplate, SandboxWarmPool) for managing isolated, stateful, singleton workloads such as AI agent runtimes.

This is a Grok-Wiki source-grounded repository wiki. Use the complete Markdown link when an agent needs the full repo context.

## Context Links

- [Complete Markdown wiki](https://grok-wiki.com/public/wiki/kubernetes-sigs-agent-sandbox-c3f2597a654a/llms-full.txt)
- [Complete Markdown alias](https://grok-wiki.com/public/wiki/kubernetes-sigs-agent-sandbox-c3f2597a654a.md)
- [Human interactive wiki](https://grok-wiki.com/public/wiki/kubernetes-sigs-agent-sandbox-c3f2597a654a)
- [GitHub repository](https://github.com/kubernetes-sigs/agent-sandbox)

## Repository

- Repository: kubernetes-sigs/agent-sandbox

- Generated: 2026-05-25T23:21:59.478Z
- Updated: 2026-05-25T23:22:25.082Z
- Runtime: Claude Code
- Format: Technical
- Pages: 30

## Pages

- [Technical Orientation](https://grok-wiki.com/public/wiki/kubernetes-sigs-agent-sandbox-c3f2597a654a/pages/01-technical-orientation.md): Purpose of agent-sandbox, its core/extensions split, controller-manager entry point, and a map for navigating the rest of this developer reference.
- [Installation & Deployment Modes](https://grok-wiki.com/public/wiki/kubernetes-sigs-agent-sandbox-c3f2597a654a/pages/02-installation-deployment-modes.md): Installing the controller via released YAML, Helm chart, or kind clusters; choosing between core-only and core+extensions deployments.
- [Quickstart Paths (gVisor, Kata, Vanilla)](https://grok-wiki.com/public/wiki/kubernetes-sigs-agent-sandbox-c3f2597a654a/pages/03-quickstart-paths-gvisor-kata-vanilla.md): Walkthrough of the quickstart manifests for vanilla, gVisor, and Kata runtimes, plus how the examples directory organizes runnable scenarios.
- [Controller Configuration & Tuning Flags](https://grok-wiki.com/public/wiki/kubernetes-sigs-agent-sandbox-c3f2597a654a/pages/04-controller-configuration-tuning-flags.md): All command-line flags exposed by the controller binary: QPS/burst, worker concurrency, warm-pool batch size, leader election, pprof, tracing, and cluster domain.
- [Sandbox CRD (agents.x-k8s.io/v1beta1)](https://grok-wiki.com/public/wiki/kubernetes-sigs-agent-sandbox-c3f2597a654a/pages/05-sandbox-crd-agents.x-k8s.io-v1beta1.md): Field-by-field reference for the core Sandbox resource: PodTemplate, VolumeClaimTemplates, Lifecycle, Replicas (0/1), and Service toggle.
- [SandboxTemplate CRD](https://grok-wiki.com/public/wiki/kubernetes-sigs-agent-sandbox-c3f2597a654a/pages/06-sandboxtemplate-crd.md): Reusable template type used by SandboxClaim and SandboxWarmPool, including the embedded Sandbox spec it encapsulates.
- [SandboxClaim CRD](https://grok-wiki.com/public/wiki/kubernetes-sigs-agent-sandbox-c3f2597a654a/pages/07-sandboxclaim-crd.md): Claim resource that resolves to a Sandbox: template references, warm-pool policy, env injection, additional pod metadata, and shutdown policies (Delete, DeleteForeground, Retain).
- [SandboxWarmPool CRD](https://grok-wiki.com/public/wiki/kubernetes-sigs-agent-sandbox-c3f2597a654a/pages/08-sandboxwarmpool-crd.md): Specification of pre-warmed sandbox pools: template binding, replica counts, and adoption semantics consumed by SandboxClaim.
- [Conditions, Reasons & Status Surfaces](https://grok-wiki.com/public/wiki/kubernetes-sigs-agent-sandbox-c3f2597a654a/pages/09-conditions-reasons-status-surfaces.md): Catalogue of condition types (Ready, Suspended, Finished), reason strings, and the annotation/label keys (pod-name, template-ref, propagated-labels) that controllers use to coordinate state.
- [Controller Manager Entry Point](https://grok-wiki.com/public/wiki/kubernetes-sigs-agent-sandbox-c3f2597a654a/pages/10-controller-manager-entry-point.md): How cmd/agent-sandbox-controller/main.go wires schemes, the controller-runtime Manager, metrics/pprof servers, leader election, and the optional extensions reconciler set.
- [Sandbox Reconciler](https://grok-wiki.com/public/wiki/kubernetes-sigs-agent-sandbox-c3f2597a654a/pages/11-sandbox-reconciler.md): Reconciliation loop for the core Sandbox: pod/PVC/service materialization, identity propagation, status conditions, scale subresource, and the cluster-domain FQDN logic.
- [SandboxClaim Reconciler](https://grok-wiki.com/public/wiki/kubernetes-sigs-agent-sandbox-c3f2597a654a/pages/12-sandboxclaim-reconciler.md): The largest controller in the project: template resolution, env/metadata injection, warm-pool adoption, pod-exclusivity invariants, foreground deletion, and TTL after finish.
- [SandboxTemplate Reconciler](https://grok-wiki.com/public/wiki/kubernetes-sigs-agent-sandbox-c3f2597a654a/pages/13-sandboxtemplate-reconciler.md): Validation and bookkeeping done by the template controller, including how template changes ripple to claims and warm pools.
- [SandboxWarmPool Reconciler](https://grok-wiki.com/public/wiki/kubernetes-sigs-agent-sandbox-c3f2597a654a/pages/14-sandboxwarmpool-reconciler.md): Pool maintenance loop: parallel batch creation/deletion bounded by max-batch-size, rollout on template changes, and watcher coordination with SandboxClaim.
- [Warm Sandbox Queue](https://grok-wiki.com/public/wiki/kubernetes-sigs-agent-sandbox-c3f2597a654a/pages/15-warm-sandbox-queue.md): The in-memory queue shared between the warm-pool and claim reconcilers that hands off warm sandboxes to incoming claims.
- [Lifecycle & Expiry Logic](https://grok-wiki.com/public/wiki/kubernetes-sigs-agent-sandbox-c3f2597a654a/pages/16-lifecycle-expiry-logic.md): Shared expiry helpers used by Sandbox and SandboxClaim controllers to compute shutdown times, requeue durations, and policy-driven cleanup.
- [Metrics & Sandbox Collector](https://grok-wiki.com/public/wiki/kubernetes-sigs-agent-sandbox-c3f2597a654a/pages/17-metrics-sandbox-collector.md): Reconciler latency/result metrics plus the custom Prometheus collector that surfaces per-sandbox phase, age, and warm-pool stats.
- [OpenTelemetry Tracing Setup](https://grok-wiki.com/public/wiki/kubernetes-sigs-agent-sandbox-c3f2597a654a/pages/18-opentelemetry-tracing-setup.md): Provider-neutral OTLP tracing wiring used by both the controller binary and the SDKs; instrumenter interface and no-op fallback.
- [Go High-Level SDK (clients/go/sandbox)](https://grok-wiki.com/public/wiki/kubernetes-sigs-agent-sandbox-c3f2597a654a/pages/19-go-high-level-sdk-clients-go-sandbox.md): The high-level Go client: Sandbox lifecycle, command execution, file transfer, port tunnels, gateway, connector strategies, and tracing helpers.
- [Generated Go Clientsets, Informers & Listers](https://grok-wiki.com/public/wiki/kubernetes-sigs-agent-sandbox-c3f2597a654a/pages/20-generated-go-clientsets-informers-listers.md): The k8s.io/client-go-style generated machinery for Sandbox and extensions: typed clientsets, informers, listers, and the codegen wiring.
- [Python Sync SDK Core](https://grok-wiki.com/public/wiki/kubernetes-sigs-agent-sandbox-c3f2597a654a/pages/21-python-sync-sdk-core.md): Synchronous Python client surface: SandboxClient, Sandbox, connector, command executor, filesystem helpers, and the k8s helper layer.
- [Python Async SDK](https://grok-wiki.com/public/wiki/kubernetes-sigs-agent-sandbox-c3f2597a654a/pages/22-python-async-sdk.md): The asyncio mirror of the sync SDK: AsyncSandboxClient, AsyncSandbox, async connector, async filesystem, and async command executor.
- [Python Extensions, Gateway & Sandbox Router](https://grok-wiki.com/public/wiki/kubernetes-sigs-agent-sandbox-c3f2597a654a/pages/23-python-extensions-gateway-sandbox-router.md): Optional Python add-ons: computer-use extension, GKE pod-snapshot extensions, the sandbox-router service, and the kind-based gateway harness.
- [Helm Chart Layout](https://grok-wiki.com/public/wiki/kubernetes-sigs-agent-sandbox-c3f2597a654a/pages/24-helm-chart-layout.md): Structure of the Helm chart: CRD shipping, deployment template, controller-args helper, RBAC bindings, and values knobs that map to controller flags.
- [Static Manifests & Generated RBAC](https://grok-wiki.com/public/wiki/kubernetes-sigs-agent-sandbox-c3f2597a654a/pages/25-static-manifests-generated-rbac.md): The kubectl-apply-ready manifests in k8s/ plus the generated ClusterRole/Binding files used by both core and extensions controllers.
- [Examples Library Map](https://grok-wiki.com/public/wiki/kubernetes-sigs-agent-sandbox-c3f2597a654a/pages/26-examples-library-map.md): Tour of the examples/ tree: AIO sandbox, Chrome/VSCode/JupyterLab, agent frameworks (Hermes, LangChain, ADK, Ray, Kueue), policy and scaling scenarios.
- [Build, Codegen & Repository Tools](https://grok-wiki.com/public/wiki/kubernetes-sigs-agent-sandbox-c3f2597a654a/pages/27-build-codegen-repository-tools.md): Make targets, the codegen.go shim, deepcopy/CRD generation, lint configuration, and the dev/tools scripts that power local development.
- [E2E Test Framework](https://grok-wiki.com/public/wiki/kubernetes-sigs-agent-sandbox-c3f2597a654a/pages/28-e2e-test-framework.md): Layout of the Go e2e suite, the framework client/predicates/watchset helpers, and the parallel/replica/shutdown scenario coverage.
- [Load Testing & CI Pipelines](https://grok-wiki.com/public/wiki/kubernetes-sigs-agent-sandbox-c3f2597a654a/pages/29-load-testing-ci-pipelines.md): cluster-loader-based load-test recipes plus the prowjob presubmit/periodic configuration that runs them in CI.
- [KEPs & Roadmap](https://grok-wiki.com/public/wiki/kubernetes-sigs-agent-sandbox-c3f2597a654a/pages/30-keps-roadmap.md): In-flight design proposals tracked under docs/keps (suspended state, metadata propagation, Python SDK refactor) and the published roadmap.

## Source Files

- `AGENTS.md`
- `api/v1beta1/groupversion_info.go`
- `api/v1beta1/sandbox_types.go`
- `api/v1beta1/zz_generated.deepcopy.go`
- `clients/go/sandbox/client.go`
- `clients/go/sandbox/commands.go`
- `clients/go/sandbox/connector.go`
- `clients/go/sandbox/files.go`
- `clients/go/sandbox/gateway.go`
- `clients/go/sandbox/sandbox.go`
- `clients/go/sandbox/tracing.go`
- `clients/go/sandbox/tunnel.go`
- `clients/k8s/clientset/versioned`
- `clients/k8s/extensions/clientset`
- `clients/k8s/extensions/informers`
- `clients/k8s/extensions/listers`
- `clients/python/agentic-sandbox-client/gateway-kind/README.md`
- `clients/python/agentic-sandbox-client/k8s_agent_sandbox/async_connector.py`
- `clients/python/agentic-sandbox-client/k8s_agent_sandbox/async_k8s_helper.py`
- `clients/python/agentic-sandbox-client/k8s_agent_sandbox/async_sandbox_client.py`
- `clients/python/agentic-sandbox-client/k8s_agent_sandbox/async_sandbox.py`
- `clients/python/agentic-sandbox-client/k8s_agent_sandbox/commands/async_command_executor.py`
- `clients/python/agentic-sandbox-client/k8s_agent_sandbox/commands/command_executor.py`
- `clients/python/agentic-sandbox-client/k8s_agent_sandbox/connector.py`
- `clients/python/agentic-sandbox-client/k8s_agent_sandbox/extensions/computer_use.py`
- `clients/python/agentic-sandbox-client/k8s_agent_sandbox/files/async_filesystem.py`
- `clients/python/agentic-sandbox-client/k8s_agent_sandbox/files/filesystem.py`
- `clients/python/agentic-sandbox-client/k8s_agent_sandbox/gke_extensions`
- `clients/python/agentic-sandbox-client/k8s_agent_sandbox/k8s_helper.py`
- `clients/python/agentic-sandbox-client/k8s_agent_sandbox/sandbox_client.py`
- `clients/python/agentic-sandbox-client/k8s_agent_sandbox/sandbox.py`
- `clients/python/agentic-sandbox-client/k8s_agent_sandbox/trace_manager.py`
- `clients/python/agentic-sandbox-client/otel-collector-config.yaml.example`
- `clients/python/agentic-sandbox-client/sandbox-router/README.md`
- `clients/python/agentic-sandbox-client/sandbox-router/sandbox_router.py`
- `cmd/agent-sandbox-controller/main.go`
- `codegen.go`
- `controllers/sandbox_controller_test.go`
- `controllers/sandbox_controller.go`
- `controllers/testmain_test.go`
- `dev/ci/periodics`
- `dev/ci/presubmits`
- `dev/load-test/cluster-loader-sandbox.yaml`
- `dev/load-test/README.md`
- `dev/tools/client-gen-go.sh`
- `dev/tools/create-kind-cluster`
- `dev/tools/deploy-to-kube`
- `dev/tools/lint-api`
- `dev/tools/test-unit`
- `Dockerfile`
- `docs/api.md`
- `docs/configuration.md`
- `docs/development.md`
- `docs/keps/119-sandbox-suspended-state/README.md`
- `docs/keps/174-metadata-propagation/README.md`
- `docs/keps/359-refactor-python-sdk/README.md`
- `docs/keps/README.md`
- `docs/prowjob_manual_run.md`
- `docs/testing.md`
- `examples/chrome-sandbox`
- `examples/hello-world-sandbox`
- `examples/hpa-swp-scaling`
- `examples/jupyterlab`
- `examples/policy`
- `examples/quickstart/gvisor.md`
- `examples/quickstart/kata-containers.md`
- `examples/quickstart/README.md`
- `examples/README.md`
- `examples/vscode-sandbox`
- `extensions/api/v1beta1/groupversion_info.go`
- `extensions/api/v1beta1/sandboxclaim_types.go`
- `extensions/api/v1beta1/sandboxtemplate_types.go`
- `extensions/api/v1beta1/sandboxwarmpool_types.go`
- `extensions/controllers/queue/simple_sandbox_queue_test.go`
- `extensions/controllers/queue/simple_sandbox_queue.go`
- `extensions/controllers/sandboxclaim_controller_test.go`
- `extensions/controllers/sandboxclaim_controller.go`
- `extensions/controllers/sandboxclaim_pod_exclusivity_test.go`
- `extensions/controllers/sandboxtemplate_controller_test.go`
- `extensions/controllers/sandboxtemplate_controller.go`
- `extensions/controllers/sandboxwarmpool_controller_test.go`
- `extensions/controllers/sandboxwarmpool_controller.go`
- `extensions/controllers/utils.go`
- `extensions/examples/README.md`
- `extensions/examples/sandbox-claim.yaml`
- `extensions/examples/sandboxclaim.yaml`
- `extensions/examples/sandboxtemplate.yaml`
- `extensions/examples/sandboxwarmpool.yaml`
- `extensions/examples/secure-sandboxtemplate.yaml`
- `go.mod`
- `helm/Chart.yaml`
- `helm/crds/agents.x-k8s.io_sandboxes.yaml`
- `helm/README.md`
- `helm/templates/_controller-args.tpl`
- `helm/templates/deployment.yaml`
- `helm/values.yaml`
- `internal/lifecycle/expiry_test.go`
- `internal/lifecycle/expiry.go`
- `internal/metrics/metrics_test.go`
- `internal/metrics/metrics.go`
- `internal/metrics/sandbox_collector_test.go`
- `internal/metrics/sandbox_collector.go`
- `internal/metrics/tracing.go`
- `internal/version/`
- `k8s/controller.yaml`
- `k8s/crds/agents.x-k8s.io_sandboxes.yaml`
- `k8s/crds/extensions.agents.x-k8s.io_sandboxclaims.yaml`
- `k8s/crds/extensions.agents.x-k8s.io_sandboxtemplates.yaml`
- `k8s/crds/extensions.agents.x-k8s.io_sandboxwarmpools.yaml`
- `k8s/extensions-rbac.generated.yaml`
- `k8s/extensions.controller.yaml`
- `k8s/extensions.yaml`
- `k8s/rbac.generated.yaml`
- `Makefile`
- `README.md`
- `roadmap.md`
- `test/e2e/basic_test.go`
- `test/e2e/extensions/warmpool_rollout_test.go`
- `test/e2e/framework/client.go`
- `test/e2e/framework/watchset.go`
- `test/e2e/parallelism_test.go`
- `test/e2e/README.md`
- `tools.mod`