Agent Sandbox Developer Reference Wiki

Pages

1. Technical OrientationPurpose of agent-sandbox, its core/extensions split, controller-manager entry point, and a map for navigating the rest of this developer reference.
2. Installation & Deployment ModesInstalling the controller via released YAML, Helm chart, or kind clusters; choosing between core-only and core+extensions deployments.
3. Quickstart Paths (gVisor, Kata, Vanilla)Walkthrough of the quickstart manifests for vanilla, gVisor, and Kata runtimes, plus how the examples directory organizes runnable scenarios.
4. Controller Configuration & Tuning FlagsAll command-line flags exposed by the controller binary: QPS/burst, worker concurrency, warm-pool batch size, leader election, pprof, tracing, and cluster domain.
5. Sandbox CRD (agents.x-k8s.io/v1beta1)Field-by-field reference for the core Sandbox resource: PodTemplate, VolumeClaimTemplates, Lifecycle, Replicas (0/1), and Service toggle.
6. SandboxTemplate CRDReusable template type used by SandboxClaim and SandboxWarmPool, including the embedded Sandbox spec it encapsulates.
7. SandboxClaim CRDClaim resource that resolves to a Sandbox: template references, warm-pool policy, env injection, additional pod metadata, and shutdown policies (Delete, DeleteForeground, Retain).
8. SandboxWarmPool CRDSpecification of pre-warmed sandbox pools: template binding, replica counts, and adoption semantics consumed by SandboxClaim.
9. Conditions, Reasons & Status SurfacesCatalogue 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.
10. Controller Manager Entry PointHow cmd/agent-sandbox-controller/main.go wires schemes, the controller-runtime Manager, metrics/pprof servers, leader election, and the optional extensions reconciler set.
11. Sandbox ReconcilerReconciliation loop for the core Sandbox: pod/PVC/service materialization, identity propagation, status conditions, scale subresource, and the cluster-domain FQDN logic.
12. SandboxClaim ReconcilerThe largest controller in the project: template resolution, env/metadata injection, warm-pool adoption, pod-exclusivity invariants, foreground deletion, and TTL after finish.
13. SandboxTemplate ReconcilerValidation and bookkeeping done by the template controller, including how template changes ripple to claims and warm pools.
14. SandboxWarmPool ReconcilerPool maintenance loop: parallel batch creation/deletion bounded by max-batch-size, rollout on template changes, and watcher coordination with SandboxClaim.
15. Warm Sandbox QueueThe in-memory queue shared between the warm-pool and claim reconcilers that hands off warm sandboxes to incoming claims.
16. Lifecycle & Expiry LogicShared expiry helpers used by Sandbox and SandboxClaim controllers to compute shutdown times, requeue durations, and policy-driven cleanup.
17. Metrics & Sandbox CollectorReconciler latency/result metrics plus the custom Prometheus collector that surfaces per-sandbox phase, age, and warm-pool stats.
18. OpenTelemetry Tracing SetupProvider-neutral OTLP tracing wiring used by both the controller binary and the SDKs; instrumenter interface and no-op fallback.
19. Go High-Level SDK (clients/go/sandbox)The high-level Go client: Sandbox lifecycle, command execution, file transfer, port tunnels, gateway, connector strategies, and tracing helpers.
20. Generated Go Clientsets, Informers & ListersThe k8s.io/client-go-style generated machinery for Sandbox and extensions: typed clientsets, informers, listers, and the codegen wiring.
21. Python Sync SDK CoreSynchronous Python client surface: SandboxClient, Sandbox, connector, command executor, filesystem helpers, and the k8s helper layer.
22. Python Async SDKThe asyncio mirror of the sync SDK: AsyncSandboxClient, AsyncSandbox, async connector, async filesystem, and async command executor.
23. Python Extensions, Gateway & Sandbox RouterOptional Python add-ons: computer-use extension, GKE pod-snapshot extensions, the sandbox-router service, and the kind-based gateway harness.
24. Helm Chart LayoutStructure of the Helm chart: CRD shipping, deployment template, controller-args helper, RBAC bindings, and values knobs that map to controller flags.
25. Static Manifests & Generated RBACThe kubectl-apply-ready manifests in k8s/ plus the generated ClusterRole/Binding files used by both core and extensions controllers.
26. Examples Library MapTour of the examples/ tree: AIO sandbox, Chrome/VSCode/JupyterLab, agent frameworks (Hermes, LangChain, ADK, Ray, Kueue), policy and scaling scenarios.
27. Build, Codegen & Repository ToolsMake targets, the codegen.go shim, deepcopy/CRD generation, lint configuration, and the dev/tools scripts that power local development.
28. E2E Test FrameworkLayout of the Go e2e suite, the framework client/predicates/watchset helpers, and the parallel/replica/shutdown scenario coverage.
29. Load Testing & CI Pipelinescluster-loader-based load-test recipes plus the prowjob presubmit/periodic configuration that runs them in CI.
30. KEPs & RoadmapIn-flight design proposals tracked under docs/keps (suspended state, metadata propagation, Python SDK refactor) and the published roadmap.