DockerSandbox

Docker io.agentscope.harness.agent.sandbox.Sandbox that runs commands in a container.

Uses the docker CLI via ProcessBuilder; no docker-java library dependency is required. The Docker daemon must be accessible on the host.

Container Lifecycle

• On #start(): the container is created and started if it does not exist; if the container exists but is stopped it is restarted; if it is already running the existing container is reused.

• On #stop(): the workspace snapshot is persisted (if configured). The container keeps running.

• On #shutdown(): the container is stopped and removed if self-managed.

Workspace Operations

• Exec: docker exec -w <root> <containerId> sh -c <command>

• PersistWorkspace: docker exec <containerId> tar -cf - -C <root> .

• HydrateWorkspace: docker exec -i <containerId> tar -xf - -C <root>

• UploadFile / DownloadFile (SandboxFileTransfer): a host temp file round-tripped through docker cp, so file bytes never pass through exec argv or the stdout capture cap. Scoped to the workspace subtree by lexical validation; uploads land with mode 0644, matching the archive-hydrate fallback. Symlinks inside the sandbox are not resolved — the isolation boundary is the container, not the subtree.