🚀 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 contribution in #1413
@tanish-wisdom made their first contribution in #1423
@dlanov made their first contribution in #1428
@wjun29 made their first contribution in #1362
@pbxqdown made their first contribution in #1353
@briankhoi made their first contribution in #1417

Full Changelog: v0.5.6...v1.0.0

Navigation Menu

Uh oh!

v1.0.0

Choose a tag to compare

Sorry, something went wrong.

Sorry, something went wrong.

Uh oh!

No results found

🚀 Announcing Agent Sandbox v1.0.0!

⚠️ Breaking Changes / Action Required

Key Highlights

Core Controller & Lifecycle Management

Sandbox Router & Networking

SDKs & Runtime Support

Integrations & Ecosystem

Installation

Standard Install (Core + Extensions)

Selective Install

Python SDK

Contributors

New Contributors

Contributors

Uh oh!