refactor(sandbox-kubernetes): rebase the Kubernetes sandbox store on agent-sandbox - #2308
Merged
Merged
Conversation
Codecov Report❌ Patch coverage is 📢 Thoughts on this report? Let us know! |
oss-maintainer
approved these changes
Jul 21, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Motivation
The Kubernetes sandbox store used to manage raw pods directly through fabric8 (
Fabric8KubernetesPodRuntime), which meant we owned pod scheduling, readiness, cleanup, and connectivity ourselves — and offered none of the warm-start or lifecycle semantics that agentic workloads actually need.agent-sandbox (a Kubernetes SIG project) solves exactly this problem at the cluster level: sandboxes are CRDs (
Sandbox/SandboxClaim/SandboxTemplate/SandboxWarmPool) reconciled by a controller, with warm pools for sub-second acquisition, PVC-backed workspace persistence, and lifecycle policies (TTL, hibernation) built in. This PR rebases the Kubernetes store on it: the cluster owns the sandbox fleet, and the Java side merely claims an instance and talks to its runtime HTTP API.What's in this PR
A standalone Java client SDK for agent-sandbox
io.agentscope.extensions.sandbox.kubernetes.clientis a self-contained client mirroring the official Python SDK (agentic-sandbox-client), usable independently of the Harness:SandboxClient/Sandboxfor lifecycle: create (claim from a warm pool), get, list, delete, terminate.CommandExecutor(POST /execute) andFilesystem(/upload,/download,/list,/exists) for the data plane, with client-side path sanitization.port-forwardlocal tunnel (the development default), and in-cluster pod IP — selected via typed connection configs.The old fabric8 pod runtime and its tests are deleted; the Harness-facing
KubernetesSandboxClient/KubernetesSandboxnow delegate to the SDK while keepingOptions/Spec/Stateserialization wire-compatible.Workspace archives now travel over the file API
Persist/hydrate used to shell out
tar | base64and embed the entire archive in an/executecommand line — which breaks past Linux's ~128 KiB per-argument limit and inflates memory. Snapshot tarballs are now transferred through the runtime's/upload//downloadendpoints as raw bytes. The base directory is configurable (fileApiBaseDir, default/workspace); leaving it blank falls back to the exec path, whose base64 decoding also got fixed to tolerate GNUbase64line wrapping.SandboxFileTransfer: an opt-in native transfer capabilityThe Harness
SandboxSPI deliberately has a single data-plane entry point (exec), because tool semantics likeedit_fileandgrep_filescan only be expressed as shell against a standard toolchain. But pure byte transfer doesn't need a shell. This PR adds an optionalSandboxFileTransferinterface;SandboxBackedFilesystemprefers it when the backend implements it and the path qualifies, and falls back to exec+base64 otherwise. The Kubernetes store implements it by mapping workspace-absolute paths onto the file API, sowrite_fileand file downloads are no longer bound by command-line length limits. Other stores are unaffected.Documentation: the runtime image contract, and where state actually lives
Two new sections in the sandbox docs (zh + en), prompted by questions this migration surfaced:
sh, coreutils, GNUstat -c,tar/base64,python3) with a one-line conformance check, plus the agent-sandbox-specific HTTP API requirements (/executemust have shell semantics; the file API root must match the workspace root). Notably, the upstream example runtime does not conform (itshlex.splits commands without a shell and roots its file API at/app) and is documented as endpoint-shape reference only.SandboxTemplate.volumeClaimTemplatesand mounted at the workspace root); the HarnessSandboxState+ snapshot layer remains the identity pointer for resume and the cold-recovery fallback once a claim expires. The docs cover the split of responsibilities, a reference template, and the snapshot-vs-PVC trade-off.The Kubernetes section of the filesystem docs was rewritten to match the actual
KubernetesFilesystemSpecAPI (warm pool + namespace + connection options), replacing an example that referenced setters from the pre-agent-sandbox era.Testing
CommandExecutorTest,FilesystemTest,CreateSandboxOptionsTest) and the adapter (KubernetesSandboxTest: exec wrapping, file-API vs exec transfer paths, self-exclusion of temp archives, wrapped-base64 decoding).SandboxBackedFilesystemTestextended to cover native-transfer dispatch, per-path fallback, and failure reporting.agentscope-harness(638 tests) andagentscope-extensions-sandbox-kubernetes(23 tests) both green.Notes for reviewers
/execute, file API rooted at/workspace) is a deployment prerequisite and is documented as such.intro.md+homepage.css) and a Chinese blog post (agentscope-v2-explained.md). Happy to split them out if preferred.