github kubernetes-sigs/agent-sandbox v1.0.5
on GitHub

3 hours ago

🚀 Announcing Agent Sandbox v1.0.5!

We're excited to announce the release of Agent Sandbox v1.0.5! This release introduces a comprehensive runtime connectivity layer to the TypeScript SDK, native in-cluster sandboxd transport for Python and TypeScript clients, streaming file transfers, deterministic claim adoption, OpenAI Agents integration, new observability metrics, and high-scale controller tuning configurations in the Helm chart.

⚠️ Breaking Changes / Action Required

  • Deep Agents Adapter Requirements & Error Handling (#1511): The Deep Agents adapter now requires deepagents>=0.7.10,<0.8.0; support for Deep Agents 0.6 has been dropped. Additionally, execution transport and response failures now propagate as native exceptions rather than synthetic ExecuteResponse(exit_code=-1) results. Users upgrading the adapter must update their Deep Agents dependencies and handle operational exceptions.

Key Highlights

TypeScript SDK Runtime Layer & Enhancements

  • sandboxd Runtime Execution & Filesystem Layer (#1759, #1596): Added full runtime connectivity to Sandbox handles, enabling command execution via gRPC (sandbox.commands.run()), filesystem operations (read, write, exists, list, delete), and health/metadata endpoints (sandbox.health(), sandbox.metadata()).
  • Streaming File Transfers (#1759): Added sandbox.files.readStream() and sandbox.files.writeStream() to transfer large files without buffering entire payloads into client memory.
  • Direct In-Cluster Connectivity (#1759): Added support for direct in-cluster transport modes (in-cluster-service and in-cluster-pod-ip) alongside the standard port-forward transport.
  • Label Selectors & Pod Metadata (#1606, #1778): Added labelSelector support to SandboxClient.listAllSandboxes and added podLabels and podAnnotations options to createSandbox.
  • Standardized Error Handling (#1766, #1779): Converted validation and timeout errors across the SDK to consistently throw SandboxError, and treated InvalidConfiguration as a terminal claim ready condition to fail fast instead of waiting out the timeout.

Python SDK & Framework Integrations

  • Direct In-Cluster sandboxd Transport (#1750): Added SandboxdInClusterConnectionConfig to connect directly to sandboxd via Service DNS or Pod IP without requiring local port-forwards.
  • Streaming File Uploads (#1634): Filesystem.write and AsyncFilesystem.write now accept binary file objects and stream uploads in chunks without memory buffering.
  • Deterministic Claim Creation & Adoption (#1573): Added claim_name and adopt_existing parameters to create_sandbox across sync and async clients, enabling durable workflows to safely adopt existing claims on retry.
  • Safe Sandbox Lookup (#1770): Fixed an issue where transient lookup failures during get_sandbox() could inadvertently delete active SandboxClaims and running sandboxes.
  • OpenAI Agents SDK Integration (#1388): Added dedicated integration package (clients/integrations/openai) allowing OpenAI Agents to run seamlessly inside Agent Sandbox with workspace hydration and session resumption.
  • Fast Failure on Invalid Configuration (#1747): Added InvalidConfiguration to TERMINAL_CLAIM_READY_REASONS to fail fast when unrecoverable child-resource validation errors occur.
  • Local Tunnel Concurrency & Diagnosis (#1683, #1132): Protected tunnel connections with an re-entrant lock to prevent port-forward leaks under concurrent first requests, and included namespace context in router error messages.

Core Controller, Extensions & Observability

  • High-Scale Controller Tuning Flags (#1794): Exposed high-scale controller flags (including --api-connections, --cache-label-selectors, --sandbox-write-behind-window, --sandbox-warm-pool-replenish-delay, and event suppression flags) as first-class parameters under controller.* in the Helm chart.
  • Warm Pool Size Gauge Metric (#1774): Added the agent_sandbox_warmpool_size Prometheus gauge metric reporting warm pool capacity partitioned by namespace, pool name, sandbox template, and sandbox readiness state.
  • Warm Pool Template Printer Column (#1790): Added a Template column to the SandboxWarmPool CRD for enhanced visibility when running kubectl get sandboxwarmpools.
  • Controller Cache-Lag Backoff (#1768): Implemented geometric requeue backoff (capped at 5s) for the SandboxClaim controller during informer cache lag races.
  • Mirrored PodScheduled Scheduling Optimization (#1439): Refactored warm pool unschedulable detection to read mirrored PodScheduled conditions from Sandbox.status rather than issuing Pod GET calls.
  • Router Cache Consistency (#1757): Fixed cache eviction logic in sandbox-router to cleanly remove stale or un-identified Pod entries on deletion and not-ready events.
  • Go SDK Ready Waiter (#1760): Added K8sHelper.WaitForSandboxReady to wait for a Sandbox's Ready condition with context deadlines and cancellation.
  • Go Fake Clientset Improvements (#795): Generated Server-Side Apply configurations and NewClientset constructors for fake Kubernetes clientsets.
  • Toolchain & Dependency Upgrades (#1733, #1786): Upgraded all Go builder images and toolchains to Go 1.27.1, and bumped Kubernetes dependencies to v0.37.1 and controller-runtime to v0.25.1.

Examples & Ecosystem

  • Reinforcement Learning Scoping Fixes (#1811): Assigned run IDs to pods under non-reserved labels (agent-sandbox-rl/run-id) and prevented on-demand runs from relabeling templates owned by other runs.
  • Ray RLlib PPO Integration (#1684): Added an end-to-end RLlib PPO training example demonstrating environment interaction with SandboxEnv.
  • WebMCP-to-MCP Bridge (#1754): Added an example using Playwright to bridge browser-registered WebMCP tools to MCP inside a Sandbox.
  • NemoClaw & OpenShell Example (#1501): Added an example showcasing NemoClaw running inside an Agent Sandbox using OpenShell.
  • urunc Unikernel Runtime Example (#1709): Added an example demonstrating sandboxes running as microVMs using the urunc OCI runtime.
  • Tilt Development Workflow (#1720): Added a development guide for running and testing Agent Sandbox applications with Tilt.
  • IRSA Simulation Hardening (#1579): Added a cryptographic STS trust verifier proxy to the LocalStack IRSA simulation example.
  • Python Runtime Shell Execution (#1765): Updated /execute in examples/python-runtime-sandbox to execute commands under a shell, enabling chaining and I/O redirection.

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/v1.0.5/sandbox-with-extensions.yaml

Selective Install

Install components separately: 

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

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

Python SDK

pip install k8s-agent-sandbox==1.0.5

Contributors

We extend our sincere thanks to all contributors to this release:
@1fanwang, @ArthurKamalov, @HasonoCell, @Karthik-Chowdary, @LucasGois1, @Pepper-rice, @Sean-790761, @YoungJinJung, @abhayjoshi201, @aditya-shantanu, @adityajoshi12, @dependabot, @chansuke, @cmainas, @drogovozDP, @ericcurtin, @felixmr1, @igooch, @james-westbrook, @janetkuo, @karimad, @khirotaka, @lunarwhite, @noeljackson, @tomergee, @vincent0426, @yuzhiquan

New Contributors

Full Changelog: v1.0.4...v1.0.5

Check out latest releases or
releases around kubernetes-sigs/agent-sandbox v1.0.5

Don't miss a new agent-sandbox release

NewReleases is sending notifications on new releases.

Get notifications