Реверс-инжиниринг недокументированного API microVM в Docker Sandbox

Команда Rivet (rivet.dev) провела реверс-инжиниринг недокументированного HTTP API режима microVM в Docker Sandboxes и создала поверх него open-source SDK - sandbox-agent-sdk. В статье задокументирован этот API, показано, как создавать microVM и обращаться к ним из шелла, а также сделана ставка: возможно, это та самая унифицированная поверхность управления microVM, которой Docker стал для контейнеров десять лет назад.

Это практическое продолжение microvm-2026, где Docker Sandboxes упоминался в обзоре платформ, но сам API ещё не был описан.

Чем на самом деле является Docker Sandboxes

Команда docker sandbox run claude ~/project похожа на docker run, но под капотом использует совершенно другую технологию. Каждый запуск поднимает microVM с отдельным ядром, а не контейнер на ядре хоста. Благодаря этому ИИ-агенту для написания кода можно выдать флаг --dangerously-skip-permissions, не подвергая хост риску. Архитектурное обоснование описано в microvm, а доминирующий сэндвич-паттерн "контейнеры внутри VM" - в matryoshka-isolation.

CLI ограничен шестью агентами из белого списка Docker (Claude, Codex, Gemini, Copilot, Kiro, Cagent). Для всего остального приходится использовать недокументированный API.

Linux не поддерживается, поскольку Docker Desktop использует там платформенно-зависимую виртуализацию (Apple Virtualization.framework на macOS, Hyper-V на Windows). Требуется вложенная виртуализация (nested virtualization). Нужен Docker Desktop 4.58+.

Поверхность API /vm

sandboxd слушает на ~/.docker/sandboxes/sandboxd.sock с тремя эндпоинтами:

• GET /vm - список всех VM
• POST /vm - создание VM
• DELETE /vm/{vm_name} - уничтожение 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"}'

Ответ содержит vm_config.socketPath, fileSharingDirectories, stateDir и ca_cert_path (CA-сертификат MITM-прокси). Имя VM формируется по шаблону {agent_name}-vm.

Остроумный подход к изоляции

Главное структурное отличие от обычного Docker: каждая microVM получает собственный демон Docker по адресу ~/.docker/sandboxes/vm/<name>/docker.sock. Привычная модель с /var/run/docker.sock - общая: любой, у кого есть доступ к сокету, управляет всеми контейнерами. Sandboxes переворачивают это: контейнеры штатно запускаются внутри microVM и полностью изолированы от хоста и других VM.

Как только сокет отдельной VM получен, всё остальное - обычный Docker:

# Build on host
docker build -t my-image:latest .
# Archive image
docker save my-image:latest > /tmp/image.tar
# Load into microVM
docker --host "unix://$VM_SOCK" load < /tmp/image.tar
# Run inside
docker --host "unix://$VM_SOCK" run -d my-image:latest

Сеть через принудительный MITM-прокси

Исходящий трафик изнутри microVM маршрутизируется через фильтрующий прокси на host.docker.internal:3128. Прокси выполняет man-in-the-middle для HTTPS ради применения политик: это означает, что контейнеры должны либо доверять CA прокси (ca_cert_path из ответа на создание), либо выставлять NODE_TLS_REJECT_UNAUTHORIZED=0 для прототипирования. По сути это уровень 3 (политики HTTP) из sandboxing-ai-agents, зашитый прямо в подложку; запустить контейнеры внутри песочницы в обход него невозможно.

Тома работают за счёт того, что workspace синхронизируется по одному и тому же абсолютному пути с обеих сторон, поэтому bind mount с хоста /Users/me/project:/Users/me/project работает сам собой.

Почему это важно

Три вывода из статьи, каждый из которых укладывается в существующие концепции вики:

1. Docker строит единую поверхность для microVM. Как и контейнеры в 2013-2015 годах, экосистема microVM сейчас фрагментирована между Firecracker, Cloud Hypervisor, Kata, libkrun и платформенными решениями. Добавление Docker'ом CLI и HTTP API за единым сокетом - тот же ход, который в своё время превратил низкоуровневую сантехнику LXC в удобный для разработчиков docker run. См. microvm-2026 с тезисом "это момент Docker для microVM", на который статья неявно делает ставку.
2. Ограничением является белый список. Недокументированный API представляет собой всю систему за вычетом белого списка имён агентов - ровно тот пробел, который должен закрывать сторонний SDK. Sandbox Agent SDK от Rivet это делает; если API сохранится, появятся и другие.
3. Ограничение macOS/Windows имеет значение. Платформенное ограничение делает это примитивом строго для ноутбука разработчика, а не для серверов - по крайней мере, пока не изменится ситуация с Docker Desktop на Linux. Для изоляции в проде на Linux сегодня по-прежнему актуален выбор из microvm-2026 (Firecracker, Cloud Hypervisor, Kata).

Предостережение о стабильности

Этот API недокументирован и может измениться. В статье Rivet это признаётся прямо: сегодня он работает на Docker Desktop 4.58+, и на этом гарантии заканчиваются. Любые инструменты поверх него зависят от сугубо внутреннего интерфейса, который Docker вполне может сломать в следующем минорном релизе. Это структурная противоположность abi-stability (где Win32 выступает надёжным ABI на Linux) - интересный антипример того, что происходит, когда апстрим не берёт на себя обязательств по контракту.

См. также

• microvm-2026 - широкий обзор использования microVM для изоляции агентов (Docker Sandboxes упомянут на уровне платформ; эта страница рассматривает API детально)
• microvm - архитектурная концепция
• matryoshka-isolation - сэндвич-паттерн "контейнеры внутри VM"
• sandboxing-ai-agents - четырёхуровневая таксономия; MITM-прокси зашит на уровне 3
• sandbox-agent-sdk - SDK от Rivet поверх этого API
• rivet-blog - сущность автора
• crabtrap - HTTP-прокси с LLM-as-judge от Brex; та же идея уровня 3, применённая к трафику, который прокси Docker'а не фильтрует
• superhq, hazmat, bubblewrap-dev-env - альтернативные варианты подложки