Exploring Docker Sandboxes: Local Snapshots & Fixes
Docker Sandboxes gives each coding agent its own isolated microVM, so it can install packages, run commands and change files without touching your machine. You create a sandbox, work inside it, save it as a template when it is in a good state, and start new sandboxes from that template later. Most of your time with sandboxes is spent in this loop.
Version 0.48.0 makes that everyday loop smoother. These changes are not the headline features of the release, but you will notice them all the time. Sandboxes start from local snapshots without reaching out to a registry. Repeat sbx exec calls are faster because guest setup runs only once. A guest that stops responding now gives you a clear error instead of leaving you waiting.
In this post, I walk through each of these changes with real commands and output. Everything below was tested on sbx v0.48.0, so you can follow along on your own machine.
Feature 1: Local snapshots skip the registry
Creating a sandbox from a local snapshot saved with this version avoids registry requests by default, including when using the daemon API.
That matters offline, on weak Wi-Fi, behind strict proxies, or for a name that also exists on Docker Hub.
Step 1: Put some state in a sandbox
mkdir -p ws-sec && sbx create shell ./ws-sec --name demo-sec
sbx exec demo-sec -- sh -c 'echo "baked into snapshot" > /home/agent/snapshot-marker'
Step 2: Save it as a template
sbx template save demo-sec demo-snap:v1
✓ snapshotted image in sandbox demo-sec (4s)
Saved template docker.io/library/demo-snap:v1
try: sbx run --pull never -t docker.io/library/demo-snap:v1 AGENT [WORKSPACE]
sbx template ls | grep -E 'REPO|demo-snap'
REPOSITORY TAG IMAGE ID FLAVOR CREATED
docker.io/library/demo-snap v1 e2b3939f30d3 shell-docker 2m
Two gotchas:
--descriptionontemplate saveis cloud-only in 0.48.0. Locally it fails with--description and --capture-mode are only supported with --cloud.template saveasks for confirmation. Without a TTY it tells you to “pass –force”, but the flag doesn’t exist yet. Run it interactively (or underscript -q /dev/null …in CI).
Step 3: Create from the snapshot without a registry pull
mkdir -p ws-snap
time sbx create shell ./ws-snap -t demo-snap:v1 --name demo-snap
IMAGE
○ image — checking…
✓ image — ready
✓ Created sandbox demo-snap
… 2.055 total
Notice checking…, not pulling…. The image resolved locally and creation took about 2 seconds. Before the snapshot existed, the same command tried the registry and failed:
IMAGE
○ image — pulling…
error: request failed: 403 Forbidden: pull failed for image "demo-snap:v1"
And the state came along:
sbx exec demo-snap -- cat /home/agent/snapshot-marker
# baked into snapshot
Feature 2: Guest setup runs once per container start
Commands against an already-running sandbox reuse guest setup instead of repeating it on every
exec,run, orcpinvocation.
time sbx exec demo -- true
# sbx exec demo -- true 0.05s user 0.03s system 62% cpu 0.143 total
About 140 ms for a full round trip to a microVM. That makes tight loops practical, for example harness scripts that call sbx exec hundreds of times. Setup re-runs only after a container start or a daemon restart.
Feature 3: Unresponsive guests fail fast
sbx exec,sbx run,sbx cp, and SSH report an unresponsive guest with stop-and-start guidance instead of hanging.sbx lsmarks the sandbox as not responding.
If a guest wedges (out of memory, a runaway process, a kernel hang), your scripts now get an error and a fix (sbx stop then start) instead of hanging forever. sbx ls shows the state too. (I couldn’t reliably reproduce a wedged guest for a screenshot, so this item comes from the release notes.)
Feature 4: Smaller fixes I checked
Empty arguments reach the command intact:
sbx exec demo -- printf '[%s]\n' "" "x"
[]
[x]
Before 0.48.0, an empty argument was rejected, which broke wrappers that pass optional flags as "".
Workspaces whose names start with a dot:
mkdir -p .dotws && sbx create shell ./.dotws --name demo-dot --no-progress
# ✓ Created sandbox demo-dot
sbx ls labels detached sandboxes and shows a CREATED column:
SANDBOX AGENT STATUS PORTS WORKSPACE CREATED
alpn-repro shell ○ stopped (detached) /tmp/alpn-ws (missing) 1mo
catalog-lab shell ○ stopped - 6d
Also from the release notes:
sbx resetno longer leaves stray resources behind or stalls while another operation is running.- Start-up reports which files are still in use from a previous run, instead of a generic failure.
sbx cpkeeps dot-prefixed paths and restrictive directory permissions. On Windows, downloads can replace a read-only destination.- Kits that declare an agent-context directory get their instructions file written there.
- Large workload + mixin combinations no longer fail with “failed to run sandbox container”.
- A kit whose resolved lock is bigger than Docker’s label size limit can now be used.
Feature 5: Always-on cloud sandboxes from more entry points
--ttl and --on-timeout restart used to work only with sbx --cloud create. Now they also work with:
sbx move my-sandbox --to cloud --ttl 8h --on-timeout restart
sbx --cloud env create --ttl 2h --on-timeout restart # with an sbxenv.yaml
From sbx move --help:
--ttl duration Time-to-live for the destination cloud sandbox (15s to 24h, e.g. 30m, 2h; only with --to cloud)
--on-timeout string 'stop' | 'restart' | 'delete' … With 'restart' a supplied --ttl must be at least 1h.
restart keeps the destination running by stopping and immediately starting it when the TTL lapses, which is useful for long agent runs that outlive your laptop session. 0.48.0 also fixes the on_timeout response decoding error. (Cloud sandboxes bill per use, so I checked the flags but didn’t run a cloud move for this post.)
Clean up
sbx rm demo-sec demo-snap demo-dot --force
sbx template rm demo-snap:v1
Next up, Part 7: the security fixes: symlink escapes in sbx cp, mount-policy checks in kit add, and more.
References: v0.48.0 release notes · Docker Sandboxes docs