Skip to content

feat(adk): add BoxLite microVM sandbox backend - #904

Closed
DorianZheng wants to merge 1 commit into
cloudwego:mainfrom
DorianZheng:feat/commandline-boxlite-sandbox
Closed

feat(adk): add BoxLite microVM sandbox backend#904
DorianZheng wants to merge 1 commit into
cloudwego:mainfrom
DorianZheng:feat/commandline-boxlite-sandbox

Conversation

@DorianZheng

@DorianZheng DorianZheng commented Jul 4, 2026

Copy link
Copy Markdown

Adds a BoxLite microVM backend for the ADK, implementing filesystem.Backend, filesystem.Shell, and filesystem.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.Backend abstraction (this PR previously targeted components/tool/commandline; fully reworked).

Where local executes on the host and agentkit delegates 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. The local backend is the behavioral reference throughout (error messages, Read's 2000-line default window, Execute's non-zero output format, streaming completion semantics).

Interface method In-guest realization
LsInfo ls -1A
Read sed -n 'start,endp' line window
GrepRaw rg --json + same JSON parsing as local (requires ripgrep in the guest image; a POSIX command -v probe returns the same friendly install hint otherwise)
GlobInfo find -mindepth 1 + host-side doublestar matching
Write base64 chunks sized under the kernel per-arg limit → unbounded file size
Edit base64 read → local-parity occurrence semantics → chunked write
Execute sh -c via Box.Exec
ExecuteStreaming Box.StartExecution + per-line stdout streaming + drain-barrier Wait

The optional MultiModalReader interface 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 boxlite build tag with a tag-less doc.go — the default build is empty, keeping the workspace CI green without the native library. Consumers run go run github.com/boxlite-ai/boxlite/sdks/go/cmd/setup once, 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

  • Default (tag-less): go build ./... / go vet ./... green, zero BoxLite packages in the dependency graph.
  • With -tags boxlite on darwin/arm64 (BoxLite SDK v0.9.7), against real booted microVMs (BOXLITE_E2E=1, python:slim):
    • write → windowed read → edit → ls → glob round-trip (special characters included)
    • 300 KiB chunked write, byte count verified in-guest
    • Execute zero and non-zero exits (combined report format)
    • ExecuteStreaming line-by-line streaming
    • GrepRaw verified both ways: against a box with ripgrep installed (match + case-insensitive + glob filter), and the install-hint error on an image without it

@DorianZheng
DorianZheng force-pushed the feat/commandline-boxlite-sandbox branch from ed1961b to ec95842 Compare July 4, 2026 15:19
@DorianZheng
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 DorianZheng changed the title feat(commandline): add BoxLite microVM sandbox backend feat(adk): add BoxLite microVM sandbox backend Jul 6, 2026
@DorianZheng
DorianZheng force-pushed the feat/commandline-boxlite-sandbox branch from ec95842 to 005ddef Compare July 6, 2026 08:31
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Development

Successfully merging this pull request may close these issues.

1 participant