Cheat sheets

Docker Sandboxes for Agents

Run an agent in a microVM, control its network and keys, get its commits back. sbx 0.47.0, docker-agent 1.149.0.

  • Concepts and terms
  • Tasks and commands
  • Annotated code
  • Diagrams
  • Defaults and numbers
  • Troubleshooting
  • Questions and tips

Source

What runs where#

socketstartsrunsHTTPS_PROXYswapallowedmountsbx CLIhostsandboxdsandboxd.sock, daemon.logSecret storemacOS KeychainSandbox microVMown kernel, private DockerEngineAgentuser agent, uid 1000Forward proxygateway.docker.internal:3128Workspacevirtiofs, same absolutepathAllowed hostspolicy rulessocketstartsrunsHTTPS_PROXYswapallowedmountsbx CLIhostsandboxdsandboxd.sock,daemon.logSecretstoremacOSKeychainSandboxmicroVMownkernel,privateDockerEngineAgentuseragent, uid1000Forwardproxygateway.docker.internal:3128Workspacevirtiofs,sameabsolutepathAllowedhostspolicyrules

From docker-sandboxes-101 §1.1, docker-sandboxes-101 §2.2, docker-sandboxes-101 §3.4, docker-sandboxes-101 §3.5, docker-sandboxes-101 §2.4

One request leaves the sandbox#

1sbx createsandboxd pulls the template and boots themicroVM.2Agentsends the request to the forward proxy on thehost.3Authorizera matching deny wins. No matching allow is animplicit deny.4Blockedthe proxy answers 403 inside TLS with "Approvalrequired".5Allowedthe proxy tunnels the host as forward-bypass.6Bound secretthe proxy swaps the sentinel for the storedvalue.7policy logone row per host with proxy type and rule.

From docker-sandboxes-101 §2.1, docker-sandboxes-101 §3.3, docker-sandboxes-101 §3.4, docker-sandboxes-101 §3.5

Sandbox lifecycle#

TaskCode
Create on a repositorysbx create shell <path> --name <name>
Attach againsbx run --name <name>
Run a command as rootsbx exec -u root <name> sh -c '<cmd>'
Copy a file insbx cp <host-file> <name>:/tmp/in.txt
Publish a portsbx ports <name> --publish 18081:8080
Stop and keep statesbx stop <name>
Remove stopped sandboxessbx prune --force

From docker-sandboxes-101 capture: 04-create.txt, docker-sandboxes-101 capture: 07-template-save.txt, docker-sandboxes-101 capture: 06-cp.txt, docker-sandboxes-101 capture: 05-ports.txt, docker-sandboxes-101 capture: 04-stop.txt, docker-sandboxes-101 capture: 04-prune.txt, docker-sandboxes-101 capture: 04-ls.txt, docker-sandboxes-101 §2.1

Secrets, MCP and health#

TaskCode
Bind a secret to hostssbx secret set-custom --host <host> --env <VAR> --value <value>
Find keys in host envsbx secret import --dry-run
Register an MCP serversbx mcp add <name> --url <url>
Attach it to a sandboxsbx mcp load <name> --sandbox <sandbox>
Run the 13 checkssbx diagnose
Save a templatesbx template save <name> <tag> --output <file>.tar
Run an agent file in a sandboxdocker-agent run --sandbox --exec <agent-file> '<prompt>'

From docker-sandboxes-101 capture: 10-set-custom.txt, docker-sandboxes-101 capture: 10-import-dry-run.txt, docker-sandboxes-101 capture: 11-mcp-add.txt, docker-sandboxes-101 capture: 11-load.txt, docker-sandboxes-101 capture: 02-daemon-status.txt, docker-sandboxes-101 capture: 02-diagnose.txt, docker-sandboxes-101 capture: 07-template-save.txt, docker-sandboxes-101 capture: 27-sandbox-run.txt

Clone mode round trip#

sbx create --clone shell <repo> \private clone, host repo read-only
--name <name>source at /run/sandbox/source
sbx exec <name> sh -c '<edit and git commit>'agent commits in the clone
git -C <repo> remote -vsbx added sandbox-<name>
git -C <repo> fetch sandbox-<name>bring the commits back
sbx rm --force <name>VM, state and scoped secrets go

From docker-sandboxes-101 capture: 08-clone-create.txt, docker-sandboxes-101 capture: 08-clone-host.txt, docker-sandboxes-101 capture: 08-clone-rm.txt, docker-sandboxes-101 §3.2, docker-sandboxes-101 §2.1

What the agent sees inside#

CommandWhat it does
HTTPS_PROXY=http://gateway.docker.internal:3128Forward proxy for HTTP and HTTPS
ANTHROPIC_API_KEY=proxy-managedSentinel. The real key stays on the host
M101_RECV_KEY=sbx-cs-<rand>Custom secret placeholder
SSH_AUTH_SOCK=/run/ssh-agent.sockHost SSH agent, forwarded by default
forward-bypassLog proxy type. Tunnel, no inspection
transparentLog proxy type. Other TCP, no injection
"deny_kind": "explicit"A rule denied it. implicit means no allow

From docker-sandboxes-101 capture: 04-env.txt, docker-sandboxes-101 capture: 10-env-sentinel.txt, docker-sandboxes-101 capture: 09-policy-log.txt, docker-sandboxes-101 §3.4, docker-sandboxes-101 §3.3

Debug a blocked host#

sbx policy init balancedonce, before the first sandbox
sbx create shell --name m101-policyno workspace mount
sbx exec m101-policy sh -c \
'curl -sS --max-time 10 https://example.com'Approval required
sbx policy log m101-policyforward, default deny
sbx policy allow network \
--sandbox m101-policy example.comrule for one sandbox
sbx policy check network example.com \
--sandbox m101-policy --verbose --jsonread allowed, rule

From docker-sandboxes-101 capture: 03-policy-init.txt, docker-sandboxes-101 capture: 09-create.txt, docker-sandboxes-101 capture: 09-blocked-by-rule.txt, docker-sandboxes-101 capture: 09-policy-log.txt, docker-sandboxes-101 capture: 09-allow.txt, docker-sandboxes-101 capture: 09-rm-allow.txt, docker-sandboxes-101 capture: run.py

Defaults#

SettingDefaultNote
--name<agent>-<workdir>Set it, so two agents stay apart
-m, --memory50% of host memoryClamped from 512 MiB to 32 GiB
--pullalwaysAlso missing or never
--skillsreadonlyAlso off or readwrite
secret set --refresh55mRefresh for a dynamic source
ssh.agentForwardingEnabledtrueTurn off for agents you do not trust
sandbox.disk.dockerVolume10gSize of /var/lib/docker
kit.allowedSources["docker.io/"]Allowed remote kit sources

From docker-sandboxes-101 §R1, docker-sandboxes-101 §R3

Key concepts#

Sandbox
a microVM with its own kernel and a private Docker Engine.
Clone mode
--clone. The agent works on a private clone. Commits return through a remote.
Preset
allow-all, balanced or deny-all, set once with sbx policy init.
Policy scope
global for all sandboxes, or one sandbox with --sandbox.
Deny wins
a deny rule takes precedence over an allow for the same host.
Sentinel
the placeholder the agent sees in place of a secret.

From docker-sandboxes-101 §R8, docker-sandboxes-101 §3.3

Troubleshooting#

SymptomCauseFix
Approval required for example.com:443.No allow rule matchessbx policy allow network --sandbox <name> <host>
curl to ::1 fails with exit 7Port published as tcp4Publish 8080/tcp for both families
copying between sandboxes is not supportedcp needs a host sideCopy through the host
Deny conflicts with existing allow ruleAllow and deny in one scopesbx policy rm network --id <uuid> first
No API key from ~/.zshrcHost environment not read since v0.35.0sbx secret set or sbx secret import
ensure daemon: daemon exited unexpectedlysandboxd problemsbx daemon status --json, read daemon.log

From docker-sandboxes-101 capture: 09-blocked.txt, docker-sandboxes-101 capture: 05-ports-curl.txt, docker-sandboxes-101 capture: 06-cp.txt, docker-sandboxes-101 capture: 09-deny-conflict.txt, docker-sandboxes-101 capture: 09-rm-allow.txt, docker-sandboxes-101 capture: 07-template-save.txt, docker-sandboxes-101 §2.2, docker-sandboxes-101 §3.5, docker-sandboxes-101 §3.2, docker-sandboxes-101 §2.4

Q&A#

Do I need Docker Desktop?
No. You need sbx login. Containers of the agent never show in host docker ps.
stop or rm?
sbx stop keeps state. sbx rm deletes the sandbox, its state and scoped secrets.
Does a host allow block a gist upload?
No. A host allow passes any method, path and body.
Does the agent see my key?
No. It sees proxy-managed. The proxy adds the key after the VM.

From docker-sandboxes-101 §1.1, docker-sandboxes-101 §2.1, docker-sandboxes-101 §3.4, docker-sandboxes-101 §3.5, docker-sandboxes-101 §3.2

Tips#

  • Set memory, ports, skills and static MCP servers at creation. A re-attach ignores them.
  • Run sbx prune --dry-run before a prune.
  • Add narrow rules with --sandbox. Keep global rules for hosts every agent needs.
  • Store keys with sbx secret set, never with -e KEY.
  • Bind a custom secret to exact hosts. The proxy replaces the placeholder anywhere.

From docker-sandboxes-101 §2.1, docker-sandboxes-101 §3.3, docker-sandboxes-101 §3.5, docker-sandboxes-101 §2.4, docker-sandboxes-101 §2.2