v1.0.0

# 🚀 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](https://github.com/kubernetes-sigs/agent-sandbox/blob/v0.5.6/docs/api-migration-guide.md).
    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:
       ```bash
       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](https://github.com/kubernetes-sigs/agent-sandbox/blob/main/docs/api-migration-guide.md). 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:
       ```bash
       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](https://github.com/kubernetes-sigs/agent-sandbox/pull/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):
```bash
kubectl apply -f https://github.com/kubernetes-sigs/agent-sandbox/releases/download/v1.0.0/sandbox-with-extensions.yaml
```

#### Selective Install
Install components separately:
```bash
# 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
```bash
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 https://github.com/kubernetes-sigs/agent-sandbox/pull/1317
* @daktari made their first contribution in https://github.com/kubernetes-sigs/agent-sandbox/pull/1408
* @ferponse made their first contribution in https://github.com/kubernetes-sigs/agent-sandbox/pull/1413
* @tanish-wisdom made their first contribution in https://github.com/kubernetes-sigs/agent-sandbox/pull/1423
* @dlanov made their first contribution in https://github.com/kubernetes-sigs/agent-sandbox/pull/1428
* @wjun29 made their first contribution in https://github.com/kubernetes-sigs/agent-sandbox/pull/1362
* @pbxqdown made their first contribution in https://github.com/kubernetes-sigs/agent-sandbox/pull/1353
* @briankhoi made their first contribution in https://github.com/kubernetes-sigs/agent-sandbox/pull/1417

**Full Changelog**: https://github.com/kubernetes-sigs/agent-sandbox/compare/v0.5.6...v1.0.0