github kubernetes-sigs/agent-sandbox v1.0.12

one hour ago

🚀 Announcing Agent Sandbox v1.0.12!

We're excited to announce the release of Agent Sandbox v1.0.12! Highlights: suspend/resume, archive extraction, and claim lifecycle options across the Go, Python, and TypeScript SDKs; single-path files.stat() in sandboxd and the Python and TypeScript SDKs; sandbox.watcher.watch() and router-port-forward in the TypeScript SDK; per-pool readiness grace periods on SandboxWarmPool; sandbox-scoped v2 tokens in sandbox-router; improved sandboxd REST error handling and pipe cleanup; and a new CI runner sandbox example.


Highlights

Core & Extension Controllers

  • Per-pool readiness grace period (SandboxWarmPool) (#2136): Added spec.readinessGracePeriodSeconds (optional, minimum 30) to SandboxWarmPool to override the controller-level --sandbox-warm-pool-readiness-grace-period flag and agent-sandbox-config ConfigMap (built-in default 5m) in either direction. Editing the field does not mark existing sandboxes stale. Updates the SandboxWarmPool CRD schema (Helm users should apply the updated CRD before setting this field) and bumps the Helm chart to 0.1.5.

Sandbox Router

  • Sandbox-scoped v2 authorization tokens (#2258): Added authz.MintScopedTokenV2Sandbox to mint Ed25519 v2 tokens bound to (namespace, name, uid) that authorize all ports, methods, and paths for that Sandbox until expiry. Upgrade all sandbox-router replicas before minting sandbox-scoped v2 tokens; older replicas reject them with 403.

sandboxd

  • Single-path file metadata (?stat=true) (#2269): Added GET and HEAD /v1/files/{path}?stat=true returning a single FileEntry object without opening files or enumerating parent directories. Also switched modified_at from RFC3339 to RFC3339Nano (UTC) across both ?stat=true and DirectoryListing (GET /v1/files/{dir}) responses to preserve sub-second timestamps.
  • More specific REST filesystem error codes (#2220, #2303): Mapped sandboxd REST /v1/files/... failures that previously returned 500 INTERNAL:
    • Disk and quota exhaustion (ENOSPC/EDQUOT) now returns 507 (RESOURCE_EXHAUSTED), and overly long paths or path components (ENAMETOOLONG) return 400 (INVALID_ARGUMENT) (#2303).
    • REST requests (GET, HEAD, PUT, DELETE, :copy, :move) targeting a path beneath a regular file (ENOTDIR) now return 404 (NOT_FOUND) (#2220).
  • Close output pipes after streamed commands exit (#2279): Fixed a file descriptor leak in non-PTY streamed ProcessService/Start calls by closing stdout and stderr read pipes immediately once output readers drain.

SDKs

  • Cross-SDK feature parity:
    • Suspend and resume lifecycle: Added Suspend(), Resume(), and IsSuspended() to Go (#2256); sync and async suspend(), resume(), and is_suspended() to Python (#2273); and async suspend(), resume(), and isSuspended() to TypeScript (#2283). Each patches spec.operatingMode with a UID guard to release the Pod while keeping the claim and persistent volumes (running processes, memory, and emptyDir storage do not survive unless paired with pod snapshots).
    • Archive extraction (extract): Added Sandbox.Extract / Files.Extract to Go (#2260), sync and async files.extract() to Python (#2244), and files.extract() to TypeScript (#2287) to unpack plain or gzipped tar archives into a sandbox directory in one request. Requires sandboxd v1.0.10+ (unsupported on the legacy runtime).
    • Claim lifecycle options: Exposed ShutdownPolicy (Delete, DeleteForeground, Retain) and TTLSecondsAfterFinished during sandbox creation across Go (Options and WithShutdownPolicy / WithTTLSecondsAfterFinished) (#2311), Python (keyword-only shutdown_policy and ttl_seconds_after_finished on create_sandbox()) (#2262), and TypeScript (CreateSandboxOptions plus exported ShutdownPolicy type) (#2286, #2304). When a lifecycle timer is set and shutdownPolicy is omitted, the SDKs continue to default it to Delete (the CRD default is Retain).
  • Python SDK:
    • Added sync and async files.stat() returning FileEntry metadata via GET /v1/files/{path}?stat=true (#2332). Requires sandboxd v1.0.12+ (raises NotImplementedError on the legacy runtime).
    • Added recursive and max_depth parameters to sync and async files.list() (#2244). Requires sandboxd v1.0.10+ (recursive=True raises NotImplementedError on the legacy runtime).
    • Updated sync and async commands.run(command_timeout=...) on sandboxd to call ExecuteWithLimits, retaining stdout and stderr produced before timeout with exit_code=124 and timed_out=True (#2319). Requires sandboxd v1.0.10+ (falls back to Execute without partial output on v1.0.9 and earlier, or when command_timeout exceeds deployment limits).
  • TypeScript SDK:
    • Added async files.stat() returning Promise<FileEntry> with sub-second RFC 3339 modifiedAt timestamps (#2292). Requires sandboxd v1.0.12+.
    • Added sandbox.watcher.watch() streaming real-time filesystem events over gRPC FileWatcherService.WatchDir (requires the optional gRPC peer dependencies) (#2312).
    • Added "router-port-forward" connectivity mode along with routerNamespace, disablePodIPRouting, and routerAuthToken options, sending authToken in X-Sandboxd-Token when routing through sandbox-router (#2259). gRPC requires sandbox-router v1.0.9+; X-Sandboxd-Token requires sandboxd v1.0.11+.

Examples

  • CI runner sandbox (#2280): Added examples/ci-runner-sandbox showing ephemeral, per-job CI build execution backed by a SandboxWarmPool with automatic claim teardown and a reference GitHub Actions workflow.
  • Claude Code proxy access and suspend/resume (#2306): Updated examples/claude-code-sandbox to document spec.networkPolicy configuration for routing through an in-cluster model proxy and updated run_claude.py to demonstrate session persistence across suspend() and resume().
  • Per-pod OpenClaw gateway tokens (#2263): Updated examples/openclaw-gvisor-sandbox to remove the shared OPENCLAW_GATEWAY_TOKEN env var so each sandbox Pod generates its own gateway token on startup.

Documentation

  • Spot/preemptible node troubleshooting (#2282): Documented how to diagnose, prevent, and recover Sandboxes stuck in PodTerminating after their node disappears without kubelet confirmation.
  • API and SDK docs (#2053, #2295): Clarified SandboxClaim API comments for unset shutdownTime, shutdownPolicy modes, and ttlSecondsAfterFinished (#2053); fixed Go SDK README.md snippets that called *Sandbox methods on *Client and clarified reconnect error handling (#2295).

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

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

Python SDK

pip install k8s-agent-sandbox==1.0.12

Contributors

We extend our sincere thanks to all contributors to this release:
@Sean-790761, @YoungJinJung, @aditya-shantanu, @aminbaa, @anishgirianish, @dongjiang1989, @ericcurtin, @gambtho, @git-jxj, @lbarrosby, @lilong555, @lunarwhite, @thuongvu, @tridev-tej, @yuzhiquan

New Contributors

Full Changelog: v1.0.11...v1.0.12

Don't miss a new agent-sandbox release

NewReleases is sending notifications on new releases.