Skip to content

Commit cbf9bdc

Browse files
NathanFlurryNathanFlurry
committed
chore: add microvms blog post (#4109)
1 parent fcb3be9 commit cbf9bdc

File tree

2 files changed

+250
-0
lines changed
  • website/src/content/posts/2026-02-04-we-reverse-engineered-docker-sandbox-undocumented-microvm-api

2 files changed

+250
-0
lines changed

‎website/src/content/posts/2026-02-04-we-reverse-engineered-docker-sandbox-undocumented-microvm-api/image.png‎

63.4 KB
Loading

‎website/src/content/posts/2026-02-04-we-reverse-engineered-docker-sandbox-undocumented-microvm-api/page.mdx‎

Lines changed: 250 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,250 @@
1+
---
2+
author: nathan-flurry
3+
published: "2026-02-04"
4+
category: technical
5+
keywords: ["docker", "microvm", "sandbox", "isolation", "security", "containers", "virtualization", "ai-agents"]
6+
title: "We Reverse-Engineered Docker Sandbox's Undocumented MicroVM API"
7+
description: "Docker ships with an undocumented API for spawning isolated microVMs. Here's how to use it for more than just AI agents."
8+
---
9+
10+
<Lead>
11+
**Docker ships with an undocumented API for spawning microVMs. We reverse-engineered it and built the open-source [Sandbox Agent SDK](https://sandboxagent.dev) to allow orchestrating coding agents inside of them.**
12+
</Lead>
13+
14+
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.
15+
16+
With the launch of Docker Sandboxes, Docker quietly shipped an undocumented API for microVMs that can power sandboxes.
17+
18+
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.)
19+
20+
## What Are Docker Sandboxes?
21+
22+
[Docker Sandboxes](https://docs.docker.com/ai/sandboxes/) ([launch post](https://www.docker.com/blog/docker-sandboxes-a-new-approach-for-coding-agent-safety/)) 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.
23+
24+
Docker shipped a simple CLI:
25+
26+
```bash
27+
docker sandbox run claude ~/project
28+
```
29+
30+
At first glance, this looks like a glorified `docker run` command, but under the hood Docker is **using a completely different technology: microVMs**.
31+
32+
## MicroVMs vs Containers: Looking Under The Hood
33+
34+
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.
35+
36+
However, it's a common **misconception that containers are good enough for running untrusted code** (AI agents, user-submitted scripts, multi-tenant plugins).
37+
38+
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.
39+
40+
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](https://github.com/firecracker-microvm/firecracker?tab=readme-ov-file#what-is-firecracker) [other](https://www.koyeb.com/blog/10-reasons-why-we-love-firecracker-microvms) [documents](https://firecracker-microvm.github.io/) that better describe microVMs & Firecracker if you'd like to read more.
41+
42+
This is why **Docker built Sandboxes on microVMs** instead of containers while remaining compatible with Docker containers.
43+
44+
This is how the two compare:
45+
46+
| | Docker Container | Docker Sandbox |
47+
|---|------------------|----------------|
48+
| **Security** | Shared kernel (namespaces) | Separate kernel (microVM) |
49+
| **Untrusted code** | Not safe | Safe |
50+
| **Network access** | Direct HTTP | Via filtering proxy |
51+
| **Volumes** | Direct mount | Bidirectional file sync |
52+
| **Platform** | Linux, macOS, Windows | macOS, Windows only |
53+
54+
### Use Cases
55+
56+
This opens up use cases that containers can't safely handle:
57+
58+
- **Untrusted code execution**: Run user-submitted scripts without risking your host
59+
- **AI coding agents**: Let Claude/Codex run with full permissions safely
60+
- **Multi-tenant plugins**: Isolate customer code in SaaS applications
61+
- **Secure CI/CD**: Run builds with VM-level isolation instead of containers
62+
63+
64+
## The MicroVMs API
65+
66+
`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.
67+
68+
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.
69+
70+
### The /vm HTTP API: Creating a VM
71+
72+
Docker's sandboxd daemon manages all of the virtual machines and listens on `~/.docker/sandboxes/sandboxd.sock`.
73+
74+
It provides three endpoints:
75+
76+
- `GET /vm`: List all VMs
77+
- `POST /vm`: Create a VM
78+
- `DELETE /vm/{vm_name}`: Destroy a VM
79+
80+
We'll create a VM with:
81+
82+
```bash
83+
curl -X POST --unix-socket ~/.docker/sandboxes/sandboxd.sock \
84+
http://localhost/vm \
85+
-H "Content-Type: application/json" \
86+
-d '{"agent_name": "my-sandbox", "workspace_dir": "/path/to/project"}'
87+
```
88+
89+
And we get the response:
90+
91+
```json
92+
{
93+
"vm_id": "abc123",
94+
"vm_config": {
95+
"socketPath": "/Users/you/.docker/sandboxes/vm/my-sandbox-vm/docker.sock",
96+
"fileSharingDirectories": ["/path/to/project"],
97+
"stateDir": "/Users/you/.docker/sandboxes/vm/my-sandbox-vm"
98+
},
99+
"ca_cert_path": "/Users/you/.docker/sandboxes/vm/my-sandbox-vm/proxy_cacerts/proxy-ca.crt"
100+
}
101+
```
102+
103+
The VM name follows the pattern `{agent_name}-vm`. `socketPath` is your per-VM Docker daemon, which we'll use in the next step.
104+
105+
### Talking To The microVM's Docker Daemon
106+
107+
Normally all containers share `/var/run/docker.sock`. Anyone with socket access can see and control every other container.
108+
109+
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, but are completely isolated from the host and other VMs.
110+
111+
To target different daemons, we will need to override the Unix socket path using `curl --unix-socket ...` or `docker --host unix://...`.
112+
113+
### Loading Images into the VM
114+
115+
New VMs are completely isolated from the host, so we need to manually load images we've built into the VM.
116+
117+
We do this by building, archiving, and loading the image into the VM like this:
118+
119+
```bash
120+
# Build on host
121+
docker build -t my-image:latest .
122+
# Archive image
123+
docker save my-image:latest > /tmp/image.tar
124+
# Load into microVM
125+
docker --host "unix://$VM_SOCK" load < /tmp/image.tar
126+
```
127+
128+
`$VM_SOCK` is the `socketPath` from the earlier step.
129+
130+
### Running Containers Inside the VM
131+
132+
Now the fun part: we can finally run our image and work with it like any other Docker container.
133+
134+
```bash
135+
docker --host "unix://$VM_SOCK" run -d --name my-container my-image:latest
136+
```
137+
138+
#### Networking
139+
140+
microVMs route outbound traffic through a filtering proxy at `host.docker.internal:3128`. Your container needs these env vars:
141+
142+
```bash
143+
docker --host "unix://$VM_SOCK" run -d --name my-container \
144+
-e HTTP_PROXY=http://host.docker.internal:3128 \
145+
-e HTTPS_PROXY=http://host.docker.internal:3128 \
146+
-e NODE_TLS_REJECT_UNAUTHORIZED=0 \
147+
my-image:latest
148+
```
149+
150+
The proxy does man-in-the-middle on HTTPS (hence `NODE_TLS_REJECT_UNAUTHORIZED=0`) for network policy enforcement. For production use, install the CA certificate from `ca_cert_path` in the VM response instead of disabling TLS verification.
151+
152+
#### Volumes
153+
154+
Workspace syncs at the same absolute path, so volume mounts just work:
155+
156+
```bash
157+
-v "/Users/me/project:/Users/me/project"
158+
```
159+
160+
### Putting It Together
161+
162+
```bash
163+
#!/bin/bash
164+
set -e
165+
166+
SANDBOXD_SOCK="$HOME/.docker/sandboxes/sandboxd.sock"
167+
WORKSPACE="$(pwd)"
168+
AGENT_NAME="my-sandbox"
169+
170+
# Create VM
171+
RESPONSE=$(curl -s -X POST --unix-socket "$SANDBOXD_SOCK" \
172+
http://localhost/vm \
173+
-H "Content-Type: application/json" \
174+
-d "{\"agent_name\": \"$AGENT_NAME\", \"workspace_dir\": \"$WORKSPACE\"}")
175+
176+
VM_NAME="$AGENT_NAME-vm"
177+
VM_SOCK=$(echo "$RESPONSE" | jq -r '.vm_config.socketPath')
178+
echo "VM created: $VM_NAME"
179+
180+
# Build and load image
181+
docker build -t my-image:latest .
182+
docker save my-image:latest > /tmp/my-image.tar
183+
docker --host "unix://$VM_SOCK" load < /tmp/my-image.tar
184+
185+
# Run container
186+
docker --host "unix://$VM_SOCK" run --rm my-image:latest echo "Hello from microVM!"
187+
188+
# Destroy VM
189+
curl -s -X DELETE --unix-socket "$SANDBOXD_SOCK" "http://localhost/vm/$VM_NAME"
190+
echo "VM destroyed"
191+
```
192+
193+
<Note>
194+
Docker Sandboxes require **Docker Desktop 4.58+** on **macOS or Windows**. Linux is not supported since Docker Desktop uses platform-specific virtualization (Apple Virtualization.framework on macOS, Hyper-V on Windows).
195+
</Note>
196+
197+
198+
## Orchestrating Agents With The Sandbox Agent SDK
199+
200+
The raw microVM API is powerful, but building a production agent orchestration system on top of it requires handling:
201+
202+
- **Session lifecycle**: Creating VMs, loading images, starting containers, and cleanup on failure
203+
- **Agent communication**: Parsing streaming output, handling permission prompts, managing human-in-the-loop workflows
204+
- **Multi-agent support**: Running Claude, Codex, or OpenCode through a unified interface
205+
206+
We built the [Sandbox Agent SDK](https://sandboxagent.dev) to handle all of this. It wraps the microVM API and provides a simple interface for spawning and interacting with AI coding agents:
207+
208+
<Tabs>
209+
<Tab title="TypeScript">
210+
211+
```typescript
212+
import { SandboxAgent } from "sandbox-agent";
213+
214+
const client = await SandboxAgent.connect({ baseUrl: "http://127.0.0.1:2468" });
215+
await client.createSession("my-session", { agent: "claude" });
216+
await client.postMessage("my-session", { message: "Fix the tests" });
217+
218+
for await (const event of client.streamEvents("my-session")) {
219+
console.log(event.type, event.data);
220+
}
221+
```
222+
223+
</Tab>
224+
<Tab title="curl">
225+
226+
```bash
227+
# Create session
228+
curl -X POST "http://127.0.0.1:2468/v1/sessions/my-session" \
229+
-H "Content-Type: application/json" \
230+
-d '{"agent":"claude"}'
231+
232+
# Send message
233+
curl -X POST "http://127.0.0.1:2468/v1/sessions/my-session/messages" \
234+
-H "Content-Type: application/json" \
235+
-d '{"message":"Fix the tests"}'
236+
237+
# Stream events
238+
curl "http://127.0.0.1:2468/v1/sessions/my-session/events/sse"
239+
```
240+
241+
</Tab>
242+
</Tabs>
243+
244+
See the full guide on [deploying with Docker Sandboxes](https://sandboxagent.dev/docs/deploy/docker-sandbox).
245+
246+
## Wrapping Up
247+
248+
Docker's microVM API opens up secure isolation for any workload, not just the handful of agents Docker officially supports. Whether you're building an AI coding assistant, running untrusted user code, or isolating multi-tenant plugins, the `/vm` API gives you the primitives to do it safely.
249+
250+
The API is undocumented and subject to change, but it works today on Docker Desktop 4.58+. If you're building something with it, we'd love to hear about it.

0 commit comments

Comments
 (0)