Skip to main content

Docker Sandboxes

Last Updated​

  • Date: 2026-03-18
  • Version: 1.0.0
  • Scope: Structured overview of Docker Sandboxes architecture, components, runtime flow, and operational boundaries.

What Changed​

v1.0.0
  • First version of the Docker Sandboxes overview.

Summary​

Docker Sandboxes run AI agent and other unpredictable workloads inside a container within a microVM-backed environment with a dedicated private Docker daemon. They also have advanced egress controls mediated by a proxy running inside the sandboxd daemon process running on the host. This matters because it reduces host blast radius and gives operators a central policy control point for outbound traffic.

Note that while there is a good amount of documentation on Docker's website about the sandbox feature, it is not open source and a lot of this information was derived through reverse engineering / observing the process.

Key Capabilities​

  • Stronger isolation boundary than direct host execution (microVM-backed runtime).
  • Private in-VM Docker daemon per sandbox.
  • Policy-driven egress control with auditable daemon/runtime logs.
  • CLI-driven network policy updates (docker sandbox network proxy ...) via daemon API.
  • Proxy trust/certificate wiring for mediated HTTPS in workload environments.
  • Agents API-key environment variables' values are never exposed within the container but are instead resolved when going through the egress proxy.

System Overview​

Components​

ComponentBinary / PathSocketsLogsConfig / State
Docker CLI/usr/local/bin/docker———
docker-sandbox plugin (client + daemon modes)- ~/.docker/cli-plugins/docker-sandbox (symlink)
- /Applications/Docker.app/Contents/Resources/cli-plugins/docker-sandbox		———
sandboxd daemon — VM registry/lifecycle, in-process proxy, context wiringRuns as docker-sandbox in daemon mode~/.docker/sandboxes/sandboxd.sock~/Library/Containers/com.docker.docker/Data/log/host/docker-sandbox.log- ~/.docker/sandboxes/image-cache/
- ~/.docker/sandboxes/vm/<sandbox-name>/
- ~/.docker/sandboxes/vm/<sandbox-name>/metadata.json
- ~/.docker/sandboxes/vm/<sandbox-name>/proxy-config.json
- ~/.docker/sandboxes/vm/<sandbox-name>/daemon.json
Docker Desktop backend/Applications/Docker.app/Contents/MacOS/com.docker.backend—~/Library/Containers/com.docker.docker/Data/log/host/com.docker.backend.log—
com.docker.krun — microVM runtime launching sandbox VMs~/.container-platform/com.docker.krun~/.docker/sandboxes/vm/<sandbox-name>/eth-krun.sock- ~/.docker/sandboxes/vm/<sandbox-name>/container-platform.log
- ~/.docker/sandboxes/vm/<sandbox-name>/console.log
- ~/Library/Containers/com.docker.docker/Data/log/host/com.docker.virtualization.log		—
LinuxKit guest — guest OS boundary where private runtime services boot~/.docker/sandboxes/vm/<sandbox-name>/Docker.raw (VM disk image)———
containerd (guest) — guest container runtime serviceIn-guest process~/.docker/sandboxes/vm/<sandbox-name>/docker.sock (internal plumbing)——
dockerd (guest) — private Docker daemon inside sandbox VMIn-guest process~/.docker/sandboxes/vm/<sandbox-name>/docker-public.sock (host bridge)——
In-daemon proxy / cert manager — goproxy-based, HTTP/HTTPS egress mediationEmbedded in sandboxd process; listens on 127.0.0.1:<ephemeral-port>—~/Library/Containers/com.docker.docker/Data/log/host/httpproxy.log- ~/.docker/sandboxes/vm/<sandbox-name>/proxy_cacerts/proxy-ca.crt
- ~/.docker/sandboxes/vm/<sandbox-name>/proxy_cacerts/proxy-ca.key
gvisor/forwarder — runtime networking forwarderPart of container-platform layer—~/.docker/sandboxes/vm/<sandbox-name>/container-platform.log—
Workspace virtiofs share — host workspace mounted into guest VMHost workspace directory———

Architecture​

How It Works (Flow)​

  1. User runs docker sandbox ...; Docker invokes the docker-sandbox cli plugin.
  2. Plugin talks to ~/.docker/sandboxes/sandboxd.sock and hits daemon API endpoints for VM lookup/create.
  3. sandboxd decides reuse vs create, writes sandbox state (metadata.json, proxy config), and starts its in-process proxy listener/cert handling.
  4. Container-platform launches ~/.container-platform/com.docker.krun; LinuxKit boots and workspace is mounted via virtiofs.
  5. Guest containerd and private dockerd start; host-side docker-public.sock and context are created.
  6. Workload traffic inside sandbox uses host.docker.internal:3128 (resolved in sandbox to 192.168.127.254:3128).
  7. Runtime networking/plumbing forwards this endpoint to host-local proxy listener(s) (127.0.0.1:<port>, observed 127.0.0.1:63838).
  8. Policy changes from docker sandbox network proxy ... are applied through daemon API (POST /network/proxyconfig).

Use cases​

  • Running autonomous/semi-autonomous coding agents or any other workloads whose behaviour you cannot trust.

References​

Authoritative links: