🚀 Announcing Agent Sandbox v0.5.2!

We're excited to announce the release of Agent Sandbox v0.5.2! This release focuses on significant improvements to core stability, lifecycle management, and developer experience, alongside robust enhancements to our testing infrastructure and expanded documentation. Key updates include critical fixes for warm pool adoption and cold restarts, new Sandbox examples for gVisor and Windows environments, and major upgrades to the sandbox router's WebSocket proxying capabilities. We've also streamlined the installation process with a new all-in-one manifest and provided numerous documentation clarity fixes.

⚠️ Breaking Changes / Action Required

• Python SDK use_pod_ip parameter removed (#1033): The use_pod_ip parameter has been removed from Python clients. In-cluster connections now automatically prefer the sandbox pod IP when available and fall back to in-cluster DNS otherwise. Users who explicitly set this parameter will need to remove it from their code.
• Installation Asset Renames (#1012): To streamline installation and improve GitOps compatibility, the primary core installation asset manifest.yaml has been renamed to sandbox.yaml. A new collision-free, all-in-one asset combining core and extensions is now available as sandbox-with-extensions.yaml. Users previously referencing manifest.yaml or attempting to combine core and extensions for GitOps workflows should update their deployment manifests.

Key Highlights

Core Stability & Lifecycle Management

• Warm Pool Adoption Fixes
  • Restore Warm Adoption from Pre-v1beta1 Warm Pools (#1191, #1197): Fixed a regression where SandboxClaims failed to warm-adopt sandboxes whose owner references were written by pre-v1beta1 (v0.4.x) pool controllers after an in-place upgrade, causing silent cold-starts. Owner references are now matched by group and kind instead of exact apiVersion.
  • Fix Warm-Claim Cold Restart on v0.5.0 Upgrade (#1124): Resolved an issue causing warm-started sandbox claims to cold-restart due to unretried optimistic lock conflicts or transient lookup errors during controller upgrades.
• NetworkPolicy Enforcement
  • Propagate sandbox-template-ref-hash Label to Pods (#1067): Ensured that the agents.x-k8s.io/sandbox-template-ref-hash label is explicitly propagated from the Sandbox CR to the Pod, restoring network isolation for all template-derived Sandboxes previously blocked by the system-label filter.
• Warm Pool Enhancements
  • Expanded Warm Pool Staleness Detection (#1102): Warm pool staleness detection now tracks VolumeClaimTemplates and Service configuration alongside PodTemplate. Updates to storage or service settings in a SandboxTemplate will now correctly trigger warm pool recreation under the Recreate update strategy.
  • Optimized Sandbox Cache Indexing (#1137): Improved warm pool controller efficiency by indexing the sandbox cache by warm pool label, avoiding O(n) list operations in reconcilePool for better performance.
• Controller Configuration
  • Gate Webhook Implementation (#1186): Introduced an --enable-webhook flag (default: true) allowing operators to explicitly enable or disable the controller-runtime webhook server and registrations, reducing RBAC requirements for deployments not using webhooks.
  • Helm Chart Flag Honoring (#942): Fixed the Helm chart silently ignoring explicitly-set false/0 controller values (e.g., --set controller.leaderElect=false), which previously left leader election enabled. Also added controller.sandboxWarmPoolMaxBatchSize and controller.enableWarmPoolEviction chart values.

Sandbox Router

• WebSocket Proxying (#923): The sandbox router now proxies WebSocket traffic to sandbox pods, supporting browser UIs like JupyterLab. Includes configurable idle timeout, max lifetime, max message size, and per-client connection limits, with TRUSTED_PROXY_CIDRS for security.
• Retry Loop Optimization (#1181): Replaced time.After with a reusable time.NewTimer in the retry loop, reducing unnecessary timer allocations and improving retry mechanism efficiency.
• Build Fix (#1133): Fixed an issue where the sandbox-router-go image was incorrectly built from the controller Dockerfile due to build context mismatches in dev/tools/push-images.

Developer Experience & Examples

• Streamlined Installation (#1012): Introduced a collision-free all-in-one install asset (sandbox-with-extensions.yaml) for seamless integration with kustomize and GitOps engines.
• New Sandbox Examples
  • gVisor-isolated OpenClaw Sandbox with PVC Persistence (#1024): Added a production-shaped, gVisor-isolated deployment example for OpenClaw using SandboxTemplate, SandboxWarmPool, and SandboxClaim, with persistent storage and NodePort/LoadBalancer access.
  • Windows Sandbox Example (#1117): Added an example demonstrating how to run a Windows guest via KVM/QEMU within the Agent Sandbox.
  • Aider Sandbox Example (#1142): Provided a new example for running Aider (AI coding assistant) in an isolated sandbox environment.

Python SDK

• Track Sandboxes Created via SDK (#1039): Sandboxes created programmatically via the Python SDK are now stamped with agents.x-k8s.io/created-by: python-client label, with corresponding Prometheus telemetry.
• Encode Dot File Paths (#1115): Fixed Go SDK file operations for dot paths (e.g., List(".")) to prevent server-side path normalization redirects.

Documentation Improvements

• Consolidated Doc Fixes (#1178): Addressed several small documentation issues, including pod count mismatches, JSON patch examples, port-forwarding targets, CRD schema accuracy, and sandbox router paths.
• API Versioning Roadmap Clarity (#1163): Clarified the Alpha to Beta API Versioning roadmap status, noting the existing v1beta1 API types across CRDs and the deprecation warning for v1alpha1.
• Link and Prerequisite Corrections (#1162, #1161, #1173, #1172, #1170, #1168, #1171): Fixed broken links, corrected prerequisite descriptions, updated URLs to HTTPS, and removed outdated references across various documentation pages and examples.

Performance & Testing Improvements

• CNI-Parameterized Benchmarking (#1195): Added CNI-parameterized benchmark job scripts under dev/ci to enable performance testing with different CNIs (e.g., Cilium, Kindnet).
• Cilium Metrics Integration (#1187): Enabled Cilium-agent Prometheus metrics on the kOps cluster and added dedicated report pages to analyze CNI performance during stress tests, identifying rate-limiting issues.
• Pprof Flame Graphs in Stress Reports (#1184): Integrated pprof flame graph generation for kube-apiserver CPU profiles directly into stress reports, aiding in bottleneck analysis.
• Automated Problem Reporting in Stress Tests (#1180): Enhanced stress test reporting with a new HTML report that analyzes data using DuckDB and highlights known performance problems.
• Capacity-Aware Stress Testing (#1183): Stress tests now fail explicitly when the configured load exceeds spare cluster pod capacity, preventing silently invalid test results.
• Comprehensive Prometheus Metrics Collection (#1176): Stress runs now collect Prometheus metrics from control-plane components, the sandbox controller, and kubelets into metrics.jsonl.gz.
• Phase-Based Stress Test Records (#1175, #1159): Stress sandbox records are now keyed by a 1-based PhaseNumber, and stress tests are split into fill, probe, and throughput phases to measure latency and throughput without conflating capacity queueing.
• CI Resilience & Debuggability
  • Retry Cluster Bring-up Steps (#1101): Improved CI robustness by retrying transient failures during cluster setup in the presubmit runner.
  • Enriched Stress Harness Milestones (#1135): Stress harness now records per-stage launch latency, throughput, and per-sandbox timelines for detailed performance analysis.
  • Loud Failure on Bad Image Pushes (#1134): dev/tools/push-images now fails loudly on unknown or duplicate images, preventing silent tag issues.
  • Kubeadm Config Fix (#1126): Updated kubeadm extraArgs to v1beta4 list format in create-kind-cluster to fix Kind cluster creation failures in E2E presubmits.
  • Release CI Fix (#1120): Fixed a bug causing release CI to fail by making protobuf/gRPC code generation self-bootstrapping.
  • Deterministic Skill Evaluation (#1127): Added a deterministic skill evaluation suite for the triage-issues skill.

Dependency Updates

• Go Modules and Docker Dependencies (#1147, #1146, #1145): Bumped golang.org/x/net, golang.org/x/sync, and golang versions across various gomod-dependencies and docker-dependencies groups.

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.2/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.2/sandbox.yaml

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

Python SDK

pip install k8s-agent-sandbox==0.5.2

Contributors

We extend our sincere thanks to all contributors to this release:
@Leonard013, @LuBingtan, @SHRUTI6991, @aditya-shantanu, @akvnn, @app/dependabot, @dongjiang1989, @esposem, @janetkuo, @lunarwhite, @mj006648, @sairajp-rewind, @tarujg

New Contributors

• @minhthong582000 made their first contribution in #1102
• @tarujg made their first contribution in #1012
• @mj006648 made their first contribution in #1033
• @LuBingtan made their first contribution in #1115
• @Leonard013 made their first contribution in #1133
• @akvnn made their first contribution in #942

Full Changelog: v0.5.1...v0.5.2