Docker Sandbox: Local and Cloud Setup, Limits, and Costs

Do not index

A Docker sandbox gives a coding agent an isolated environment with its own kernel and Docker Engine. Docker Sandboxes now runs locally or on Docker-managed cloud compute through the sbx CLI. For teams choosing hosted infrastructure, Agent37 offers another route: standard gVisor sandboxes for compatible workloads and full VMs for Docker builds and Compose.

The useful question is what your agent needs to do after it starts. A dependency update, a container build, and a worker that waits for jobs have different storage, lifetime, and cost requirements. This guide helps you choose the execution environment and check the parts that can break when you move beyond your laptop.

Product behavior and public rates were checked on October 30, 2026. Command examples follow the linked documentation; we did not run a paid Docker Cloud job or a comparative performance benchmark for this guide.

What a Docker sandbox isolates

Docker Sandboxes is Docker's agent execution product. Its current interface is sbx; older tutorials using docker sandbox can describe a previous release. Start with the current installation guide, which also explains that Docker Desktop and a host Docker Engine are not prerequisites.

In a local sandbox, the agent runs inside a microVM with a separate Linux kernel. A Docker Engine inside that boundary lets it build images and launch containers without receiving your host's Docker socket. The agent has sudo privileges within the VM, so the VM boundary does the isolation work. See Docker's isolation reference.

That distinction matters for build agents. Giving an agent control over a Docker daemon gives it control over the environment that daemon manages. Choose the boundary before granting access, especially when an agent will execute unfamiliar repository scripts.

The workspace is a separate decision. A direct mount exposes the selected host directory for edits. Clone mode gives the agent a private working clone but still makes the source repository readable, including ignored files. Keep credentials outside that repository. An isolated process can still damage files you deliberately share with it.

Choose where the agent should run

Local execution suits interactive work tied to your machine. Cloud execution suits tasks that need independent compute. Docker documents meaningful differences between the two environments:

Decision	Local Docker Sandboxes	Docker Cloud Sandboxes
Compute location	Your machine	Docker-managed infrastructure
Source files	Host workspace, private clone, or internal workspace	Copy files or clone a remote repository
Credentials	Local secret store	Separate cloud secret store
Outbound policy	Local and supported organization policies	Cloud account and sandbox rules
Preview services	Host port bindings	Public HTTPS endpoints

These are deployment differences from Docker's local and cloud comparison. Adding --cloud changes the backend; it does not move your local mounts, credentials, or policy automatically.

On Linux, local sandboxes require KVM. Running that local runtime inside a VM also requires nested virtualization. Cloud commands avoid that host virtualization requirement. This makes the cloud option useful when your CI runner or development machine cannot launch local microVMs.

Choose based on where files should live and who owns the machine's lifecycle. If several jobs need independent environments, give each a separate workspace and an explicit destination for its results.

Start a cloud worker with a small, inspectable task

Docker's cloud quickstart requires sbx 0.45.0 or later and activated Docker Agentic Platform access. Sign in with the subscribed Docker account, then configure the agent's cloud credential. For an Anthropic API key, the documented secret identifier is anthropic.

sbx login
sbx --cloud diagnose
sbx --cloud secret set anthropic
sbx --cloud create --name review-worker --allow-network github.com:443 claude
sbx --cloud exec review-worker git clone \
  https://github.com/docker/welcome-to-docker.git /home/agent/workspace/sample
sbx --cloud attach review-worker

Use a unique sandbox name. This example clones a public repository and attaches to the agent; it does not authorize a private repository or configure every destination a build might need.

For your first job, ask the agent to inspect the checkout and write a short report to a named file. Specify the expected path, the required sections, and that it should leave source files unchanged. Then inspect the report independently. A successful model response alone does not prove the expected artifact exists.

Only add dependency installation, container builds, and repository write access after that small path works. Each step introduces another failure mode: unavailable packages, denied network requests, insufficient disk, or a credential with the wrong scope. Keeping the first task narrow makes failures easier to diagnose.

Configure credentials and outbound access separately

Docker's cloud credential guide separates the cloud secret store from credentials configured locally. Set the needed secret before creating the worker. Avoid placing model keys in repository files or shell examples that enter source control.

Managed secrets and files containing secrets behave differently during snapshots. An interactive login can write credential files inside a sandbox. Those files can travel with a filesystem snapshot even when managed secrets stay in their separate store. Inspect the filesystem before saving a reusable template.

Network access also needs a deliberate policy. Docker's cloud network policy reference describes account defaults and additional sandbox rules, with matching denies taking precedence. A deny-all default can still have permitted destinations through applicable rules; the preset name alone is not a complete description of effective access.

For a build worker, list the model service, source host, package registries, and artifact destination it needs. Test one intended connection and one connection that should fail. Keep that check with the worker configuration so a future policy change does not silently broaden access or break dependency installation.

Decide what survives the job

Cloud sandboxes default to a one-hour expiration. Docker stops resumable sandboxes and deletes others unless you choose an action. Check account support before relying on stop/resume; volume-backed sandboxes cannot stop. Docker also documents experimental volumes whose snapshots save on exit, with the last exiting writer winning when shared. See cloud lifecycle and storage.

For a durable workflow, send important output somewhere outside the job before cleanup. A Git branch suits source changes. An artifact store suits reports, logs, and build outputs. Record the output location alongside the job identifier so a retry can tell completed work from an unfinished attempt.

Moving between local and cloud is another lifecycle operation. Docker's move command copies a filesystem snapshot into a separate destination. It does not transfer live processes, memory, host mounts, or managed secrets. The source remains a separate resource, and later changes do not synchronize.

Treat a move as a deployment: verify files, credentials, network access, and expiration at the destination before retiring the source. A successful transfer is only the start of that check.

Check Docker build compatibility before scaling

Docker currently documents a cloud limitation where docker exec can use the sandbox VM filesystem instead of the target container's filesystem. The same path affects docker compose exec and Docker healthchecks. The main process started by docker run uses the correct filesystem. See the known limitation before adopting a Compose workflow.

This deserves a specific acceptance test. Have your container create a marker file that exists only inside that container. Check whether the commands your workflow uses read the expected file, then verify the readiness checks your dependent services require. Do not use an exit code alone as the evidence.

If your pipeline depends on those affected operations, evaluate a different runtime or redesign the relevant step. A provider's ability to launch Docker does not establish compatibility with every build, debugging, or service orchestration pattern.

For the underlying runtime distinctions, our microVM versus container guide explains what the kernel boundary changes.

Compare cloud costs with the same runtime assumptions

Docker's published Small rate is $0.14 per hour for 2 vCPUs and 4 GB of memory, metered per second. Its cloud usage documentation specifies memory in GiB. Docker's billing guide says there is no recurring Agentic Platform subscription fee; inference is billed by your model provider.

Agent37 bills standard compute at $0.80 per vCPU and $0.70 per GB RAM per 730-hour month. Full VM compute is 2.5 times that rate. Disk costs $0.09 per GB per 730 hours, including time retained while stopped. These are usage rates, not a monthly subscription. See Agent37 pricing.

Runtime and resource shape	60 aggregate running hours	730 aggregate running hours
Docker Cloud Small, 2 vCPU / 4 GiB	$8.40 compute	$102.20 compute
Agent37 full VM, 2 vCPU / 4 GB, 12 GB disk retained for 730 hours	$1.98 compute and disk	$12.08 compute and disk
Agent37 standard gVisor, 2 vCPU / 4 GB, 12 GB disk retained for 730 hours	$1.44 compute and disk	$5.48 compute and disk

The VM row is the relevant Agent37 option for a Docker daemon. The standard row is for workloads that can run without one. Equal CPU counts do not establish equal throughput, memory units are reported as each provider specifies them, and this table is not a benchmark.

For the VM's 60-hour estimate, the calculation is ((2 × $0.80 + 4 × $0.70) × 2.5 × 60 / 730) + (12 × $0.09). Retaining the disk all month contributes $1.08 even when the machine runs only 60 hours.

Docker's cloud launch pricing states that volumes and egress are free and paused sandboxes incur no charge. We have not added an invented storage fee to its compute row or assumed a matched disk capacity. The table excludes promotional credits, taxes, model calls, and paid tools. Aggregate monthly hours can span multiple sessions; they do not promise an uninterrupted 730-hour Docker session.

Use a full VM when your worker needs Docker

Agent37 provides both standard gVisor and full VM sandboxes. Standard instances cannot run a Docker daemon. For image builds, Compose services, or kernel-dependent tools, select a full VM and budget its separate compute rate.

The VM reference documents the agent37-ubuntu template with Docker, Compose, and buildx installed. Its default shape is 2 vCPUs, 4 GB RAM, and 12 GB disk, matching the VM example above. VM creation requires a funded workspace.

Docker data must live on the billed persistent disk; the Ubuntu template configures that location. Custom images need their own configuration. The entrypoint runs as PID 1 without systemd, so check how your worker and background services start.

An awake Agent37 instance bills compute even while waiting. Stop it or enable auto-sleep when the workload permits; retained disk continues billing. Keep durable state on disk and test recovery rather than assuming every wake preserves running processes.

This is an alternative environment for your agent and Docker workloads. It does not imply that Docker's sbx management interface is implemented by Agent37. Use the instance API for creation and lifecycle controls.

Validate one job, then choose your deployment

Before adding concurrency, run a representative job through the complete lifecycle: obtain source, install dependencies, execute tools, collect output, stop, and recover anything you intend to retain. Include the actual container readiness check and artifact transfer your production worker will use.

Record elapsed runtime, peak storage, model spend, and whether a retry produces a duplicate result. Compare cost per completed job after that measurement. A low hourly rate helps only when the runtime supports the workflow and the worker reliably returns usable output.

If a persistent full VM fits your Docker workload, create an Agent37 sandbox, choose the VM runtime, and start with one worker. Use that job's measured needs to set disk capacity, lifecycle settings, and your next spending limit.

Docker sandbox: Run coding agents locally or in the cloud