What you will build
A tiny, disposable project that proves where a file edit lands. You will use the shell integration first so the boundary is visible without a model account or an autonomous coding session. A sandbox is an execution environment; it is not an approval to trust every output it produces.
- Host terminal
- sbx creates microVM
- Agent edits shared lab
- You review the diff
Conceptual flow. Follow the lesson for prerequisites, exact commands and verification limits.
Read the mechanism
Think of the microVM as a workshop with its own operating system, tools and Docker Engine. A workspace mount is a doorway you deliberately open into that workshop. In direct mode, both sides see the same files. The workshop can be isolated from the rest of the building while still damaging whatever you put through that doorway.
This distinction separates execution isolation from data integrity. If you share a repository read-write, the agent may modify it. If you permit an external API, an agent may use that API’s capabilities. The practical question is therefore: “What resources have I connected, with which rights?”
The current standalone CLI is sbx. Older articles using docker sandbox describe an earlier interface. This edition was checked on 6 October 2026 against Docker’s current docs and the v0.46.0 release. Record your installed version; command availability can differ.
Worked lab · one harmless file
Prerequisites: a supported local installation from Docker’s installation guide, virtualization available, sufficient free disk, and a completed sbx login. Installing Docker Sandboxes and signing in are separate setup steps; this page does neither.
Run on the host in a new teaching directory, never in your home folder or an existing important repository:
mkdir sandbox-handbook-lab
cd sandbox-handbook-lab
printf 'hello from the host\n' > note.txt
sbx version
sbx create --name handbook-first shell .
sbx exec handbook-first pwd
sbx exec handbook-first cat note.txt
sbx exec handbook-first sh -c 'printf "hello from the sandbox\n" >> note.txt'
cat note.txt
sbx lsThe shell redirect belongs inside the quoted sh -c argument. Moving >> note.txt outside those quotes makes the host shell perform the write, which would invalidate the demonstration.
Expected observations
The sandbox’s working directory should match the host project’s absolute path. The final host cat should contain both lines. These are predictions to verify, not output captured from a completed lab. Save your actual version, sandbox name and output in a local lab notebook. No AI request is required for this exercise.
Troubleshooting
If creation fails, distinguish authentication, virtualization and image download errors before changing anything. Check the official prerequisites and sbx diagnose. If the file is missing, inspect pwd on both sides and confirm the named sandbox is the one created here. Reusing a name can reconnect you to an older workspace.
Interview practice
Does a sandbox make it safe to mount an entire home directory?
No. Isolation protects resources outside the shared boundary. A broad mount places more documents, configuration and credentials inside that boundary. Share the smallest disposable workspace that satisfies the task.
Why begin with a shell instead of an AI agent?
It removes model behavior and provider authentication from the experiment. Once file and process boundaries are understood, an agent becomes another workload inside the same execution environment.
Completion check
Explain which process wrote the second line, where the file lives, and why the edit was visible immediately. Keep the sandbox for the next exercises; removing it later will not undo host-file edits.
Sources and version notes
Checked 6 October 2026; current baseline: sbx v0.46.0. Docker Sandboxes · Install Docker Sandboxes · Security model
Make the understanding yours.
Use the completion check above. Mark this chapter when you can explain the mechanism and its limits.
Self-assessed reading progress. This does not certify that a lab ran or a system is secure.