Reverse Engineering Docker's Undocumented MicroVM API for Secure Agent Execution
The rise of AI coding agents like Claude Code, Codex, and Gemini has created a critical security challenge: how to allow an autonomous agent to install packages, modify files, and execute arbitrary code without compromising the host system. While Docker containers have long been the industry standard for isolation, they are fundamentally unsuitable for executing untrusted code.
Recently, Docker introduced "Docker Sandboxes," which include an undocumented API for spawning microVMs. By reverse-engineering this API, developers can now orchestrate secure, isolated environments for coding agents and other untrusted workloads, moving beyond the limitations of standard containers.
Containers vs. MicroVMs: The Security Gap
To understand why Docker shifted to microVMs for its sandbox feature, it is necessary to distinguish between container isolation and virtual machine isolation.
Containers share the host's kernel. They use namespaces and cgroups to provide a layer of isolation, but because the kernel is shared, a vulnerability in the kernel can allow a compromised container to escape to the host. This makes containers a risky choice for multi-tenant plugins or AI agents running with high permissions.
MicroVMs, by contrast, provide a separate kernel for every instance. They offer the security profile of a full virtual machine but are optimized for speed and low overhead, similar to technologies like AWS Lambda or Firecracker. This is widely considered the gold standard for isolating untrusted user code.
Comparison Summary
| Feature | Docker Container | Docker Sandbox (microVM) |
|---|---|---|
| Security | Shared kernel (namespaces) | Separate kernel (microVM) |
| Untrusted Code | Not safe | Safe |
| Network Access | Direct HTTP | Via filtering proxy |
| Volumes | Direct mount | Bidirectional file sync |
| Platform | Linux, macOS, Windows | macOS, Windows only (initially) |
Deconstructing the Undocumented API
Docker's sandbox functionality is managed by the sandboxd daemon, which listens on a Unix socket at ~/.docker/sandboxes/sandboxd.sock. Through reverse engineering, it has been discovered that the daemon exposes three primary endpoints:
GET /vm: Lists all active VMs.POST /vm: Creates a new VM.DELETE /vm/{vm_name}: Destroys a specific VM.
The Architecture of Isolation
One of the most significant departures from standard Docker is how the daemon is handled. In a typical setup, all containers share /var/run/docker.sock. In the Sandbox model, each microVM receives its own dedicated Docker daemon located at ~/.docker/sandboxes/vm/<name>/docker.sock.
This ensures that containers running inside the microVM are completely isolated from the host and from other VMs. To interact with these VMs, developers must override the Unix socket path using curl --unix-socket or docker --host unix://....
Implementation Details
Because these VMs are entirely isolated, images must be manually loaded into the VM environment. The process involves building the image, archiving it, and loading it via the VM-specific socket:
# Example workflow
docker save my-image | docker --host unix://$VM_SOCK load
Networking and Volumes
Outbound traffic in these microVMs is routed through a filtering proxy at host.docker.internal:3128. To ensure connectivity, containers require specific environment variables (HTTP_PROXY and HTTPS_PROXY). Because the proxy performs man-in-the-middle (MITM) operations on HTTPS for policy enforcement, developers must either install the CA certificate provided in the VM response or disable TLS verification (e.g., NODE_TLS_REJECT_UNAUTHORIZED=0).
Workspace synchronization is handled via absolute paths, meaning volume mounts function as expected, facilitating a seamless bridge between the host files and the isolated environment.
Critical Analysis and Community Perspectives
While the reverse-engineered API provides a powerful primitive for agent orchestration, the community has raised several important points regarding its utility and limitations.
Platform Availability
The original implementation was limited to macOS and Windows due to its reliance on platform-specific virtualization (Apple Virtualization.framework and Hyper-V). However, community members have noted that Linux support is possible via KVM, and Docker has since released sbx, a standalone 50MB binary that removes the requirement for Docker Desktop entirely.
The "Agent Security" Debate
Some developers question whether VM-level isolation is the primary problem to solve for AI agents. As one contributor noted:
"Even sandboxed agents usually have a lot of capabilities. Adding backdoors to code by installing breached packages, abusing some access tokens to cause harm, and much more."
This suggests that while microVMs prevent host kernel escapes, they do not solve the higher-level application security risks associated with autonomous agents executing code.
Conclusion
Docker's move toward microVMs signals a shift in how the industry views the execution of untrusted code. By providing a dedicated kernel per sandbox, Docker is moving away from the "shared kernel" risk of containers. While the API remains undocumented and subject to change, it provides a robust foundation for building secure AI coding assistants and multi-tenant SaaS plugins.