We Reverse-Engineered Docker Sandbox's Undocumented MicroVM API — Rivet

Source: https://rivet.dev/blog/2026-02-04-we-reverse-engineered-docker-sandbox-undocumented-microvm-api/ (fetched via defuddle on 2026-05-22)

Author: Rivet team (rivet.dev). Companion product: Sandbox Agent SDK at https://sandboxagent.dev.

Docker ships with an undocumented API for spawning microVMs. We reverse-engineered it and built the open-source Sandbox Agent SDK to allow orchestrating coding agents inside of them.

Docker & containers are the standard for how we've been running backends. Recently, more workloads have been moving to sandboxes for untrusted code execution, which Docker is not suitable for.

With the launch of Docker Sandboxes, Docker quietly shipped an undocumented API for microVMs that can power sandboxes. This looks promising as a unified way of managing sandboxes on your own infrastructure using microVMs, just like Docker did for containers 10 years ago. (Today it only supports macOS/Windows. Requires nested virtualization.)

What Are Docker Sandboxes?

Docker Sandboxes (https://docs.docker.com/ai/sandboxes/) are Docker's solution for running AI coding agents safely. Claude Code, Codex, and Gemini need to run arbitrary code, install packages, and modify files. MicroVMs let them run --dangerously-skip-permissions without being dangerous.

Docker shipped a simple CLI:

docker sandbox run claude ~/project

At first glance this looks like a glorified docker run, but under the hood Docker is using a completely different technology: microVMs.

MicroVMs vs Containers

Containers share the host kernel for speed; a compromised container puts the host at risk. Products like AWS Lambda, Fly.io, and most sandbox providers use microVMs for lightweight virtual machines with separate kernels. Lighter than full VMs, considered the gold standard of isolating user code.

This is why Docker built Sandboxes on microVMs instead of containers while remaining compatible with Docker containers.

Use Cases

• Untrusted code execution
• AI coding agents (let Claude/Codex run with full permissions safely)
• Multi-tenant plugins
• Secure CI/CD

The MicroVMs API

docker sandbox run is strictly limited to Docker's whitelisted agents: Claude, Codex, Gemini, Copilot, Kiro, Cagent. It does not let you run your own containers.

So we went down the rabbit hole to reverse engineer the underlying microVM API.

The /vm HTTP API: Creating a VM

Docker's sandboxd daemon manages all VMs and listens on ~/.docker/sandboxes/sandboxd.sock.

Three endpoints:

• GET /vm: list all VMs
• POST /vm: create a VM
• DELETE /vm/{vm_name}: destroy a VM

Create a VM:

curl -X POST --unix-socket ~/.docker/sandboxes/sandboxd.sock \
  http://localhost/vm \
  -H "Content-Type: application/json" \
  -d '{"agent_name": "my-sandbox", "workspace_dir": "/path/to/project"}'

Response:

{
  "vm_id": "abc123",
  "vm_config": {
    "socketPath": "/Users/you/.docker/sandboxes/vm/my-sandbox-vm/docker.sock",
    "fileSharingDirectories": ["/path/to/project"],
    "stateDir": "/Users/you/.docker/sandboxes/vm/my-sandbox-vm"
  },
  "ca_cert_path": "/Users/you/.docker/sandboxes/vm/my-sandbox-vm/proxy_cacerts/proxy-ca.crt"
}

VM name follows the pattern {agent_name}-vm. socketPath is the per-VM Docker daemon.

Talking To The microVM's Docker Daemon

Normally all containers share /var/run/docker.sock. Anyone with socket access controls every other container.

Sandboxes flip this. Each microVM gets its own Docker daemon at ~/.docker/sandboxes/vm/<name>/docker.sock for maximum isolation. Containers run like normal inside the microVM, completely isolated from the host and other VMs.

Override the socket via docker --host unix://....

Loading Images into the VM

New VMs are isolated from the host, so images must be loaded manually:

docker build -t my-image:latest .
docker save my-image:latest > /tmp/image.tar
docker --host "unix://$VM_SOCK" load < /tmp/image.tar

Running Containers Inside the VM

docker --host "unix://$VM_SOCK" run -d --name my-container my-image:latest

Networking

microVMs route outbound traffic through a filtering proxy at host.docker.internal:3128:

docker --host "unix://$VM_SOCK" run -d --name my-container \
  -e HTTP_PROXY=http://host.docker.internal:3128 \
  -e HTTPS_PROXY=http://host.docker.internal:3128 \
  -e NODE_TLS_REJECT_UNAUTHORIZED=0 \
  my-image:latest

The proxy does MITM on HTTPS (hence NODE_TLS_REJECT_UNAUTHORIZED=0) for network policy enforcement. For production, install the CA from ca_cert_path.

Volumes

Workspace syncs at the same absolute path:

-v "/Users/me/project:/Users/me/project"

Putting It Together

#!/bin/bash
set -e
SANDBOXD_SOCK="$HOME/.docker/sandboxes/sandboxd.sock"
WORKSPACE="$(pwd)"
AGENT_NAME="my-sandbox"

RESPONSE=$(curl -s -X POST --unix-socket "$SANDBOXD_SOCK" \
  http://localhost/vm \
  -H "Content-Type: application/json" \
  -d "{\"agent_name\": \"$AGENT_NAME\", \"workspace_dir\": \"$WORKSPACE\"}")

VM_NAME="$AGENT_NAME-vm"
VM_SOCK=$(echo "$RESPONSE" | jq -r '.vm_config.socketPath')

docker build -t my-image:latest .
docker save my-image:latest > /tmp/my-image.tar
docker --host "unix://$VM_SOCK" load < /tmp/my-image.tar
docker --host "unix://$VM_SOCK" run --rm my-image:latest echo "Hello from microVM!"

curl -s -X DELETE --unix-socket "$SANDBOXD_SOCK" "http://localhost/vm/$VM_NAME"

Requires Docker Desktop 4.58+ on macOS or Windows. Linux not supported (Docker Desktop uses Apple Virtualization.framework on macOS, Hyper-V on Windows).

Orchestrating Agents With The Sandbox Agent SDK

The raw microVM API is powerful, but a production agent orchestration system on top of it needs:

• Session lifecycle (VM create, image load, container start, cleanup on failure)
• Agent communication (parsing streaming output, permission prompts, HITL workflows)
• Multi-agent support (Claude, Codex, OpenCode through one interface)

The Sandbox Agent SDK (https://sandboxagent.dev) wraps the microVM API.

Wrapping Up

Docker's microVM API opens up secure isolation for any workload, not just the handful of agents Docker officially supports. AI coding assistants, untrusted user code, multi-tenant plugins — the /vm API gives the primitives. The API is undocumented and subject to change, but it works today on Docker Desktop 4.58+.