Docker Sandboxes 0.39 makes AI-agent environments declarative with .sbxenv.yaml
Docker Sandboxes 0.39, released August 19, 2026, introduces declarative sandbox environments described in a versioned .sbxenv.yaml file and reproduced with sbx env run. Teams running AI agents in CI should adopt the format, but they should also lock down kit signing and MCP governance.
August 19, 2026. 0.39.0. One YAML file. Docker just gave AI-agent environments what the Dockerfile gave containers a decade ago: a declarative, versioned, reproducible form. Docker Sandboxes 0.39.0, published on August 19, 2026, introduces sandbox environments: a .sbxenv.yaml file declares the agent, workspace, kits, environment variables, secrets, ports, and resource limits, and sbx env run reproduces the environment exactly.
This is not cosmetic. Today a developer who launches a Claude Code agent in a sandbox rebuilds the environment by hand — or worse, lets it drift with no record. The .sbxenv.yaml file turns that implicit state into a code artifact, diffable and reviewable like everything else in the repo.
A Dockerfile for the agent, not the image
The mechanics are easy to read. A .sbxenv.yaml file declares everything that makes up the environment: the agent, the mounted workspace, the kits to install, environment variables, secrets, registry credentials, exposed ports, and resource caps. Once the file is committed to the project, any contributor runs sbx env run and gets the same sandbox, without reconstructing the configuration from memory.
The lifecycle is managed through dedicated commands: sbx env create, sbx env exec, and sbx env rm. Two properties set it apart from a simple setup script. First, files compose: a shared file can carry common configuration, overridden locally by a second file. Second, values can reference host environment variables, so machine-specific paths and credentials are never hard-coded.
The feature is flagged experimental. That is Docker’s usual signal: the format will still move, but the direction — making the agent environment as reproducible as an image build — is deliberate.
The supply chain becomes a real concern
The most consequential part of the release is not the YAML. It is that the sandbox becomes an object you sign, govern, and audit.
Three building blocks make that concrete. Kits get signed. Since 0.39.0, a kit can be signed and verified with Sigstore signatures compatible with cosign, via sbx kit sign and sbx kit verify, with optional enforcement at load time. Secrets become dynamic. sbx secret set can now resolve a value from a reference or a command, with controls over refresh, verification, and error output. Images get redirected. The platform.images.registryMirror setting points template and kit images at the organization’s registry mirror.
The trio answers a real worry: if an agent’s environment carries secrets, registry credentials, and third-party kits, it becomes a supply-chain vector in its own right. The 0.38.0 release, published on August 6, 2026, had already laid the first stone with the MCP gateway: MCP servers registered once, reused across agents, OAuth credentials staying on the host, and governance through Cedar policies.
The rest of 0.39.0
The release piles up improvements that show a maturing product. USB passthrough arrives as experimental (--usb, Linux x86_64/ARM64 only), behind the DOCKER_SANDBOXES_FEATURE_SANDBOX_USB flag. The Ollama backend is selected with --provider ollama rather than a prefix on the model name. Stopped sandboxes are cleaned up in bulk with sbx prune. Each sandbox identifies itself through the SANDBOX_NAME and SANDBOX_ID variables, with the older SANDBOX_VM_ID deprecated. And Claude Code’s /remote-control now works inside a sandbox via sbx settings set claude.remoteControl true.
Two fixes deserve attention. First, kits declaring a persistent volume without a size now get 512 MB instead of 50 GB, which sharply reduces host disk usage. Second, Claude sandboxes use about 3.9 GB less disk on the host machine. Across a fleet of workstations or runners, those two details change the real bill.
MicroVM isolation, not just containers
The security promise of sandboxes rests on a deliberate architectural choice: each sandbox runs in a microVM, not a plain container. The workspace is mounted from the host, networking is sandbox-scoped, and credentials — including OAuth tokens for MCP servers — stay on the host, never copied into the environment.
That is what makes it acceptable to run code produced by a third-party agent. An agent that fixes code and opens a pull request runs operations no one has reviewed line by line: the microVM bounds the blast radius of a drift, and network policies, such as the --deny-network HOST flag introduced in 0.38.0, block exfiltration. The sandbox becomes a traceable trust boundary, not one more container in the pipeline.
The corollary is a governance load. As kits get signed, secrets become dynamic, and MCP servers centralize in the sbx mcp gateway, the security team finally gains the control points it was missing: a Cedar policy can refuse the registration of an MCP server or the call of a specific tool, without touching the agents’ code.
Why CI is the real battleground
Docker’s companion post, Running AI agents in GitHub Actions with Docker Sandboxes, gives the canonical use case: an isolated agent that runs Testcontainers tests, fixes code, and opens a draft pull request. That is where .sbxenv.yaml earns its keep. In CI, the agent’s environment must be identical on every run, auditable afterward, and reproducible by any reviewer. A versioned file meets all three requirements, where an interactively created sandbox meets none.
The trade-off is a wider attack and governance surface: every third-party kit, every MCP server, and every dynamic secret becomes a link in the chain. Sigstore signing and Cedar policies are not comfort options — they are the minimum controls once the agent touches production code.
The daily workflow
To measure what 0.39.0 changes, walk through a typical day. The developer starts with sbx env run: the sandbox is created from the repository’s .sbxenv.yaml, installs the declared kits, and opens an interactive session. Switching models no longer depends on a name prefix — sbx run --model now selects the Ollama backend via --provider ollama. Sensitive secrets are no longer typed by hand: sbx secret set resolves them from a reference or a command, with controlled refresh.
Maintenance aligns with a container fleet. sbx prune cleans up stopped sandboxes in bulk, never touching a running one, and filters on how long each has been stopped. sbx diagnose reports free disk space and detects broken or shadowed SSH configuration. And when the host cannot provide a hypervisor — say a virtual machine without nested virtualization — the error message says so clearly instead of failing after thirty seconds.
It is this mesh of small commands that turns the sandbox from a gadget into a team tool: every step is scriptable, every state is inspectable, and every failure has a diagnosis.
Verdict
If your AI agents run in CI or on shared runners, adopt .sbxenv.yaml now: the reproducibility and traceability it brings outweigh its experimental status. At the same time, enforce kit-signature verification at load and govern MCP servers with policies, before an unsigned third-party kit becomes the entry point.
If you only use sandboxes occasionally, locally, wait for a release that stabilizes the YAML format, but watch the direction: the agent environment is becoming a code artifact like any other. Teams that integrate it early will have a head start when Docker flips the stable flag.
References
- Docker Sandboxes release notes — 0.39.0, August 19, 2026
- Sandbox environments — Docker Docs, accessed August 23, 2026
- Running AI agents in GitHub Actions with Docker Sandboxes — Docker Blog, accessed August 23, 2026
- docker/sbx-releases — v0.39.0, August 19, 2026