🚀 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): Addedspec.readinessGracePeriodSeconds(optional, minimum30) toSandboxWarmPoolto override the controller-level--sandbox-warm-pool-readiness-grace-periodflag andagent-sandbox-configConfigMap (built-in default5m) in either direction. Editing the field does not mark existing sandboxes stale. Updates theSandboxWarmPoolCRD schema (Helm users should apply the updated CRD before setting this field) and bumps the Helm chart to0.1.5.
Sandbox Router
- Sandbox-scoped v2 authorization tokens (#2258): Added
authz.MintScopedTokenV2Sandboxto mint Ed25519 v2 tokens bound to(namespace, name, uid)that authorize all ports, methods, and paths for that Sandbox until expiry. Upgrade allsandbox-routerreplicas before minting sandbox-scoped v2 tokens; older replicas reject them with403.
sandboxd
- Single-path file metadata (
?stat=true) (#2269): AddedGETandHEAD /v1/files/{path}?stat=truereturning a singleFileEntryobject without opening files or enumerating parent directories. Also switchedmodified_atfromRFC3339toRFC3339Nano(UTC) across both?stat=trueandDirectoryListing(GET /v1/files/{dir}) responses to preserve sub-second timestamps. - More specific REST filesystem error codes (#2220, #2303): Mapped
sandboxdREST/v1/files/...failures that previously returned500 INTERNAL:- Disk and quota exhaustion (
ENOSPC/EDQUOT) now returns507(RESOURCE_EXHAUSTED), and overly long paths or path components (ENAMETOOLONG) return400(INVALID_ARGUMENT) (#2303). - REST requests (
GET,HEAD,PUT,DELETE,:copy,:move) targeting a path beneath a regular file (ENOTDIR) now return404(NOT_FOUND) (#2220).
- Disk and quota exhaustion (
- Close output pipes after streamed commands exit (#2279): Fixed a file descriptor leak in non-PTY streamed
ProcessService/Startcalls by closingstdoutandstderrread pipes immediately once output readers drain.
SDKs
- Cross-SDK feature parity:
- Suspend and resume lifecycle: Added
Suspend(),Resume(), andIsSuspended()to Go (#2256); sync and asyncsuspend(),resume(), andis_suspended()to Python (#2273); and asyncsuspend(),resume(), andisSuspended()to TypeScript (#2283). Each patchesspec.operatingModewith a UID guard to release the Pod while keeping the claim and persistent volumes (running processes, memory, andemptyDirstorage do not survive unless paired with pod snapshots). - Archive extraction (
extract): AddedSandbox.Extract/Files.Extractto Go (#2260), sync and asyncfiles.extract()to Python (#2244), andfiles.extract()to TypeScript (#2287) to unpack plain or gzipped tar archives into a sandbox directory in one request. Requiressandboxdv1.0.10+(unsupported on the legacy runtime). - Claim lifecycle options: Exposed
ShutdownPolicy(Delete,DeleteForeground,Retain) andTTLSecondsAfterFinishedduring sandbox creation across Go (OptionsandWithShutdownPolicy/WithTTLSecondsAfterFinished) (#2311), Python (keyword-onlyshutdown_policyandttl_seconds_after_finishedoncreate_sandbox()) (#2262), and TypeScript (CreateSandboxOptionsplus exportedShutdownPolicytype) (#2286, #2304). When a lifecycle timer is set andshutdownPolicyis omitted, the SDKs continue to default it toDelete(the CRD default isRetain).
- Suspend and resume lifecycle: Added
- Python SDK:
- Added sync and async
files.stat()returningFileEntrymetadata viaGET /v1/files/{path}?stat=true(#2332). Requiressandboxdv1.0.12+(raisesNotImplementedErroron the legacy runtime). - Added
recursiveandmax_depthparameters to sync and asyncfiles.list()(#2244). Requiressandboxdv1.0.10+(recursive=TrueraisesNotImplementedErroron the legacy runtime). - Updated sync and async
commands.run(command_timeout=...)onsandboxdto callExecuteWithLimits, retainingstdoutandstderrproduced before timeout withexit_code=124andtimed_out=True(#2319). Requiressandboxdv1.0.10+(falls back toExecutewithout partial output onv1.0.9and earlier, or whencommand_timeoutexceeds deployment limits).
- Added sync and async
- TypeScript SDK:
- Added async
files.stat()returningPromise<FileEntry>with sub-second RFC 3339modifiedAttimestamps (#2292). Requiressandboxdv1.0.12+. - Added
sandbox.watcher.watch()streaming real-time filesystem events over gRPCFileWatcherService.WatchDir(requires the optional gRPC peer dependencies) (#2312). - Added
"router-port-forward"connectivity mode along withrouterNamespace,disablePodIPRouting, androuterAuthTokenoptions, sendingauthTokeninX-Sandboxd-Tokenwhen routing throughsandbox-router(#2259). gRPC requiressandbox-routerv1.0.9+;X-Sandboxd-Tokenrequiressandboxdv1.0.11+.
- Added async
Examples
- CI runner sandbox (#2280): Added
examples/ci-runner-sandboxshowing ephemeral, per-job CI build execution backed by aSandboxWarmPoolwith automatic claim teardown and a reference GitHub Actions workflow. - Claude Code proxy access and suspend/resume (#2306): Updated
examples/claude-code-sandboxto documentspec.networkPolicyconfiguration for routing through an in-cluster model proxy and updatedrun_claude.pyto demonstrate session persistence acrosssuspend()andresume(). - Per-pod OpenClaw gateway tokens (#2263): Updated
examples/openclaw-gvisor-sandboxto remove the sharedOPENCLAW_GATEWAY_TOKENenv 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
PodTerminatingafter their node disappears without kubelet confirmation. - API and SDK docs (#2053, #2295): Clarified
SandboxClaimAPI comments for unsetshutdownTime,shutdownPolicymodes, andttlSecondsAfterFinished(#2053); fixed Go SDKREADME.mdsnippets that called*Sandboxmethods on*Clientand 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.yamlSelective 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.yamlPython SDK
pip install k8s-agent-sandbox==1.0.12Contributors
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
- @anishgirianish made their first contribution in #2286
- @gambtho made their first contribution in #2306
- @tridev-tej made their first contribution in #2302
Full Changelog: v1.0.11...v1.0.12