v0.5.6

🚀 Announcing Agent Sandbox v0.5.6!

We're excited to announce the release of Agent Sandbox v0.5.6! This release brings significant improvements to controller reliability, warm pool lifecycle management, and race condition handling. It also introduces backing pod scheduling condition mirroring, Prometheus Operator monitoring resources in the Helm chart, filesystem tools in the MCP server, suspend/resume latency metrics in the Python SDK, and new examples for Pi coding agent, E2B envd daemon, and n8n orchestration.

Key Highlights

Core Controller & Warm Pool Lifecycle

• Strict Sandbox-to-Pod Mapping (#1337): Enforced controller owner reference UIDs as the authoritative Sandbox-to-Pod mapping, preventing duplicate pod creation when pod-name annotations are missing or stale. If multiple owned pods exist, reconciliation safely fails closed with Ready=False (reason MultiplePods) and emits a warning event.
• Warm Pool Stale Sandbox Adoption Prevention (#1078): Fixed a race condition where SandboxClaim could adopt stale template pods under the Recreate update strategy by enforcing semantic blueprint and content hash checks on candidate adoption.
• Transient Pod Networking Adoption Gate (#683): Added bounded wait and requeue logic to SandboxClaim to ensure rotating warm-pool candidates report pod networking before adopting them or falling back to cold creation.
• Informers Cache Lag Resilience (#1072): Added bounded 200ms requeuing and the SandboxCreatePending condition when createSandbox encounters transient AlreadyExists errors due to informer cache lag, preventing workqueue churn and status wipes.
• Warm Pool observedGeneration (#1328): Added status.observedGeneration to SandboxWarmPool to allow clients and GitOps tooling to reliably detect when the controller has finished processing spec updates.
• Configurable Readiness Grace Period and Recheck Cadence (#1290): Added --sandbox-warm-pool-readiness-grace-period (default 5m) and --sandbox-warm-pool-unschedulable-recheck-interval (default 1m) controller flags to accommodate slower image startup times and node auto-provisioning latency.

API & Observability Enhancements

• Pod Scheduling Status Mirroring (#1291): Mirrored the backing pod's PodScheduled condition into Sandbox.status.conditions (surfacing reasons like Unschedulable and SchedulingGated), enabling diagnosis of scheduling issues without requiring pod-level RBAC.
• Centralized API Enum Validations (#1288): Refactored +kubebuilder:validation:Enum markers to type definitions across SandboxOperatingMode, NetworkPolicyManagement, EnvVarsInjectionPolicy, and VolumeClaimTemplatesPolicy for strict CRD validation.
• API Documentation & Defaults Clarification (#1106): Clarified doc comments regarding desired operating mode vs. observed readiness conditions, environment variable injection cold-start behaviors, and status field clearance during suspension.

SDKs & MCP Tooling

• MCP Filesystem Parity Tools (#1329): Added list_files and file_exists tools to the Agent Sandbox MCP server with token-budget bounding and isolation checks, aligning capabilities with the Go and Python SDKs.
• Python SDK Suspend/Resume Telemetry (#1143): Added Prometheus histogram metrics (sandbox_client_suspend_latency_ms, sandbox_client_resume_latency_ms, sandbox_client_restore_latency_ms) to benchmark snapshot and restore lifecycle operations.
• Optional Warm Pool Option in Go SDK (#1179): Relaxed sandbox.NewClient validation so Options.WarmPoolName is only required when actively provisioning a claim via CreateSandbox or Open().
• Reinforcement Learning Harness Robustness (#1314): Added deep container spec merging to preserve custom images/specs when injecting volumes and environment variables, defensive exec stream handling, and concurrent batch fleet cleanup.

Helm & Deployment Operations

• Opt-in Prometheus Operator Resources (#1355, #1017): Added Helm support for deploying an opt-in ServiceMonitor to scrape the /metrics endpoint and a starter PrometheusRule alert (AgentSandboxControllerMetricsTargetsDown).
• Helm Image Pull Secrets (#1370): Added support for configuring imagePullSecrets on the controller deployment via Helm values.
• Podman Deployment Support (#1152): Added support for deploying local kind clusters using Podman (CONTAINER_ENGINE=podman make deploy-kind).

Ecosystem Examples & Workloads

• Pi Coding Agent Example (#1373): Added a sandbox example running the terminal-based Pi coding agent with interactive TUI attach and persistent workspace storage.
• E2B envd Sandbox Example (#1302): Added an example demonstrating E2B's envd daemon running inside a sandbox container, complete with REST/gRPC API support and verification clients across Python, Go, TypeScript, and Bash.
• n8n Workflow Integration Example (#1345): Added an integration example for managing sandbox lifecycles and tool executions directly from n8n workflows.
• Python Runtime Non-Blocking Execution (#1380, #1025): Offloaded /execute handler subprocess execution from the FastAPI event loop and added SANDBOX_EXEC_TIMEOUT_SECONDS (default 300s) to prevent commands from wedging sandbox health checks.
• Example Documentation Coverage (#1372): Published documentation website entries for 18 previously undocumented example architectures and integration patterns.

Installation

Standard Install (Core + Extensions)

Recommended for most users and GitOps engines (Argo CD, Config Sync, kustomize):

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

Selective Install

Install components separately:

# Core only:
kubectl apply -f https://github.com/kubernetes-sigs/agent-sandbox/releases/download/v0.5.6/sandbox.yaml

# Extensions (opt-in):
kubectl apply -f https://github.com/kubernetes-sigs/agent-sandbox/releases/download/v0.5.6/extensions.yaml

Python SDK

pip install k8s-agent-sandbox==0.5.6

---

Contributors

We extend our sincere thanks to all contributors to this release:
@Ryotess, @aditya-shantanu, @aegeiger, @akvnn, @alanhuangch, @dependabot, @chw120, @dongjiang1989, @drogovozDP, @esposem, @hchenxa, @janetkuo, @jensvandenreyt, @lunarwhite, @ngopalak-redhat, @noeljackson, @prash2512, @pujitha24, @shrutiyam-glitch, @tom1299, @yingjun8, @yuzhiquan

New Contributors

• @yuzhiquan made their first contribution in #1290
• @pujitha24 made their first contribution in #1380
• @Ryotess made their first contribution in #1025
• @alanhuangch made their first contribution in #1337
• @yingjun8 made their first contribution in #1106
• @jensvandenreyt made their first contribution in #1370

Full Changelog: v0.5.5...v0.5.6