🚀 Announcing Agent Sandbox v1.0.6!

We're excited to announce Agent Sandbox v1.0.6! This release adds the first part of a multi-cluster warm-pool fleet planner, interactive processes via commands.start() in the TypeScript SDK, and closer parity across the Go and Python SDKs (per-request command timeouts, claim expiry, sandboxd health and metadata, claim labels and selectors). It also fixes warm-pool status updates under API throttling, stale evictions in the router cache, and dropped PTY output in sandboxd.

⚠️ Breaking Changes / Action Required

• Sandbox Name Length Validation with spec.service (#1475): The v1beta1 Sandbox CRD now rejects names longer than 63 characters when spec.service is true. These Sandboxes never worked: the controller gives the headless Service the Sandbox's name, so Service creation failed and the Sandbox never became Ready. A new root-level CEL rule now reports that failure at admission time.
  • Action Required: The rule covers the whole object and doesn't exempt existing objects. A pre-existing Sandbox with a name over 63 characters and spec.service: true will fail every update, including status updates. To fix it, disable or unset spec.service, or recreate the Sandbox with a name of 63 characters or fewer.
• Router Scoped-Token v2 Authorization & proxy.Lookup Interface (#1498): Scoped-token v2 now authorizes the Sandbox UID that sandbox-router resolves from its Pod cache, not the caller's X-Sandbox-UID header. A v2 token minted for a deleted Sandbox can no longer reach a replacement Sandbox with the same name. Path-routed (browser) requests now authorize with v2 instead of failing with 403. Under v2, cache misses and X-Sandbox-Pod-IP overrides are rejected. In every mode, if a request's X-Sandbox-UID and X-Sandbox-ID disagree, it now routes to the Sandbox named by X-Sandbox-ID.
  • Action Required: Out-of-tree implementations of proxy.Lookup must implement Resolve instead of Get/GetByName, pass the dialed cache.Entry to Invalidate, and drop InvalidateByName.

Key Highlights

Core Controller & Router Stability

• Warm Pool Status Updates Under Throttling (#1852): Fixed SandboxWarmPool status.replicas and status.readyReplicas freezing when a reconcile hit partial batch errors, such as APF 429 Too Many Requests throttling during batch creation.
• Configurable Warm-Candidate Grace Period (#1758): The new --sandbox-claim-warm-candidate-grace-period flag (default 2s) sets how long a SandboxClaim waits for a warm candidate to report a Pod IP before falling back to cold creation. Raise it on clusters with slow IPAM or CNI.
• Ready Event Gating (#1826): Sandbox Ready-transition events are now gated on both the Ready condition's status and its reason. New tests confirm the transition reconciles without panicking when events are disabled with --disable-sandbox-events.
• UID-Fenced Router Cache Invalidation (#1498): sandbox-router now fences dial-failure and owner-change evictions by Pod UID. A slow dial failure to a terminated Pod no longer evicts the cache entry for its replacement.

Interactive Processes & sandboxd Runtime

• Interactive Processes in the TypeScript SDK (#1802): The new commands.start() launches long-running processes, shells, and REPLs. It supports streaming stdin/stdout/stderr, backpressure, PTY sizing and resizing, signals (signal(), kill()), and process lifecycle management.
• sandboxd PTY Output and Initial Size (#1804): Fixed races in the sandboxd ProcessService where short-lived PTY processes lost buffered output before the stream ended, or started with a 0x0 window.

SDK Parity & Developer Experience

• Python SDK Improvements:
  • Injected ApiClient (#1509): SandboxClient, AsyncSandboxClient, K8sHelper, and AsyncK8sHelper accept a pre-configured api_client for multi-cluster and multi-context setups.
  • kubectl Tunnels Follow the Injected Client (#1830): kubectl port-forward tunnels now use the cluster and credentials of an injected api_client instead of the ambient kubeconfig. Basic auth is not carried over.
  • Per-Request Command Timeouts (#1842): commands.run() accepts command_timeout, and ExecutionResult exposes timed_out, in both the legacy runtime and sandboxd modes.
  • mTLS and Custom Headers for Direct Connections (#1782): SandboxDirectConnectionConfig adds extra_headers, client_cert, and ca_cert.
  • In-Cluster Mode Names Aligned with Go and TypeScript (#1854): The SandboxdInClusterConnectionConfig modes service-dns and pod-ip are renamed to in-cluster-service and in-cluster-pod-ip, and SandboxServiceUnavailableError is renamed to SandboxNoServiceError. The old names still work but are deprecated.
  • Kubernetes Client 37 Compatibility (#1869): Updated custom-object response parsing and Pod metadata handling for the typed signatures in kubernetes>=37.0.0.
• Go SDK Improvements:
  • Claim Expiry with ShutdownAfter (#1865): Options.ShutdownAfter sets spec.lifecycle.shutdownTime, with the Delete policy, on claims the client creates. A crashed client no longer leaks sandboxes. This matches the Python and TypeScript SDKs.
  • Command Environment & Working Directory (#1849): Run accepts WithEnv and WithWorkingDir.
  • Health & Metadata APIs (#1839): New Sandbox.Health and Sandbox.Metadata helpers for sandboxd.
  • Claim Labels & Selectors (#1836): Options.Labels labels claims at creation, and WithLabelSelector filters ListAllSandboxes.
  • Fail Fast on Terminal Claim Conditions (#1834): When a claim can't become ready, Open and GetSandbox now return a sentinel error right away (ErrWarmPoolNotFound, ErrTemplateNotFound, or ErrClaimFailed).
  • Clear Error for Unsupported Runtime (#1835): Run with RuntimeSandboxd over a direct REST APIURL now returns ErrUnsupportedByRuntime instead of hanging until it fails with ErrNotReady.
• TypeScript SDK Improvements:
  • Readiness & Pod IP Helpers (#1821, #1867): New Sandbox.status() and Sandbox.getPodIP(). Pod IPs are canonicalized, including IPv4-mapped IPv6 and dual-stack addresses.
  • Volume Claim Templates (#1814): createSandbox accepts volumeClaimTemplates.
  • Fail Fast on Clean Stream Close (#1792): commands.run() now fails immediately with a connection error when sandboxd closes the HTTP/2 stream without a response.

Multi-Cluster Fleet & Reinforcement Learning

• Multi-Cluster Warm-Pool Fleet Planner (#1435, #1394): Adds the multi-cluster fleet KEP and the first part of a reference planner under examples/multi-cluster-fleet/. It covers capacity-aware replica placement (Hamilton apportionment), warm-pool sizing, and a per-cluster member daemon that reconciles pools.
• Shared Run IDs in agent-sandbox-rl (#1813): The new FleetConfig.run_id lets a job's orchestrator and workers share one run ID, along with its warm pools and templates. Only the process that warmed a pool resizes or deletes it.

Examples & Documentation

• Docker Sandboxes Example (#1831): examples/docker-sbx runs Docker Sandboxes (sbx) inside Agent Sandbox microVMs on KVM-enabled Kubernetes nodes.
• Python Runtime Sandbox Timeouts (#1841): The examples/python-runtime-sandbox execution server accepts a per-request timeout_seconds and reports timed_out.
• Scale & Performance Tuning Guide (#1793): Expanded coverage of burst adoption vs. sustained throughput, warm-pool sharding, APF isolation, and controller worker tuning.
• Sandbox Status Conditions Reference (#1825): New reference for Sandbox status conditions and their transition reasons.

Installation

Standard Install (Core + Extensions)

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

kubectl apply -f https://github.com/kubernetes-sigs/agent-sandbox/releases/download/v1.0.6/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.6/sandbox.yaml

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

Python SDK

pip install k8s-agent-sandbox==1.0.6

Contributors

Thanks to everyone who contributed to this release:
@Aasif-Simpplr, @Beverly621, @YoungJinJung, @abhayjoshi201, @aditya-shantanu, @briankhoi, @dependabot, @ekam-walia, @ericcurtin, @hyperb1iss, @igooch, @ilaigold, @janetkuo, @khirotaka, @lunarwhite, @mtkumar123, @vicentefb

New Contributors

• @Beverly621 made their first contribution in #1475
• @Aasif-Simpplr made their first contribution in #1841
• @mtkumar123 made their first contribution in #1827
• @ilaigold made their first contribution in #1862
• @ekam-walia made their first contribution in #1863

Full Changelog: v1.0.5...v1.0.6

🚀 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.post1

(Note that ==1.0.5 won't match it; use ~=1.0.5, >=1.0.5, or ==1.0.5.post1.)

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

• @chansuke made their first contribution in #1746
• @adityajoshi12 made their first contribution in #1132
• @LucasGois1 made their first contribution in #1573
• @james-westbrook made their first contribution in #1720
• @abhayjoshi201 made their first contribution in #1757
• @felixmr1 made their first contribution in #1760
• @Karthik-Chowdary made their first contribution in #1764
• @cmainas made their first contribution in #1709
• @ericcurtin made their first contribution in #1765
• @YoungJinJung made their first contribution in #1781

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

🚀 Announcing Agent Sandbox v1.0.4!

We're excited to announce the release of Agent Sandbox v1.0.4! This release brings significant improvements across the board, including Kubernetes lifecycle event reporting for Sandboxes, streaming file download capabilities across SDKs, async sandboxd runtime support in Python, automatic sandbox expiration in TypeScript, enhanced concurrency isolation in the RL SDK, and numerous stability, security, and documentation enhancements.

Key Highlights

Core Controller & Lifecycle Management

• Kubernetes Lifecycle Events (#1532): The Sandbox reconciler now emits Kubernetes Events across key lifecycle transitions, including SandboxPodCreated, SandboxPodCreateFailed, SandboxReady, SandboxSuspended, SandboxExpired (for Retain shutdown policies), PodSucceeded, and PodFailed. Events can be toggled via the new --disable-sandbox-events controller flag.
• Terminal Validation for Long Service Names (#1630): Fixed an issue where Sandboxes with derived headless Service names exceeding the 63-character DNS-1035 limit caused controller hot-looping. Permanent apiserver invalidity errors are now classified as terminal, marking the resource as Ready=False with reason InvalidConfiguration without requeuing.
• Router Cache Invalidation Fencing (#1398): Enhanced the sandbox-router Pod cache to track backing Pod UIDs alongside Sandbox UIDs, preventing delayed delete/NotReady events from old pods from evicting newly created replacement pods.

SDKs & Client Libraries

• Streaming File Downloads (#1643): Added streaming file download support to the Go (ReadTo) and Python (read_to / AsyncFilesystem.read_to) SDKs. Callers can now stream files directly into custom writers/sinks without buffering large responses in memory.
• Python Async sandboxd Runtime Support (#1438, #1697): Added full async support for sandboxd to AsyncSandboxClient, including gRPC-based process execution and REST filesystem operations over direct Pod tunnels, with hardened cleanup routines across connection failures and cancellations.
• TypeScript SDK Expiration & Type Fixes (#1605, #1535): Added support for shutdownAfterSeconds in CreateSandboxOptions to automatically set controller-enforced expiration deadlines. Widened the return type of getSandboxClaimWarmpoolName() to Promise<string | undefined>.
• Resilient Python Watch Streams (#1612): Improved watch stream reliability in K8sHelper and AsyncK8sHelper by catching transient HTTP disconnects (e.g. ProtocolError, ReadTimeoutError, ClientConnectionError) and reconnecting transparently while preserving tracked resource versions.
• File Path & Sanitization Fixes (#1719, #1721, #1594): Preserved leading, trailing, and embedded spaces in Python SDK file paths, prevented double-decoding of literal percent escapes in the Python runtime, and fixed path sanitization when sandbox roots are accessed through symlinked directory aliases.

Reinforcement Learning SDK (agent-sandbox-rl)

• Run Isolation & Safe Concurrency (#1737): Introduced run-scoped teardown selectors and FleetConfig.run_isolation modes ("names" and "namespace"), preventing concurrent training runs in shared namespaces from accidentally resizing, deleting, or stalling on each other's warm pools and templates. Added fail-fast handling on pool deletion and conditional resource writes.

Security & Governance

• Hardened Command Governance Example (#1690): Upgraded governed_run.py to protect against command injection, shell chaining (;, &&, ||, |, &), command substitution ($(...) and backticks), GNU-style option abbreviations, and execution wrappers (sudo, env, xargs, timeout, exec).

Documentation & Tooling

• Comprehensive Configuration & TLS Docs (#1653, #1689): Documented all 34 controller flags in the configuration reference, published end-to-end instructions for enabling secure TLS metrics serving on port 8443, and added HTTP/2 and HTTP/1.1 ALPN negotiation support.
• Runtime API Specification (#1645): Published official runtime API reference documentation for sandboxd contracts, endpoints, and transport policies.
• Developer Tooling & CI Enhancements (#1616, #1696, #1699, #1738, #1741): Enforced LF line endings repository-wide via .gitattributes, made E2E port-forward helpers race-free, prevented duplicate flake reports for closed issues, integrated cluster-free framework tests into the unit test suite, and improved GCP kOps benchmark validation timeouts.

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

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

Python SDK

pip install k8s-agent-sandbox==1.0.4

Contributors

We extend our sincere thanks to all contributors to this release:
@1fanwang, @Flandern1211, @HasonoCell, @Pepper-rice, @Sean-790761, @XixianWasTaken, @aditya-shantanu, @alanhuangch, @aojea, @dependabot, @briankhoi, @dongjiang1989, @esposem, @janetkuo, @karimad, @khirotaka, @lunarwhite, @niting, @pauldotyu, @tomergee, @vincent0426, @vvoronko, @yujunz, @yuzhiquan

New Contributors

• @niting made their first contribution in #1612
• @Flandern1211 made their first contribution in #1438
• @Sean-790761 made their first contribution in #1630
• @pauldotyu made their first contribution in #1682
• @1fanwang made their first contribution in #1721
• @yujunz made their first contribution in #1594
• @XixianWasTaken made their first contribution in #1699

Full Changelog: v1.0.3...v1.0.4

🚀 Announcing Agent Sandbox v1.0.3!

We're excited to announce the release of Agent Sandbox v1.0.3! This release introduces configurable TLS controls for the controller and router, resolves process group leaks in sandboxd, optimizes namespace deletion handling, enhances Python SDK type safety with PEP 561 support, extended pluggable agent toolsets & in-cluster Agent Client Protocol (ACP) server, and brings extensive new blueprints for enterprise fleet management, execution-scoped credentials, and advanced network policies.

Key Highlights

Core Controller & Runtime Stability

• Process Group Cleanup in sandboxd (#1379): Replaced default process cancellation with process group termination (-PGID), preventing orphan descendant processes from leaking when clients disconnect from commands executed in sandboxes.
• Namespace Deletion Requeue Optimization (#1617): Improved Sandbox controller reconciliation during namespace termination by intercepting NamespaceTerminatingCause errors and requeuing without logging errors or triggering exponential backoff storms during bulk deletions.
• Configurable TLS Profiles (#1595): Added CLI flags, environment variables, and configuration options (--tls-min-version, --tls-cipher-suites, --metrics-secure-serving, and --metrics-cert-dir) to customize TLS versions and cipher suites for the controller metrics server and sandbox-router.

Python SDK & Client Tooling

• Comprehensive Type Annotations (#794): Added strict typing annotations across the k8s-agent-sandbox client package, bundled the PEP 561 py.typed marker, and improved null-safety and error handling across async connectors and snapshot utilities.

Enterprise Blueprints & Reference Architectures

• OpenClaw Enterprise Fleet Blueprint (#1652, #1656): Added openclaw-fleet-gke, an enterprise-grade reference architecture demonstrating warm-pool provisioning, per-employee persistent Filestore storage, out-of-band config injection, online dynamic PVC expansion, and Gateway API routing.
• Execution-Scoped Credentials (#1644): Added examples/containarium-execution-scoped-token demonstrating short-lived, per-execution credential injection via ProcessConfig.env_vars with instant revocation upon process exit and network isolation via Cilium NetworkPolicy.
• Cluster-Wide Egress Control (#1646): Added examples/network-policy-api-sandbox, showcasing multi-tier egress management and domain name filtering using the SIG Network ClusterNetworkPolicy API with kube-network-policies.
• Pluggable Agent Toolsets & In-Cluster ACP Server (#1457, #1586): Extended sandboxed-tools with modular toolsets (including Gemini CLI parity in Go) and an in-cluster Agent Client Protocol (ACP) JSON-RPC server with client permission prompts.

Testing, Scalability & Operations

• Scalability & CI Test Hardening (#1624, #1626, #1623, #1546, #1551): Enhanced scalability test presubmits with JUnit XML metric-gate outputs, startup readiness polling, retry loops for cluster provisioning, and refined flake classification to prevent false-alarm infra failures.
• Example Test Coverage (#1608): Added unit test suites covering security-critical logic, path traversal guards, allowlists, and mutating webhook JSON patch generators across example workloads.
• Performance Tuning & Lifecycle Guidance (#1359, #1587): Published a performance tuning guide for high-throughput deployments (docs/performance-tuning.md), clarified restartPolicy interactions with sandbox TTL cleanups, and updated controller metrics references with auto-generation tooling (#1444).

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

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

Python SDK

pip install k8s-agent-sandbox==1.0.3

Contributors

We extend our sincere thanks to all contributors to this release:
@aditya-shantanu, @alexatakvelon, @aojea, @app/dependabot, @dongjiang1989, @esposem, @hsinhoyeh, @janetkuo, @justinsb, @lunarwhite, @sanjay7178, @vvoronko

New Contributors

• @sanjay7178 made their first contribution in #794
• @aojea made their first contribution in #1646

Full Changelog: v1.0.2...v1.0.3

🚀 Announcing Agent Sandbox v1.0.2!

We're excited to announce the release of Agent Sandbox v1.0.2! This release brings significant improvements across the sandbox router, SDKs, and reinforcement learning (RL) integrations. Key enhancements include Ed25519-based scoped-token v2 verification for fine-grained authorization, direct in-cluster connectivity options for the Go SDK, improved connection resiliency for the Python SDK, warm pool adoption and OpenHands integration in the RL framework, and controller observability metrics via controller-runtime v0.25.0.

⚠️ Breaking Changes / Action Required

• Sandbox Router Authorizer Interface Update (authz.Authorizer) (#1497): The public Authorizer interface signature in Go sandbox-router has changed from taking separate (namespace, name) string arguments to accepting a single authz.AuthorizationTarget struct. Custom Authorizer implementations must update their Authorize method to inspect the fields of authz.AuthorizationTarget.
• Sandbox Router Namespace Change (#1537): The Go sandbox-router manifests in sandbox-router/deploy/ have moved from the default namespace to agent-sandbox-system to enforce privilege separation and align with SDK defaults and NetworkPolicy rules. If you deploy raw manifests, ensure your manifests and scripts point to agent-sandbox-system.

Key Highlights

Sandbox Router & Security

• Scoped-Token v2 Target Binding (#1497): Added Ed25519 scoped-token v2 verification binding tokens to Sandbox UID, port, HTTP method, and exact upstream path. Enables multi-key rotation and exclusive cutoff timestamps (--authz-scoped-token-v1-accept-until) for seamless migration from legacy HMAC v1 tokens.
• Namespace & NetworkPolicy Alignment (#1537, #1539): Deployed the router to agent-sandbox-system and added the app: sandbox-router label to router deployment manifests, ensuring compatibility with the controller's secure-by-default SandboxTemplate NetworkPolicy.
• OLM Operator Router Integration (#1425, #1477): Added the sandbox-router deployment, proxy service, and health checks directly to the Operator Lifecycle Manager (OLM) bundle.

Go & Python SDKs

• Direct In-Cluster Connectivity in Go SDK (#1576): Added Options.Connectivity (ConnectivityInClusterService and ConnectivityInClusterPodIP), enabling workloads inside the cluster to connect directly to sandbox pods via headless service DNS or Pod IP without proxying through the API server or router.
• Python SDK Connection Resilience on 4xx (#1574): Fixed an issue where HTTP 4xx responses (such as file not found) caused the connector to tear down the port-forward tunnel and clear the cached Pod IP. Tunnel teardown and routing invalidations are now reserved for transport failures and 5xx errors.
• Async Client Concurrency & Flake Hardening (#1385, #1553): Added comprehensive E2E tests for AsyncSandboxClient validating concurrent execution and non-blocking event loops, with interval-overlap assertions resilient to sub-second warm-pool creation speeds.

Reinforcement Learning (RL) & Fleet Integrations

• Warm Pool Adoption (#1556): Added FleetConfig.adopt_existing=True and FleetConfig.pool_name_format to the RL SDK, allowing training harnesses to discover and adopt pre-provisioned warm pools by container image rather than creating redundant pools.
• OpenHands Fleet Adapter & Fan-Out (#1503): Introduced OpenHands integration shims (make_fleet_workspace, make_handle_workspace), advisory attach-time version skew detection, and scalable multi-agent example workflows (examples/run_openhands_fleet.py).
• RL Quickstart Standardization (#1549): Updated setup steps to configure and provision workloads consistently in the agent-sandbox-rl namespace.

Controller Observability, Performance & MCP Server

• controller-runtime v0.25.0 & REST Client Metrics (#1547): Upgraded controller-runtime to v0.25.0 and enabled client-go REST client metrics (rest_client_requests_total, rest_client_request_duration_seconds, rate-limiting, and retry counters) by default.
• MCP Server Probes & Skills (#1339, #1534): Added /healthz (liveness) and /readyz (readiness) probe endpoints to the Model Context Protocol (MCP) server container and documented client skills for MCP tools.
• Golden-Snapshot Warm Pools on GKE (#1522): Added an end-to-end example demonstrating golden-image warm pools restored directly from GKE Pod Snapshots.
• High-Throughput Tuning & Diagnostics (#1593, #1552, #1555): Documented flags for connection sharding, write optimization, and refill rate limiting; tuned stress test networking defaults (nodeCIDRMaskSize=23); and added serial port log capture during benchmark cluster validation failures.

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

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

Python SDK

pip install k8s-agent-sandbox==1.0.2

Contributors

We extend our sincere thanks to all contributors to this release:
@aditya-shantanu, @dongjiang1989, @drogovozDP, @esposem, @hyperb1iss, @janetkuo, @justinsb, @leomcl, @nankeen, @tomergee, @vicentefb, @vincent0426, @wjun29, @yuzhiquan

New Contributors

• @hyperb1iss made their first contribution in #1497
• @leomcl made their first contribution in #1463
• @nankeen made their first contribution in #1576

Full Changelog: v1.0.1...v1.0.2

🚀 Announcing Agent Sandbox v1.0.1!

We're excited to announce the release of Agent Sandbox v1.0.1! This release introduces the foundational TypeScript SDK for sandbox resource management, adds a first-class OpenHands agent workspace integration, hardens SDK lifecycle teardown and pod resolution, refines testing benchmarks, and resolves key bugs across documentation, metrics, and examples.

Key Highlights

SDKs & Integrations

• TypeScript SDK Resource Layer (#976): Introduced the initial TypeScript client (agentic-sandbox-client) under clients/typescript/ for managing SandboxClaim lifecycles, watching sandbox readiness, and optional OpenTelemetry tracing.
• OpenHands Workspace Integration (#1488): Added AgentSandboxWorkspace, enabling the OpenHands agent SDK to bind to pre-warmed Agent Sandbox pods with sub-second startup latency, supporting direct pod IP access, sandbox-router mode, and pool-level authentication.
• Python SDK atexit Cleanup Fix (#1512): Switched AsyncSandboxClient process exit cleanup to a synchronous client to resolve an interpreter shutdown race condition that caused sandbox resource leaks.
• SDK Pod Name Fallback (#1467): Ensured Go and Python SDKs correctly fall back to the Sandbox name when the legacy agents.x-k8s.io/pod-name annotation is present but empty.

Testing & Reliability

• Runtime Burst Benchmarking Improvements (#1485): Refactored TestRuntimeClassBurstRecovery to provision fresh warm pools per iteration, eliminating stale controller expectations and classifying claim latency into clear Green (≤1s), Grey (>1s), and Cold zones.
• Accurate Metric Documentation (#1443): Corrected Prometheus metric HELP strings and label documentation across internal metrics collectors to match controller behavior.

Examples & Documentation

• Sandboxd Quickstart & Topologies (#1416): Added an end-to-end Go SDK quickstart for sandboxd along with dedicated runtime container and binary-injection deployment topology configurations.
• SandboxClaim Label-Domain Allowlist Docs (#1530): Documented the SandboxClaim.spec.additionalPodMetadata.labels allowlist and improved controller rejection error messages to reference the agent-sandbox-config ConfigMap.
• Command Governance Policy Example (#1456): Added an example demonstrating client-side command classification and pre-execution filtering before dispatching commands to a running sandbox.
• Sandboxed Tools Refactoring (#1482): Extracted the interactive sandboxed-tools agent loop into an importable pkg/agent package with a dedicated CLI.
• Gateway API Examples(#1331, #1471): Expanded Gateway API documentation beyond GKE to include Istio and other providers, and audited manifests, schemas, and instructions across the examples repository.

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

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

Python SDK

pip install k8s-agent-sandbox==1.0.1

Contributors

We extend our sincere thanks to all contributors to this release:
@Oneimu, @adibmbrk, @aditya-shantanu, @app/dependabot, @briankhoi, @dongjiang1989, @esposem, @hchenxa, @janetkuo, @justinsb, @karimad, @khirotaka, @kincoy, @lunarwhite, @pujitha24, @sairajp-rewind, @tomergee, @vvoronko

New Contributors

• @adibmbrk made their first contribution in #1486
• @khirotaka made their first contribution in #976

Full Changelog: v1.0.0...v1.0.1

🚀 Announcing Agent Sandbox v1.0.0!

We're excited to announce the release of Agent Sandbox v1.0.0! This major milestone marks the transition of the core and extension APIs to v1beta1, removing legacy v1alpha1 support and webhook conversion infrastructure. This release also introduces browser-facing path-based routing with session-cookie authentication in sandbox-router, support for the next-generation sandboxd runtime across client SDKs, official integrations with NVIDIA NeMo Gym and Gymnasium for Reinforcement Learning (RL), streaming uploads in the Go SDK, and significant performance and scaling enhancements.

⚠️ Breaking Changes / Action Required

• Removal of v1alpha1 APIs & Conversion Webhooks (#1470):
  • The deprecated v1alpha1 API version has been completely removed across agents.x-k8s.io and extensions.agents.x-k8s.io. All CRDs now exclusively serve v1beta1.
  • The conversion webhook server, TLS certificates, and manager webhook CLI flags (--webhook-*) have been removed.
  • Performance & Reliability Improvements: Eliminating the conversion webhook removes extraneous API server conversion round-trips and CPU load during informer cache syncs (which previously occurred even when only v1beta1 was requested). It also removes webhook latency on writes and eliminates webhook failure modes (e.g., certificate rotation and private-cluster webhook firewall blocks).
  • Action Required (Upgrade Procedure for All Users; Fresh Installs Can Skip): Direct upgrades from < v0.5.0 to v1.0.0 are not supported. Existing clusters must follow this 4-step sequence:
    1. Upgrade to v0.5.x & run storage migration: If running < v0.5.0, upgrade to v0.5.2+ first. Rewrite all stored resources to v1beta1 and prune v1alpha1 from storedVersions following the v0.5.x API Migration Guide.
    2. Verify stored versions: Confirm that all four CRDs report only v1beta1 in status.storedVersions. If v1alpha1 remains, the Kubernetes API server will reject the upgrade:

       kubectl get crd sandboxes.agents.x-k8s.io \
         sandboxclaims.extensions.agents.x-k8s.io \
         sandboxtemplates.extensions.agents.x-k8s.io \
         sandboxwarmpools.extensions.agents.x-k8s.io \
         -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.status.storedVersions}{"\n"}{end}'

    3. Upgrade to v1.0.0: Follow the v1.0.0 API Migration Guide. Helm users must run kubectl apply -f helm/crds/ before helm upgrade (the webhookServiceName chart value was removed). OLM users should approve the v1.0.0 InstallPlan. (Note: The InstallPlan will fail if Step 2 was not completed).
    4. Post-Upgrade Cleanup: Remove orphaned webhook resources by running:

       kubectl delete -n agent-sandbox-system \
         svc/agent-sandbox-webhook-service \
         secret/agent-sandbox-webhook-certs \
         role/agent-sandbox-controller \
         rolebinding/agent-sandbox-controller \
         --ignore-not-found

• Removal of pod-name Annotation Writing (#1417):
  • Controllers no longer write the agents.x-k8s.io/pod-name annotation to newly created Sandbox resources, as Sandbox names and backing Pod names are guaranteed to be identical.
  • Performance Improvement: Eliminating the separate metadata patch alongside status updates removes an extra reconciliation loop per Sandbox. In benchmarks, this reduced average Sandbox reconcile latency by 55% (2.2x speedup) and eliminated tens of thousands of redundant API server PATCH requests under load.
  • Action Required: Update any external scripts, monitoring, or tooling that reads metadata.annotations["agents.x-k8s.io/pod-name"] to use .metadata.name directly. Existing resources with the legacy annotation will still be read until cleared.
• SDK FileEntry Schema Update (#1347):
  • In the Go SDK, FileEntry.ModTime is now time.Time (previously float64), and a Mode field has been added.
  • In the Python SDK, FileEntry.mod_time has been renamed to FileEntry.modified (datetime), and a mode field has been added.

Key Highlights

Core Controller & Lifecycle Management

• Instant Claim Reconciliation on Template Creation (#1315): Creating a previously missing SandboxTemplate now triggers immediate reconciliation for waiting SandboxClaim resources instead of waiting for fallback timer intervals.
• Accurate Claim Generation Tracking (#1317): Fixed SandboxClaim Ready conditions to report the claim's own observedGeneration rather than the backing Sandbox's generation.
• SandboxClaim UID Label Propagation (#1423): Fixed an issue where agents.x-k8s.io/claim-uid labels were filtered out before propagating to backing Pods for claim-owned sandboxes.
• Expose serviceFQDN on SandboxClaims (#1325): The bound Sandbox's in-cluster DNS service name is now surfaced directly on SandboxClaim.status.sandbox.serviceFQDN.
• Burst Scaling & Claim Latency Optimizations (#1454, #1417): Reduced p99 claim startup latency during large burst allocations by eliminating redundant reconcile writes and tuning warm candidate poll intervals from 500ms to 100ms.

Sandbox Router & Networking

• Browser Path-Based Routing (#1413, #1441): Added an opt-in --path-routing-prefix mode, enabling browser sessions, iframes, and WebSockets (e.g., web IDE terminals or dev server HMR clients) to route traffic using URL paths (<prefix>/<namespace>/<id>/<port>/...) without requiring custom HTTP headers.
• Browser-Session Authentication & CSWSH Protection (#1446): Added session cookie bootstrapping via query parameter exchanges, SameSite configuration, and mandatory Origin validation (--authz-cookie-allowed-origins) to guard against Cross-Site WebSocket Hijacking (CSWSH). Added --authz-trust-forwarded-proto for deployments behind TLS-terminating ingress proxies.
• Official Go Router Promotion (#1448, #1415): Standardized documentation around the high-performance Go sandbox-router and added sandbox-router-go to official image promotion pipelines.

SDKs & Runtime Support

• sandboxd Daemon Integration (#1347): Added opt-in support across Go and Python SDKs for the unified sandboxd runtime (REST filesystem on :8080 + gRPC ProcessService on :9090) via pod port-forwarding. Updated sandboxd to bind 0.0.0.0 by default.
• Streaming File Uploads in Go SDK (#1419): Added Files.WriteReader and Sandbox.WriteReader to stream data from io.Reader without buffering entire payloads in memory.
• Environment Variable Injection (#1003): Go and Python SDKs now support injecting runtime environment variables into SandboxClaim specifications during creation.
• Non-Idempotent POST Retry Prevention (#1353): Fixed an issue in the Python SDK where failed POST /execute commands were retried on 5xx errors, preventing accidental duplicate execution of shell commands.
• Disable Pod IP Routing Option (#932): Added DisablePodIPRouting to Go SDK options for environments where direct pod-to-pod routing is restricted by network policies or service meshes.
• Configurable Base Directory in Python Runtime (#1408): Added SANDBOX_BASE_DIR environment variable support (default /app) to allow sandboxes to run with readOnlyRootFilesystem: true.

Integrations & Ecosystem

• NVIDIA NeMo Gym Integration (#1374): Added clients/integrations/nemo-gym (nemo-gym-k8s-agent-sandbox), registering Agent Sandbox warm pools as an agent_sandbox provider for NVIDIA NeMo Gym RL training environments.
• Gymnasium Integration (#1350): Added clients/integrations/gymnasium offering a standard Gymnasium environment interface with configurable reward and termination hooks.
• MCP Server get_sandbox_status Tool (#1362): Added a tool to the Model Context Protocol (MCP) server for querying sandbox readiness and status.
• Sandboxed Tools Enhancements (#1428, #1459): Added a configurable per-tool execution timeout (-tool-timeout) and introduced a deterministic fake LLM (fake-eliza) for testing agent tool pipelines offline.
• Agent Client Protocol (ACP) Example (#1450): Added a lightweight client implementation for testing ACP interactions.

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

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

Python SDK

pip install k8s-agent-sandbox==1.0.0

Contributors

We extend our sincere thanks to all contributors to this release:
@HasonoCell, @Oneimu, @aditya-shantanu, @alanhuangch, @app/dependabot, @briankhoi, @daktari, @dlanov, @drogovozDP, @esposem, @ferponse, @futuretea, @gruebel, @janetkuo, @justinsb, @lunarwhite, @moficodes, @pbxqdown, @sairajp-rewind, @shrutiyam-glitch, @tanish-wisdom, @tomergee, @vicentefb, @wjun29

New Contributors

• @futuretea made their first contribution in #1317
• @daktari made their first contribution in #1408
• @ferponse made their first contri...

🚀 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

🚀 Announcing Agent Sandbox v0.5.5!

We're excited to announce the release of Agent Sandbox v0.5.5! This release brings significant enhancements to core stability, performance, new examples, and documentation, along with important updates to development workflows and dependency management.

⚠️ Breaking Changes / Action Required

• Python SDK Minimum Version (#1324): The minimum supported Python version for k8s-agent-sandbox and the deepagents and mcp-server integration packages has been raised from 3.10 to 3.11. Users on Python 3.10 must upgrade to Python 3.11 or newer before adopting this release, as pip will refuse to install newer versions of these packages on Python 3.10. Python 3.10 reaches end of life on 2026-10-31.

Key Highlights

Core Stability & Lifecycle Management

• Stale SandboxClaim Assignment Fix (#1129): Addressed issues where stale SandboxClaim assignments could interfere with reconciliation, ensuring stable ownership and continuous operation.
• Optimized Metadata Writes (#1252): Introduced an opt-in mechanism to coalesce recoverable metadata-only writes via RequeueAfter deferral, reducing API server load during bursts and improving overall performance (--sandbox-write-behind-window controller flag).
• Profiling Endpoint Stability (#1305): Implemented protection against concurrent fgprof profile requests, ensuring the profiling endpoint remains stable and returns a 500 error for subsequent concurrent requests.
• Warm Pool Refill Shaping (#1251): Added replenish-delay and max-refill-rate flags to the SandboxWarmPool controller, allowing for more controlled and throttled refilling after sandboxes are claimed.

Examples & Documentation

• nono Sandbox Example (#1333): Introduced a new example demonstrating enhanced security with the nono agent security runtime within Agent Sandbox, showcasing filesystem isolation, scoped egress, and tamper-evident audit trails.
• AWS IRSA Local Simulation (#1340): Added an example for simulating AWS IRSA locally with LocalStack, enabling validation of sandbox pod credential-loading paths without a real AWS account.
• Kata on AKS Examples (#1312): Provided new examples for running Agent Sandbox with Kata Containers hardware-virtualized isolation on Azure Kubernetes Service (AKS), including a minimal kata-aks-sandbox and an openclaw-kata-aks-sandbox.
• RL Example Update (#1311): Refreshes the agent-sandbox-rl example's controller tuning guidance for controller v0.5.4+, recommending higher concurrent workers due to fixes.
• Multi-Runtime Benchmark Study (#1279): Expanded the GKE Memory Swap example into a comprehensive multi-runtime performance study across gVisor, Kata Containers (kata-qemu), and Kata Containers (kata-clh).
• High-Density Benchmark & Node Tuning Docs (#1334): Added high-density benchmark results and node tuning instructions for GKE swap configurations.

Performance & Benchmarking

• Router Resolution Benchmarks (#1246): Added benchmarks for the router's upstream resolution paths (UID cache, namespace/name cache, DNS fallback), highlighting significant performance differences.
• Python Sandbox Density Benchmark (#1342): Introduced a high-density Python workload benchmark suite and automated runner to evaluate memory density scalability and swap offloading characteristics.
• Enhanced Performance Test Validation (#1358): Improved the KWOK scalability presubmit test by extracting a reusable metrics scraper and adding automated latency threshold validation.
• Client to Claim Ready Latency Metric (#565): Added an end-to-end metric (agent_sandbox_client_claim_startup_latency_ms) to measure user-perceived latency from client request initiation to sandbox readiness.

Build & CI

• Python Router Path Preservation (#1158): Fixed an issue where the Python sandbox-router would incorrectly decode percent-encoded dot segments in paths.
• Automated Deployment Dependency Install (#1189): Ensured deploy-to-kube automatically installs necessary Python dependencies, preventing installation failures.
• Expanded CI Coverage: Integrated Prow presubmit unit tests for several examples (#1273), wired hermes-agent and policy/vap tests into CI (#1349), and added Prow presubmits for OLM (#1303).
• OLM Bundle Update (#1330): Updated the OLM bundle to version 0.5.4.
• Linting Enhancements (#1320): Added goheader and intrange linters to enforce code style and updated existing code to comply.
• Image Loading for Kind Clusters (#1356): Fixed an issue where extra image tags were ignored when loading images into Kind clusters via push-images.

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

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

Python SDK

pip install k8s-agent-sandbox==0.5.5

Contributors

We extend our sincere thanks to all contributors to this release:
@Axpz, @lubingtan, @Oneimu, @XbaoWu, @YahiaBadr, @aditya-shantanu, @aleks-stefanovic, @alexatakvelon, @dependabot, @dongjiang1989, @esposem, @hchenxa, @igooch, @karimad, @lukehinds, @michaelxu2288, @ngopalak-redhat, @oceanxie1, @tom1299, @tomergee, @tomsen02, @vincent0426, @volatilemolotov, @vvoronko

New Contributors

• @michaelxu2288 made their first contribution in #1312
• @oceanxie1 made their first contribution in #1279
• @tomsen02 made their first contribution in #1300
• @karimad made their first contribution in #1340
• @lukehinds made their first contribution in #1333
• @Axpz made their first contribution in #1338
• @ngopalak-redhat made their first contribution in #1336
• @vincent0426 made their first contribution in #1129
• @hchenxa made their first contribution in #1189

Full Changelog: v0.5.4...v0.5.5

🚀 Announcing Agent Sandbox v0.5.4!

We're excited to announce the release of Agent Sandbox v0.5.4! This release brings significant improvements in core stability, performance, and introduces powerful new features for the Python SDK and router. Key areas of focus include hardening sandbox lifecycle management, optimizing API server interactions, and expanding integration capabilities.

⚠️ Breaking Changes / Action Required

• Sandbox Suspended condition changed to comply with Kubernetes convention (#1150):
  • The Suspended status condition is now always present on Sandbox resources after initial reconciliation. Clients should inspect its boolean status value (e.g., status: "False") rather than checking for its presence or absence.
  • The legacy PodNotTerminated reason string is deprecated in favor of PodTerminating. Update any client-side logic that explicitly checks for PodNotTerminated.

Key Highlights

Core Stability & Lifecycle Management

• Persistent Suspended Conditions for Sandbox (#1150): The Sandbox Suspended status condition is now consistently present and transitions its status (True or False) instead of appearing or disappearing, enabling standard kubectl wait commands and preserving history.
• Robust Adoption Assignment & Optimistic Locks (#1277): Prevents assignment flips, orphaned sandboxes, and duplicate adoptions under load by applying optimistic locks on adoption patches and resolving conflicts against authoritative reads. Benign adoption contention now surfaces as an AdoptionConflict Ready reason.
• Optimistic-Locked Status Writes (#1256): Eliminates duplicate startup-latency histogram observations and stale status overwrites by using optimistic-locked status patches, ensuring metrics are recorded exactly once and status reflects the authoritative state.
• Reduced Redundant Reconciles & Status Patching (#1254): Improves controller efficiency by using non-optimistic merge patches for Sandbox status writes (eliminating 409 conflicts) and adding predicates to only reconcile owning SandboxClaim on relevant Sandbox field changes.
• Warm Pool Over-Creation Mitigations (#1266): Prevents SandboxWarmPool from over-creating replicas due to informer-cache lag. Sandbox creations are now gated by a ReplicaSet-style expectations tracker, and terminating sandboxes count against the target. Introduces WarmPoolNotProgressing events for capacity shortfalls.
• Efficient Pod Cache Transformation (#1272): Strips Pod finalizers from the informer cache, reducing memory usage and event decoding costs as they are not used by Agent Sandbox controllers.
• Semantic Comparison for K8s API Objects (#1278): Replaces reflect.DeepEqual with apiequality.Semantic.DeepEqual for Kubernetes API object comparisons, preventing unnecessary status updates and reconciliation due to non-semantic differences.
• Stricter API Group Verification (#945): Enhances warm-pool and sandbox ownership/identity validation by consistently verifying API Group in addition to Kind for controller and owner references.
• Improved RBAC for Events (#1080): Grants core API group ("") events permission for the leader election event recorder, fixing events is forbidden errors.
• Exposed Sandbox Service Ports (#1258): Generated headless Sandbox Services now automatically include ports derived from declared container ports, improving compatibility with service meshes like Istio.
• Accurate Startup Latency Metrics (#1087): Fixes SandboxClaim controller startup latency histograms to record exactly once per claim lifetime, preventing overcounts due to readiness probe flapping.
• Go Client Handle Registry Race Fix (#998): Prevents leaking orphaned sandbox handles in the Go client by making GetSandbox/CreateSandbox race-safe and ensuring proper disconnection of redundant handles.
• Enhanced Adoption Conflict Resolution (#1304): Improves adoption handling for optimistic-lock contention and refines user-facing conflict messaging to avoid exposing low-level internal errors.

Performance & Scalability

• API Connection Sharding (#1240): Introduces opt-in controller flags (--separate-watch-connection and --api-connections) to use dedicated HTTP/2 connections for informer watches and shard non-watch traffic, significantly improving API concurrency and reducing watch starvation.
• Optimized Metadata Writes (#1250): Implements direct merge patches for hot-path metadata writes on SandboxClaim controllers, reducing CPU and memory allocations by building targeted patch payloads instead of full-object diffs.
• Stress Test Configuration Improvements (#1283): Increases Kubelet API QPS limits and caps Kubelet event spam during stress tests, allowing for higher churn rates and reducing API server load.
• KWOK Scalability Presubmit Test (#1269): Adds a fast, lightweight presubmit test using KWOK (Kubernetes WithOut Kubelet) to automatically benchmark performance and catch scalability regressions on every Pull Request.
• Optimized Pod Counting for Circuit Breaker (#1232): The circuit breaker now efficiently counts pods using limit=1 and remainingItemCount to reduce API server and memory load at large scales.
• Infrastructure Tuning for Stress Tests (#1275): Configures benchmark worker node root volumes on pd-ssd and control plane nodes on c3-standard-22, addressing disk I/O and control plane CPU bottlenecks for improved stress test performance.
• Beta API Serving Optimization (#1234): Stress tests now serve only the beta Sandbox APIs to reduce conversion traffic and improve API server efficiency.

Router Enhancements

• Scoped-Token Authorizer (#1243): Introduces a new --authz-mode=scoped-token for sandbox-router, allowing local verification of signed tokens bound to a single (namespace, name) without requiring a kube-apiserver round-trip.
• Improved Warm-Pool Routing (#1239): sandbox-router now routes requests carrying X-Sandbox-Id via the Pod-IP cache's namespace/name index, fixing 502 (NXDOMAIN) errors for warm-pool sandboxes without a dedicated Service.

SDK & Integrations

• Agent Sandbox Recycling (Python SDK) (#1232): Introduces sandbox recycling (reuse_git_restore_sandbox) in the agent-sandbox-rl SDK, allowing reuse of claimed sandboxes across tasks (e.g., RL rollouts) to reduce claim latency and API load. Includes contamination guards, persistent exec sessions, and warm-pool over-creation mitigations.
• Optimized Python SDK wait_for_claim_ready (#1241): The Python SDK's wait_for_claim_ready() now uses a single, watch-based approach on the claim itself, significantly reducing latency compared to the previous two-sequential-watch method. Also, faster dev port-forward polling.
• AsyncSandbox Functionality Alignment (#999): Aligns AsyncSandbox functionality with Sandbox in the Python SDK, ensuring consistent behavior and expanding API capabilities.
• Langchain-Deepagents Integration (#1144): Adds a new Python package for integrating with Langchain-Deepagents, enabling sandbox lifecycle management, command execution, and file transfer.
• MCP Server Introduction (#1141): Adds an Agent Sandbox MCP (Multi-Cluster Proxy) server with basic implementation for listing sandboxes and tools for create/delete, command execution, and file operations.

Documentation & Examples

• Expanded Security Threat Model (#1299): The security threat model documentation has been expanded to include architectural overview, trust boundaries, threat analysis with mitigations, and SandboxTemplate enforcement capabilities.
• Clarified Repository Scope (#1298): The README.md now explicitly clarifies that Agent Sandbox is a sandbox orchestrator, delegating low-level container isolation to secure runtimes like gVisor or Kata Containers.
• Hermes Agents-as-a-Service Example (#1271): Adds a comprehensive example demonstrating the multi-user "agents as a service" platform pattern, featuring warm-pool claims, suspend/resume for cost management, PVC state survival, and a minimal gateway.
• Firecracker Sandbox Example (#1238): Introduces an example demonstrating how to run Agent Sandboxes on Kata Containers with the Firecracker VMM, providing microVM isolation and fast boot times.
• APF Insulation Overlay Example (#1270): Adds an opt-in API Priority and Fairness (APF) insulation overlay and operator guide to prioritize critical controller API traffic and isolate bulk workloads.
• Runtime-Class-Aware Benchmarks (#1262): Adds e2e tests and benchmarks for warm pool subsystem across runc, gVisor, and Kata runtimes, measuring cold start latency, warm pool claim speed, and burst recovery.
• Enhanced Stress Testing Phases (#1287): Refactors tests to include a phase for testing with large numbers of pods (e.g., up to 80% capacity) and adds new capacity-related test assertions.
• Improved Stress Test Reports (#1284): Enhances stress test reports with a "Limiter Regime by Component" table to identify client-go rate limiter behavior (queueing vs. pacing) and estimate implied QPS limits.

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

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

Python SDK

pip install k8s-agen...