We Reverse-Engineered Docker Sandbox's Undocumented MicroVM API - Rivet<br>Skip to main content

GitHubSign In

Blog

Technical

We Reverse-Engineered Docker Sandbox's Undocumented MicroVM API<br>Posted by<br>N Nathan Flurry<br>Co-founder & CTO

February 4, 2026<br>Other articles<br>Introducing agentOS<br>Introducing SQLite for Rivet Actors<br>Introducing Queues for Rivet Actors

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 to be 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 (launch post) 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 command, but under the hood Docker is using a completely different technology: microVMs .

MicroVMs vs Containers: Looking Under The Hood

Containers are what most developers know and love when they run docker run. They provide basic file system, network, and process isolation between the host machine.

However, it’s a common misconception that containers are good enough for running untrusted code (AI agents, user-submitted scripts, multi-tenant plugins).

By design, containers share the host’s kernel in order to be fast and lightweight. However, that means that a compromised container can put the host at risk. The security implications of using containers is a longer topic, but most of the industry agrees that containers are a bad practice for untrusted code execution.

In order to achieve better security, products like AWS Lambda, Fly.io, and most sandbox providers use microVMs for lightweight virtual machines with separate kernels for better security. It’s lighter than a full virtual machine, but does not carry as much overhead. This is considered the gold standard of isolating user code. There are many other documents that better describe microVMs & Firecracker if you’d like to read more.

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

This is how the two compare:

Docker ContainerDocker SandboxSecurity Shared kernel (namespaces)Separate kernel (microVM)Untrusted code Not safeSafeNetwork access Direct HTTPVia filtering proxyVolumes Direct mountBidirectional file syncPlatform Linux, macOS, WindowsmacOS, Windows only

Use Cases

This opens up use cases that containers can’t safely handle:

Untrusted code execution : Run user-submitted scripts without risking your host

AI coding agents : Let Claude/Codex run with full permissions safely

Multi-tenant plugins : Isolate customer code in SaaS applications

Secure CI/CD : Run builds with VM-level isolation instead of containers

The MicroVMs API

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

So naturally, I went down the rabbit hole to see if I could reverse engineer the underlying microVM API in order to run any code I’d like inside of sandboxes.

The /vm HTTP API: Creating a VM

Docker’s sandboxd daemon manages all of the virtual machines and listens on ~/.docker/sandboxes/sandboxd.sock.

It provides three endpoints:

GET /vm: List all VMs

POST /vm: Create a VM

DELETE /vm/{vm_name}: Destroy a VM

We’ll create a VM with:

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

And we get the response:

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

The VM name follows the pattern {agent_name}-vm. socketPath is your per-VM Docker daemon, which we’ll use in the next step.

Talking To The microVM’s Docker Daemon

Normally all containers share /var/run/docker.sock. Anyone with socket access can see and control every other container.

Sandboxes flip this. Each microVM gets its own...