DEV Community

Cover image for Stop Running AI Agents on Your Host — Master Docker Sandboxes in One Guide
Koti Vellanki
Koti Vellanki

Posted on

Stop Running AI Agents on Your Host — Master Docker Sandboxes in One Guide

#docker #ai #agents #containers

Blog 1 — Docker Sandboxes Series

Docker Sandboxes from Zero — Why They Exist, Setup, First Sandbox & Basic Isolation

What We Are Building

By the end of this blog you will understand why AI coding agents are risky on a normal laptop, install the sbx CLI, launch your first isolated sandbox, see the isolation boundary with your own eyes, and clean everything up properly.

No paid AI subscription is required. We use the shell agent.

Why This Matters

AI coding agents are useful because they act on their own. They install packages, edit files, run tests, build Docker images, and sometimes run commands you would never type yourself.

If you run them directly on your machine they can:

  • Change or delete files outside the project
  • Install system packages that break your setup
  • Talk to your host Docker daemon
  • Reach any network destination
  • Accidentally expose credentials already present in your environment

Normal containers share the host kernel. Mounting the Docker socket gives the agent the same power as you. Full virtual machines are heavy and slow to start.

Docker Sandboxes solve this by giving each agent its own lightweight microVM.

Before vs After — The Core Problem

before-aftersandbox

Explanation of the diagram

Left side shows the dangerous default: the agent runs with the same power as you on the host.

Right side shows the sandbox approach: the agent is locked inside a microVM. Only the project folder is shared. Everything else stays isolated.

What You Should Know Before Starting

  • Comfortable with a terminal
  • Free Docker account
  • Supported platform:
    • macOS
    • Windows 11 with Windows Hypervisor Platform enabled
    • Ubuntu 24.04+ with KVM working

Docker Desktop is not required. (No blocker for corporates...)

Environment Setup

Install the sbx CLI

macOS

brew trust docker/tap
brew install docker/tap/sbx
Enter fullscreen mode Exit fullscreen mode

Ubuntu / Linux

curl -fsSL https://get.docker.com | sudo REPO_ONLY=1 sh
sudo apt-get install docker-sbx
sudo usermod -aG kvm $USER
newgrp kvm
Enter fullscreen mode Exit fullscreen mode

Windows

winget install -h Docker.sbx
Enter fullscreen mode Exit fullscreen mode

Verify:

sbx version
Enter fullscreen mode Exit fullscreen mode

sbx version

Sign in 

sbx login
Enter fullscreen mode Exit fullscreen mode

sbx login

Step 1 — Create a Simple Project 

mkdir -p ~/sandbox-lab
cd ~/sandbox-lab
echo "hello from the host" > note.txt
Enter fullscreen mode Exit fullscreen mode

sbx creating project

Step 2 — Launch the First Sandbox 

sbx run --name first-sandbox shell
Enter fullscreen mode Exit fullscreen mode

sbx launch first sandbox

On the first run choose the Balanced network preset (recommended).

You are now inside a Bash shell that lives inside the microVM.

Step 3 — Look Around Inside the Sandbox 

pwd
ls -la
cat note.txt
whoami
docker version
Enter fullscreen mode Exit fullscreen mode

inside sandbox

Open a second terminal on the host:

sbx ls
Enter fullscreen mode Exit fullscreen mode

sbx ls

High-level Sandbox Architecture (what you just created)

sbx architecture

Explanation of the diagram

You talk to the sbx CLI. The CLI starts a microVM. Inside that microVM the agent, its Docker daemon and its filesystem live. The only connection back to the host is the workspace folder you chose.

Step 4 — Prove the Isolation

Inside the sandbox:

echo "written from inside the sandbox" >> note.txt
echo "created inside sandbox" > from-sandbox.txt
docker pull alpine:latest
docker images
Enter fullscreen mode Exit fullscreen mode

inside sbx

On the host:

cat ~/sandbox-lab/note.txt
ls ~/sandbox-lab
docker images | grep alpine || echo "alpine image is NOT on the host"
Enter fullscreen mode Exit fullscreen mode

on host

Note: Ideally you should see message alpine image is NOT on the host as output but as I'm using postgres alpine image for another application it showed up but you can observe this alpine images is not what we pulled in the sandbox.

Isolation Boundary Diagram

isolation boundary

Explanation of the diagram

Files in the project folder move both ways (live mount).

The sandbox Docker daemon has no path to the host Docker daemon. Images and containers stay inside the microVM.

What Just Happened Internally

The microVM has its own kernel. The agent has full power inside the microVM (including sudo). Network traffic goes through a host-side proxy that enforces the policy you chose. Credentials (when we use them later) are injected by the proxy and never stored inside the VM.

Let’s Break It (Gently)

Inside the sandbox try:

curl -I https://koti.dev
Enter fullscreen mode Exit fullscreen mode

policy

If it is blocked under Balanced policy, that is expected.

On the host allow it:

sbx policy allow network koti.dev
Enter fullscreen mode Exit fullscreen mode

allow policy

Retry. It should now work.

policy worked

Production Thinking

In real work I always:

  • Start with Balanced or stricter
  • Give every sandbox a clear name
  • Prefer --clone for experimental or untrusted agent work
  • Treat sbx rm as the normal way to finish a session

Security Considerations

  • The agent is powerful inside the sandbox. Do not treat it like a normal restricted container.
  • The workspace is read-write by default.
  • Never put long-lived secrets as normal environment variables inside the sandbox (we cover the proper way in the next blog).

Common Mistakes

  • Forgetting the kvm group on Linux → sandbox will not start
  • Skipping sbx login
  • Expecting host Docker to see images built inside the sandbox
  • Leaving many sandboxes running → disk fills up

Troubleshooting

Problem Quick check Fix
sbx not found Installation Re-run install steps
KVM error on Linux `lsmod \ grep kvm`
Sandbox stuck sbx ls sbx stop then sbx rm
Need clean state — sbx reset (destructive)

Also useful:

sbx diagnose
Enter fullscreen mode Exit fullscreen mode

Cleanup 

sbx stop first-sandbox
sbx rm first-sandbox
sbx ls
Enter fullscreen mode Exit fullscreen mode

Your ~/sandbox-lab folder remains. Only the microVM is gone.

What We Learned

  • AI agents need strong isolation. MicroVMs give that isolation without the weight of full VMs.
  • The sbx CLI is the current free way to use Docker Sandboxes.
  • Workspace is shared; almost everything else stays inside the sandbox.
  • You can now install, launch, inspect and cleanly remove a sandbox.

What’s Next?

In Blog 2 we take full control of the environment: how files persist, the difference between direct mount and clone mode, network policies in depth, and the safe way to inject secrets so the agent never sees the real values.

References

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

Top comments (0)