# Sandbox Agent SDK

Rivet's open-source SDK for orchestrating AI coding agents inside microVMs, built on the undocumented Docker Sandbox `/vm` API ([[rivet-docker-sandbox-microvm]]). The pitch is the gap between the raw HTTP endpoint and a production agent runner: session lifecycle (VM create → image load → container start → cleanup-on-failure), parsing streaming agent output, handling permission prompts and human-in-the-loop workflows, and presenting Claude, Codex, OpenCode, and others through one unified interface.

## What it wraps

Three things the raw API leaves to you:

1. **Session lifecycle.** Creating microVMs, loading images, starting containers, and the cleanup-on-error paths the API doesn't manage.
2. **Agent communication.** Streaming output parsing, permission-prompt handling, human-in-the-loop checkpoints. The same pattern [[charlie-daemons]] hit at the long-running-agent layer.
3. **Multi-agent abstraction.** One TypeScript interface over Claude Code, Codex, OpenCode, etc. — the substrate equivalent of what [[toolbox/cc-mirror]] and [[toolbox/claude-code-router]] do at the model-routing layer.

## Where it fits

Sits on top of Docker Desktop 4.58+ on macOS/Windows. Adjacent to but distinct from:

- [[toolbox/superhq]] — broader multi-agent orchestrator (Claude Code, Codex, Pi) with its own microVM substrate; SDK-first, not orchestrator-first.
- [[toolbox/flue]] — withastro's harness framework; ships with just-bash sandboxing by default, not microVMs.
- [[hazmat]] — macOS-native containment (user/Seatbelt/pf); not microVM-based.
- [[bubblewrap-dev-env]] — Linux namespace isolation; the kind of substrate [[microvm-2026]] argues isn't enough alone.

The SDK's main value is **letting you escape the six-agent whitelist** in `docker sandbox run`. If you want to put your own agent or your own container behind Docker's microVM isolation, this is the path.

## Limitations

- Platform: macOS/Windows only, because Docker Sandboxes is.
- API stability: built on an undocumented Docker surface (`sandboxd.sock`); upstream is free to break it.
- Watchlist candidate: production adoption signals are still early; re-check 2026-08-22 for breaking-API events and SDK maturity.

## Repo

https://sandboxagent.dev. Documentation includes a "deploy with Docker Sandboxes" guide. Companion writeup: [[rivet-docker-sandbox-microvm]].