feat(adk): add BoxLite microVM sandbox backend - #904
Closed
DorianZheng wants to merge 1 commit into
Closed
Conversation
DorianZheng
force-pushed
the
feat/commandline-boxlite-sandbox
branch
from
July 4, 2026 15:19
ed1961b to
ec95842
Compare
DorianZheng
marked this pull request as ready for review
July 4, 2026 15:40
Add a filesystem.Backend (plus Shell and StreamingShell) backed by a BoxLite microVM, so an ADK agent's workspace — file reads, writes, edits, searches, and shell commands — runs inside a hardware-isolated, self-hosted sandbox. All operations go through in-guest exec so files and commands share one filesystem view; guest scripts take paths as positional parameters so model input never needs shell-quoting; Write streams base64 chunks under the kernel per-arg limit. The local backend is the behavioral reference. The implementation sits behind a "boxlite" build tag so the default build is empty and the workspace CI stays green without the CGO native library. Ref #903
DorianZheng
force-pushed
the
feat/commandline-boxlite-sandbox
branch
from
July 6, 2026 08:31
ec95842 to
005ddef
Compare
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
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.
Adds a BoxLite microVM backend for the ADK, implementing
filesystem.Backend,filesystem.Shell, andfilesystem.StreamingShell— so an agent's whole workspace (file reads, writes, edits, searches, and shell commands) runs inside a hardware-isolated, self-hosted sandbox.Follows the maintainers' direction in #903 to place this under ADK as a concrete implementation of the unified
filesystem.Backendabstraction (this PR previously targetedcomponents/tool/commandline; fully reworked).Where
localexecutes on the host andagentkitdelegates to a remote sandbox service, BoxLite boots a microVM per backend — dedicated guest kernel, no shared host state, no external service — suited to running untrusted, model-generated commands.How it maps
Every operation goes through in-guest exec so reads, writes, and commands share one filesystem view. Guest scripts take paths as positional parameters (
"$1"), so model-supplied paths never need shell-quoting. Thelocalbackend is the behavioral reference throughout (error messages, Read's 2000-line default window, Execute's non-zero output format, streaming completion semantics).LsInfols -1AReadsed -n 'start,endp'line windowGrepRawrg --json+ same JSON parsing aslocal(requires ripgrep in the guest image; a POSIXcommand -vprobe returns the same friendly install hint otherwise)GlobInfofind -mindepth 1+ host-sidedoublestarmatchingWriteEditlocal-parity occurrence semantics → chunked writeExecutesh -cviaBox.ExecExecuteStreamingBox.StartExecution+ per-line stdout streaming + drain-barrierWaitThe optional
MultiModalReaderinterface is not implemented yet; planned as a follow-up.Build tag
The BoxLite SDK is CGO with a prebuilt native library (linux/amd64, darwin/arm64), so the implementation is behind the
boxlitebuild tag with a tag-lessdoc.go— the default build is empty, keeping the workspace CI green without the native library. Consumers rungo run github.com/boxlite-ai/boxlite/sdks/go/cmd/setuponce, then build with-tags boxlite. If you'd prefer a dedicated CI job that runs setup and tests-tags boxlite, happy to add it.Testing
go build ./.../go vet ./...green, zero BoxLite packages in the dependency graph.-tags boxliteon darwin/arm64 (BoxLite SDK v0.9.7), against real booted microVMs (BOXLITE_E2E=1,python:slim):Executezero and non-zero exits (combined report format)ExecuteStreamingline-by-line streamingGrepRawverified both ways: against a box with ripgrep installed (match + case-insensitive + glob filter), and the install-hint error on an image without it