by Docker just released a really exciting update to Docker Sandboxes, a feature that allows running AI agents, like Claude Code, in isolated environments.
This change was released with the Docker Desktop 4.58 update (Docker Engine 29.1.5). They refer to it as a "new version of Docker Sandboxes".
In this article, I’ll demonstrate how to use it and some details about agent instructions and network policies.
New vs Old Docker Sandboxes
The main difference is that now these instances run inside of microVMs, which have much better isolation than regular containers.
Containers share the host kernel (or in the case of Docker Desktop, share the same virtual machine) and can’t safely isolate something that needs its own Docker daemon. Docker-in-Docker approaches either compromise isolation (privileged mode with host socket mounting) or create nested daemon complexity.
With microVMs, each sandbox gets its own VM with a private Docker daemon. The agent can build images, start containers, and run tests without any access to your host Docker environment.
| Layer | Regular Docker Container | MicroVM (Docker Sandbox) |
|---|---|---|
| Isolation Layer | Container Runtime (Namespaces/Cgroups) | Guest Kernel (Isolated) |
| Virtualization | None (Direct syscalls) | Hypervisor (KVM/Firecracker) |
| Host OS Kernel | Shared Kernel | Protected Kernel |
| Hardware | Host Hardware | Host Hardware |
Running Claude Code in a Docker Sandbox
All the commands for managing these sessions will be under the docker sandbox namespace. Below is how to run Claude Code in an isolated workspace:
docker sandbox run claude ~/projects/brainjuckYou must inform the agent and the workspace (the path to your project). I’m pointing mine to brainjuck, a Brainfuck-to-JVM compiler written in JavaScript. This information will be important later when we check the agent’s instructions.
This will then get the instance up using the docker/sandbox-template. In my case, it used the claude-code template.
It starts Claude Code with --dangerously-skip-permissions. This is fine, right?
The way it deals with the file system is straightforward. The workspace (~/projects/brainjuck) acts like a bind mount and all the rest of the filesystem acts a volume.
Agent Instructions
Every instance comes with a CLAUDE.md file that is supposed to contain relevant information about that project and environment configuration. Such a file is not visible in the host system.
In the VM, it will be placed in the parent directory. In my case, the file is at ~/projects/CLAUDE.md.
The file can be broken down into three sections:
Project Guidance: a generic section where language-based guidelines are provided.
In my example, it didn’t provide much specific information about the project itself. It doesn’t even mention JVM, Compiler or Brainfuck. It just saw the codebase has some Java and JavaScript files and provided general guidelines for those languages.
Docker Isolation layer Instructions (env and shell): this information is about the workspace itself. The dos and don’ts of environment and shell, and some troubleshooting tips.
Network Policies: this section mentions a firewall that restricts outbound network access. In the default mode, everything is allowed and there’s no step to configure it when creating the session. So, running these environments in default is risky since the best practice suggests limiting network access when running with
--dangerously-skip-permissions.
See the full CLAUDE.md file generated for my project here.
Network Policies
To follow the recommendation of limiting the network access, you can use the docker sandbox network proxy command to configure the network policies of an instance. You can either allow everything (default) or deny everything.
By the least privilege principle, the reasonable to do is to deny everything and then allow only the domains that are necessary for the agent to work.
docker sandbox network proxy claude-brainjuck --policy denyWith everything denied, when I ask it to fecth a content, it displays an error.
I deny all but for the app to work it needs access to stuff like GitHub, Anthropic API, package registries, etc. The proxy config for the session already starts with all of them allowed. You can see the proxy config at ~/.docker/sandboxes/vm/<vm-name>/proxy-config.json
In this JSON file, under the policy key, you will see if it’s allow or deny. Under the network key, you will see the allowedDomains and blockedDomains lists.
To add or remove domains you can use the --allow-host and --block-host flags. Example:
docker sandbox network proxy claude-brainjuck --allow-host "blog.codeminer42.com"
You can also inspect network logs and allow/block using CIDR notation. All under docker sandbox network namespace. Run it with --help to see all options.
Conclusion
This is a great feature for running AI agents in a safe way. Even better, with a tool you probably already have installed: Docker. No need to do a whole setup with bwrap or install socat.
Keep in mind that this is still an experimental feature. So, expect some rough edges and missing documentation. But overall, it works really well.
We want to work with you. Check out our Services page!
