Security Model, Troubleshooting, Limitations & Production Best Practices

Blog 5 — Docker Sandboxes Series (Final)

What We Are Building

This final blog brings everything together.

You will:

• Clearly understand the five isolation layers and the real trust boundary
• Know exactly what is protected and what is still shared
• Diagnose real problems with sbx diagnose and policy logs
• See realistic limitations so you do not over-promise
• Leave with a practical production checklist and team runbook

After this blog you should be able to introduce Docker Sandboxes to a real team with confidence and honest expectations.

Why This Matters

You now know how to launch agents, control files, network and secrets, build containers inside the sandbox, use templates, kits, ports and SSH.

The last missing piece is judgement.

An experienced engineer needs to answer:

• What can still go wrong?
• Where does the protection stop?
• How do I debug when something fails?
• When should I not use a sandbox?
• How do I run this safely with a team?

This blog answers those questions with practical detail.

What You Should Know Before Starting

• Blogs 1–4 completed
• At least one working sandbox from previous labs

The Five Isolation Layers (Security Model)

Docker Sandboxes protect the host with five layers. The primary trust boundary is the microVM.

High-level Trust Boundary

Explanation

Everything inside the microVM is fully controlled by the agent (including sudo).

The hypervisor prevents the agent from reaching anything on the host except what you deliberately share (workspace, allowed network via proxy, injected credentials).

Layer-by-layer summary

1. Hypervisor isolation
   
   Separate kernel. No shared processes or memory with the host. Removing the sandbox deletes the entire VM.

2. Network isolation
   
   All HTTP/HTTPS goes through a host-side proxy that enforces deny-by-default policy.
   
   Raw TCP, UDP and ICMP are blocked at the network layer.
   
   Sandboxes cannot talk to each other or to host localhost.

3. Docker Engine isolation
   
   Each sandbox has its own Docker daemon. There is no path to the host Docker socket.

4. Workspace isolation (optional but important)

   • Default = direct read-write mount (agent can change your real files)
   • --clone = private clone inside the VM + read-only mount of your repo (much safer)

5. Credential isolation
   
   Secrets stay in the OS keychain on the host. The proxy injects them into HTTP headers. Raw values never enter the microVM.

What the agent can do inside the microVM

• Install any package with sudo
• Build and run any containers with its own Docker
• Read/write the workspace (or the private clone)
• Make network calls to domains you have allowed

What is protected

• Host filesystem outside the workspace / shared skills store
• Host Docker daemon
• Host network and localhost
• Any domain not explicitly allowed
• Direct communication between sandboxes
• Raw secrets

Hands-on: Controlled Breakage & Recovery

1. Confirm the isolation layers yourself

# Start a clean sandbox
sbx run --name sec-test --clone shell

# Inside the sandbox try things that should fail
ls /home          # only the agent user
docker info       # works — but it is the sandbox daemon
curl -I https://example.com   # may be blocked depending on policy

On the host:

docker images | grep -i alpine || echo "Host Docker is clean"

2. Run diagnostics

sbx diagnose

This checks CLI, daemon, storage, authentication and gives suggested fixes.

Also useful:

sbx policy ls
sbx policy log
sbx ls

3. Simulate a common failure

Intentionally block a domain the agent needs, watch it fail, then fix it:

sbx policy deny network registry.npmjs.org
# try npm install inside the sandbox → fails
sbx policy allow network "*.npmjs.org"
# try again → works

Realistic Limitations

Be honest with your team about these:

• Resource overhead — each sandbox is a microVM + its own Docker daemon. Disk and memory usage grows with images and packages. Clean up regularly with sbx rm.
• Direct mount risk — without --clone the agent can modify Git hooks, CI files, .env, IDE configs, etc. Always review changes.
• Clone mode still reads your files — including untracked .env files. Secrets should never live in the workspace.
• Non-HTTP protocols — SSH, raw TCP, UDP are blocked by default. Limited IP:port exceptions exist but are not free-for-all.
• Organisation governance (paid) completely replaces local sbx policy rules. Local allow rules become inactive.
• Filesystem performance — large repositories in direct mode can feel slower. Virtiofs caching helps; you can disable it if needed.
• No shared Docker layers between sandboxes — each keeps its own cache.
• MCP servers that run on the host are outside the microVM boundary. Treat them as trusted host integrations.

Production Best Practices & Team Runbook

Recommended defaults for a team

# Always prefer clone mode for agent work
sbx run --name feature-xyz --clone claude

# Keep network tight
sbx policy set-default balanced   # or stricter
# then add only what is needed

# Secrets only via sbx secret
sbx secret set anthropic
sbx secret set github -t "$(gh auth token)"

# Named sandboxes + clean up
sbx rm feature-xyz   # when the task is finished

Simple team runbook (copy-paste ready)

1. Install sbx and run sbx login + sbx setup ssh once.
2. Prefer --clone for any non-trivial agent session.
3. Use named sandboxes (--name).
4. Store all secrets with sbx secret.
5. Start from Balanced (or Locked) network policy and open only required domains.
6. Connect VS Code / Cursor via *.sbx when you need a full editor.
7. Publish ports only when you need to open a service in the browser.
8. When the task is done: sbx stop → sbx rm.
9. Weekly: sbx ls and remove anything older than a few days.
10. If something is broken: sbx diagnose first.

Combining with Docker Hardened Images

Inside the sandbox you can (and should) build your application images from Docker Hardened Images (dhi.io/...). The sandbox’s own Docker daemon will pull them after you have authenticated to dhi.io on the host. This gives you both strong agent isolation and secure base images.

If you haven't heard or tried Docker Hardened Images (DHI) yet, don't worry similar to Sandboxes I'll be publishing short blog series on DHI as well.

Common Mistakes (Final List)

• Running agents in direct mode on important repositories without review
• Leaving secrets in .env files that the agent can read
• Opening network too widely (“just allow **”)
• Forgetting to remove old sandboxes → disk fills up
• Expecting local policy rules to work when organisation governance is active
• Treating the sandbox as a full replacement for a proper CI environment

Troubleshooting Quick Reference

Symptom	First command	Typical fix
Anything strange	sbx diagnose	Follow the suggestions
Network blocked	sbx policy log	sbx policy allow network <domain>
Cannot connect editor	sbx setup ssh	Re-run setup
Disk full	sbx ls	sbx rm old sandboxes
Agent cannot authenticate	sbx secret ls	Re-set the secret
Slow file operations	Check if direct mount	Try --clone or disable virtiofs cache
Policy changes ignored	sbx policy ls	Check for “Managed by ”
Completely broken state	—	sbx reset (destructive, keeps secrets optional)

Cleanup

sbx stop sec-test 2>/dev/null || true
sbx rm sec-test 2>/dev/null || true
# Review remaining sandboxes
sbx ls

What We Learned in the Whole Series

1. Why microVM isolation exists and how to install/use sbx
2. Full control over workspace, persistence, network and secrets
3. Running real coding agents + isolated Docker safely
4. Templates, kits, ports, SSH and daily workflows
5. The exact security model, real limitations and how to run this in production

You now have a complete, practical Zero-to-Hero path for Docker Sandboxes.

Final Production Checklist

• [ ] Everyone on the team has sbx installed and logged in
• [ ] Default is --clone for agent sessions
• [ ] Secrets only via sbx secret
• [ ] Network policy starts restrictive
• [ ] Named sandboxes + regular cleanup
• [ ] VS Code / Cursor connected via SSH when needed
• [ ] sbx diagnose is the first troubleshooting step
• [ ] Team knows the limitations (especially direct mount and resource use)

What’s Next?

You have finished the Docker Sandboxes series.
I'll see you again with another interesting series.

References

• https://docs.docker.com/ai/sandboxes/security/ — security model overview
• https://docs.docker.com/ai/sandboxes/security/isolation/ — detailed isolation layers
• https://docs.docker.com/ai/sandboxes/troubleshooting/ — diagnostics and common fixes
• https://docs.docker.com/ai/sandboxes/governance/ — organisation governance
• https://docs.docker.com/ai/sandboxes/faq/ — practical limitations and tips
• https://docs.docker.com/ai/sandboxes/architecture/ — comparison with other approaches

All technical claims and commands verified against current official documentation (August 2026).

---