Docker Sandboxes

Summary

Docker Sandboxes is an open-source command-line tool that runs AI coding agents inside isolated microVM sandboxes, each with its own Docker daemon, filesystem, and network so agents can build containers, install packages, and modify files without touching the host. The `sbx` CLI itself is free, including for commercial use; centrally managing network and filesystem policy across an organization's developers from the Docker Admin Console requires a separate paid subscription. It installs via Homebrew, WinGet, or APT/RPM packages and works with Claude Code, Codex, Gemini CLI, OpenCode, and other agents, making it a fit for developers and platform teams who need to run autonomous coding agents without exposing their machines to arbitrary file or network access. It sits in the runtime-security and sandboxing space, layering egress policy, secrets management, and audit logging around agent execution rather than just isolating processes.

Docker Sandboxes isolates containerized applications in secure, lightweight environments for testing and development without affecting the host system.

Command line

Values are placeholders taken from each option’s declared default. Nothing is executed here — the output shown is a recording of a run that already happened.

Release history

1. v0.39.0 Aug 19, 2026 · issue 005

   Docker Sandboxes v0.39.0 adds declarative .sbxenv.yaml environments, sbx env lifecycle commands, USB passthrough, bulk sbx prune, and kit signing via cosign.

   └──▷ GET THIS VERSION
   copy

   $ git clone --branch v0.39.0 https://github.com/docker/sbx-releases.git
   # already have the repo? check out this version:
   $ git checkout v0.39.0

   └──▷ TRY IT
   Commit a reproducible sandbox definition with your project so every contributor launches the same environment with one command.
   copy

   $ sbx env run

   Define a complete sandbox environment — agent, kits, env vars, secrets, ports, and resource limits — in a project-committed file.
   .sbxenv.yaml copy

   # .sbxenv.yaml
   agent: claude
   workspace: .
   kits:
     - name: my-kit
   env:
     - NODE_ENV=development
   secrets:
     - MY_API_KEY
   ports:
     - 8080

   Passthrough a specific USB device into a sandbox for hardware-in-the-loop testing on Linux x86_64/ARM64.
   copy

   $ DOCKER_SANDBOXES_FEATURE_SANDBOX_USB=1 sbx create --usb /dev/bus/usb/001/002 my-sandbox

   • ›New sbx env run command provisions a sandbox from .sbxenv.yaml and opens an interactive session; sbx env create, sbx env exec, and sbx env rm manage the full environment lifecycle.
   • ›New .sbxenv.yaml declarative environment file defines agent, workspace, kits, environment variables, secrets, registry credentials, ports, and resource limits — committable with a project for reproducible contributor environments.
   • ›Multiple .sbxenv.yaml files can be combined for shared configuration and local overrides, with host environment variable references for machine-specific paths and credentials.
   • ›New experimental --usb flag on sbx create (enabled via DOCKER_SANDBOXES_FEATURE_SANDBOX_USB environment variable) re-attaches specified USB devices into the sandbox via usbfs on Linux x86_64/ARM64.
   • ›New sbx prune command bulk-removes stopped sandboxes with filtering by how long each has been stopped, never touching running sandboxes.
   +9 moreshow less

   • ›sbx run and sbx create now accept -e/--env and --env-file to inject environment variables into a sandbox, following docker run precedence rules.
   • ›New --provider ollama flag on sbx run --model selects the Ollama backend, replacing the former ollama/ model-name prefix.
   • ›sbx secret set and sbx secret set-custom now support dynamic secrets that resolve values from a reference or command, with options to control refreshing, verification, and error output.
   • ›Sandboxes now expose SANDBOX_NAME and SANDBOX_ID environment variables matching the values shown by sbx ls --json; the older SANDBOX_VM_ID is deprecated.
   • ›Claude Code's /remote-control endpoint can now be used inside sandboxes by enabling the claude.remoteControl setting via sbx settings set claude.remoteControl true.
   • ›New platform.images.registryMirror setting redirects Docker Hub-resolving sandbox template and kit images to an organization's registry mirror.
   • ›Kits can now be signed and verified with cosign-compatible Sigstore signatures via sbx kit sign / sbx kit verify, with optional policy enforcement at load time.
   • ›OAuth kits can now declare their credential file using the declarative credentialFile.structure form (rendered to well-formed JSON) instead of a free-form Go template.
   • ›sbx diagnose now reports free disk space on the volume holding sandbox data, detects broken/shadowed/stale SSH client configuration, and checks host virtualization support.
   └──▷ BREAKING ON UPGRADE

   • !sbx run --model no longer accepts an ollama/ prefix to select the Ollama backend; use the new --provider ollama flag instead.
2. v0.38.0 Aug 6, 2026 · issue 005

   Docker Sandboxes v0.38.0 adds MCP gateway management, kit spec v2, GPU passthrough, per-sandbox network deny rules, and local GGUF model support.

   └──▷ GET THIS VERSION
   copy

   $ git clone --branch v0.38.0 https://github.com/docker/sbx-releases.git
   # already have the repo? check out this version:
   $ git checkout v0.38.0

   └──▷ TRY IT
   Block a sandbox from reaching an internal IP range at creation time, getting a clear policy message instead of a silent timeout.
   copy

   $ sbx run --deny-network 10.0.0.0/8 claude

   Start a Claude Code session using a local GGUF model served by Ollama instead of the cloud API.
   copy

   $ sbx run --model ollama/llama3 claude

   • ›Adds sbx mcp subcommand for registering and managing remote or local MCP servers, with a built-in MCP gateway that keeps OAuth credentials on the host.
   • ›Adds dynamic MCP tools mcp-find, mcp-add, and mcp-config-set for attaching registered MCP servers to sandboxes.
   • ›Adds --deny-network HOST flag to sbx run and sbx create to record per-sandbox network deny rules at creation time, with layer-aware egress messages.
   • ›Adds sbx daemon restart subcommand to stop and restart the sandboxd daemon in the background.
   • ›Introduces kit spec schemaVersion: '2' (v2 grammar) with clearer structure for setup, permissions, agent instructions, networking, and credentials; v1 kits continue to load via the legacy path.
   +19 moreshow less

   • ›Adds DOCKER_SANDBOXES_CLONED_WORKSPACE_SIZE environment variable to configure the size of the cloned workspace volume.
   • ›Experimental: adds sbx run --gpu for NVIDIA VFIO GPU passthrough on Linux, enabled via sbx settings set feature.sandbox-gpu true.
   • ›Experimental: adds sbx run --model <name> claude to run Claude Code against a local GGUF model; prefix with ollama/ to use a model from an existing Ollama installation.
   • ›Experimental: adds proxy, proxy.sandbox, proxy.daemon, and matching no_proxy settings for separate proxy configuration scopes for sandbox and daemon traffic.
   • ›Experimental: adds proxy.integratedAuth setting on Windows to enable NTLM/Kerberos/Negotiate authentication to upstream proxies.
   • ›Experimental: adds tls.allowNegativeSerial setting (via sbx settings set tls.allowNegativeSerial true) for compatibility with TLS-inspecting proxies that issue certificates with negative serial numbers.
   • ›MCP server and tool registrations can be governed organization-wide using Cedar policies.
   • ›sbx inspect now displays custom secrets configured for a sandbox.
   • ›sbx create and sbx run show detailed structured startup progress, including environment files loaded, resources provisioned, and each kit command outcome; kit-install progress streams live during sbx create --kit.
   • ›Blocked HTTPS proxy connections now appear in sbx policy log even when the client aborts the TLS handshake.
   • ›Docker Agent and OpenCode sandboxes can authenticate GitHub Copilot requests with proxy-managed GitHub credentials.
   • ›Codex sandboxes created from the TUI prefer stored OpenAI OAuth credentials over API keys.
   • ›Kit install commands can now consume static files from files/home, including binary files.
   • ›Kits using extends correctly inherit and override the base image or build source of their parent.
   • ›Homebrew installs from a stapled .dmg artifact instead of a .tar.gz archive, improving Gatekeeper compatibility on macOS.
   • ›sbx policy allow network reports a clear error when org governance overrides a local allow rule.
   • ›Signing in refreshes organization policies in the running daemon immediately instead of waiting for the next polling interval.
   • ›IP-literal destinations denied by a CIDR rule now fail fast with a policy message instead of timing out.
   • ›Service and custom secrets are global by default, with --sandbox for sandbox scope; legacy positional and --global forms are deprecated with warnings.