DEV Community

Cover image for Docker Sandbox Workspace, Network Policies & Secrets — Complete Practical Guide (2026)
Koti Vellanki
Koti Vellanki

Posted on

Docker Sandbox Workspace, Network Policies & Secrets — Complete Practical Guide (2026)

#ai #docker #containers #agents

Blog 2 — Docker Sandboxes Series

Docker Sandbox Workspace, Network Policies & Secrets — Complete Practical Guide (2026)

What We Are Building

By the end of this blog you will fully control three critical things:

  1. How the agent sees and changes your files (direct mount vs clone mode)
  2. What survives when you stop a sandbox and what is deleted when you remove it
  3. Exactly which network destinations the agent can reach, and how secrets are injected safely without ever entering the microVM

You will break things on purpose, fix them, and leave with a clean, controlled environment ready for real agents.

Why This Matters

In Blog 1 we launched a sandbox and saw basic isolation. That is not enough for real work.

If the agent can freely rewrite your entire project and can reach any website, one wrong command can still cause pain.

If secrets sit as environment variables inside the sandbox, the agent (or any code it runs) can read them.

If you do not understand what survives a stop, you will keep losing installed packages or Docker images.

This blog gives you the practical controls an experienced engineer actually uses every day.

What You Should Know Before Starting

  • Blog 1 completed (sbx installed and working)
  • A project directory (we will reuse or recreate ~/sandbox-lab)
  • Optional but useful: gh CLI if you want to test GitHub secrets

Environment Setup

Make sure you are in a clean state from Blog 1:

sbx ls

# If any sandbox is still running, stop and remove it
sbx stop first-sandbox 2>/dev/null || true
sbx rm first-sandbox 2>/dev/null || true
Enter fullscreen mode Exit fullscreen mode

cleaning up old sbx

Create a fresh project:

mkdir -p sandbox-lab
cd sandbox-lab
git init
echo "hello from host - direct mode" > note.txt
git add . && git commit -m "initial"
Enter fullscreen mode Exit fullscreen mode

creating sbx project

Step 1 — Direct Mount (Default Behaviour)

Launch a normal sandbox:

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

launching direct sbx

Inside the sandbox:

pwd
cat note.txt
echo "changed by agent" >> note.txt
echo "new file from agent" > agent-file.txt
ls -la
Enter fullscreen mode Exit fullscreen mode

inside sbx

Exit the sandbox (Ctrl+D or exit) or open terminal in the sandbox directory.

On the host:

ls 
cat note.txt
Enter fullscreen mode Exit fullscreen mode

ls cat

You see the changes immediately. This is the default direct mount.

Direct Mount Diagram

direct mount

Explanation

The project folder on your host is mounted directly into the microVM at the exact same path. Any change the agent makes appears on your host instantly, and vice versa. There is no copy and no sync delay.

Step 2 — Clone Mode (Safer Isolation for Files)

Remove the previous sandbox:

sbx stop direct-sandbox
sbx rm direct-sandbox
Enter fullscreen mode Exit fullscreen mode

remove sbx

Now create one with --clone:

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

clone sandbox

Inside the sandbox:

pwd
ls -la
cat note.txt
echo "this change stays inside the clone" >> note.txt
git status
Enter fullscreen mode Exit fullscreen mode

inside clone sbx

On the host:

cat note.txt
# The host file is unchanged
Enter fullscreen mode Exit fullscreen mode

inside host

The agent is working on a private Git clone inside the microVM. Your original files are mounted read-only.

Clone Mode Diagram

clone sbx diagram

Explanation

Start from the host repository (mounted read-only). The sandbox creates its own private clone. The agent edits only that clone. When you want the changes, you fetch from the special remote sandbox-<name> that Docker automatically adds on the host. Removing the sandbox deletes the private clone.

Important: --clone can only be set at creation time. You cannot switch an existing sandbox later.

Step 3 — Persistence: What Survives Stop vs Remove

Inside any running sandbox install something:

# still inside clone-sandbox or start a new one
apt-get update && apt-get install -y tree

#if command fails due to root privileges use then use the following command

sudo apt-get update && sudo apt-get install -y tree

docker pull alpine:latest
Enter fullscreen mode Exit fullscreen mode

Stop it (state is kept):

# from host
sbx ls
sbx stop clone-sandbox
sbx ls
Enter fullscreen mode Exit fullscreen mode

stop current sbx

Start it again:

sbx run --name clone-sandbox
Enter fullscreen mode Exit fullscreen mode

Inside:

tree --version
docker images
Enter fullscreen mode Exit fullscreen mode

resume sbx

Everything is still there.

Now remove it completely:

sbx stop clone-sandbox
sbx rm clone-sandbox
Enter fullscreen mode Exit fullscreen mode

remove sbx completely

If you recreate a sandbox with the same name, the packages and images are gone. That is expected.

Lifecycle Diagram

lifecycle diagram

Explanation

stop pauses the microVM but keeps the disk state (packages, images, agent history).

rm deletes the entire microVM and everything inside it. Host project files are never touched.

Step 4 — Network Policies

List current rules:

sbx policy ls
Enter fullscreen mode Exit fullscreen mode

You will see the Balanced preset rules (or whatever you chose earlier).

Allow a specific host:

sbx policy allow network docker.com
Enter fullscreen mode Exit fullscreen mode

Deny something:

sbx policy deny network docs.docker.com
Enter fullscreen mode Exit fullscreen mode

host firewall rules

Test from inside a sandbox:

sbx run --name net-test shell
# inside
curl -I https://docker.com
curl -I https://docs.docker.com   # should fail if denied
Enter fullscreen mode Exit fullscreen mode

sbx net-test

test firewall rules

Rules apply immediately. Deny always wins over allow.

You can scope a rule to one sandbox with --sandbox <name> or keep it global (default).

Network Flow Diagram

network flow diagram

Explanation

Every outbound HTTP/HTTPS request from the sandbox goes through a proxy that lives on your host. The proxy checks the policy rules. Non-HTTP traffic (raw TCP, UDP, ICMP) is blocked at the network layer and cannot be opened with normal policy rules (except limited IP:port cases).

Step 5 — Secrets (The Safe Way)

Never put real tokens as normal environment variables inside the sandbox.

Store a secret on the host:

# Example with GitHub (if you have gh CLI)
sbx secret set github -t "$(gh auth token)"

![sbx github secret](https://dev-to-uploads.s3.us-east-2.amazonaws.com/uploads/articles/95mykhlfukxre589fo7r.png)


# Or interactively
sbx secret set anthropic
Enter fullscreen mode Exit fullscreen mode

The value is stored in your OS keychain. When the agent makes an HTTP request that needs it, the host-side proxy injects the credential. The raw secret never enters the microVM.

Verify from the host:

sbx secret ls
Enter fullscreen mode Exit fullscreen mode

sbx secret ls

Credential Injection Diagram

credential injection

Explanation

The agent only sees a normal HTTP request. The proxy quietly adds the authentication header using the secret stored on the host. Even if the agent is compromised, it cannot read the real token.

Let’s Break It

  1. Start a sandbox with Locked Down style policy and try to reach a package registry → it fails.
  2. Allow the host → it works.
  3. Put a fake secret with sbx secret set and confirm the agent can use the service without the value appearing in env inside the sandbox.

Production Thinking

In a real project I would:

  • Prefer --clone when the agent is experimental or when multiple agents run on the same repo
  • Keep network policy as restrictive as possible (start from Balanced or stricter)
  • Always use sbx secret for any token
  • Name sandboxes clearly and remove them when the task is finished
  • Document the exact sbx policy allow list the team needs

Security Considerations

  • Direct mount = agent can rewrite your working tree
  • Clone mode = safer file isolation, but you must fetch the work later
  • Secrets injected by proxy are the only safe method
  • Network is deny-by-default; anything not explicitly allowed is blocked
  • Organisation policies (if your company enables them) override local rules completely

Common Mistakes

  • Forgetting --clone is create-time only
  • Expecting stop to free disk space (only rm does)
  • Putting secrets in .env files inside the sandbox
  • Adding too many global allow rules and wondering why isolation feels weak
  • Not checking sbx policy ls after changing rules

Troubleshooting

Problem How to confirm Fix
Changes not appearing on host Are you in clone mode? Fetch from sandbox-<name> remote
Network still blocked sbx policy ls Add allow rule or check deny precedence
Secret not working sbx secret ls Re-set the secret; restart sandbox
Disk full Many old sandboxes sbx ls then sbx rm unused ones
Policy not applying Org governance active? Local rules are ignored

Useful commands:

sbx policy ls
sbx secret ls
sbx diagnose
Enter fullscreen mode Exit fullscreen mode

Cleanup 

sbx stop net-test clone-sandbox 2>/dev/null || true
sbx rm net-test clone-sandbox 2>/dev/null || true
sbx policy ls          # review and clean rules if needed
# Optional full reset of policies (careful)
# sbx policy reset
Enter fullscreen mode Exit fullscreen mode

cleanup sbx

What We Learned

  • Direct mount is convenient but gives the agent write access to your real files
  • Clone mode keeps your working tree safe and is the better default for experimental work
  • stop keeps state, rm destroys it
  • Network is fully controllable with sbx policy
  • Secrets never need to enter the microVM — the proxy injects them

You now have complete control over the three things that matter most for safe daily use.

What’s Next?

In Blog 3 we put everything together: launch real coding agents (Claude, Gemini, Codex, etc.), give them actual development tasks, and use the isolated Docker daemon that lives inside every sandbox to build and run containers safely.

References

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

Top comments (0)