- 💡 TIP
- Many thanks to claude for its translation. It’s been reviewed but may well contain errors. Feel free to PR ;)
TL;DR;
Your AI agent has no business on your machine. Put it in a sandbox, describe what it’s allowed to do in a YAML file, and version all that stuff for me.
Your CISO will thank you (don’t forget to mention me). Or not, but they’ll sleep better.
And let’s get the illustration question out of the way: it’s a whale (wink, wink), and you can see its rib cage. Haha, hum.
YOLO mode is fun until the rm -rf
A few weeks ago, I told you about Docker Agent, Docker’s agent framework that doesn’t need Docker.
Today I’m doing it again with another tool backed by Docker Inc, which doesn’t use the docker runtime. Nope.
Yet another tool with a very well-chosen name. Granted, I’m not the sharpest tool in the shed, but it took me a while to figure out that SBX meant sandbox.
Do we say Redhat Hibernate or HashiCorp Terraform? No, I don’t think so. Please Docker: could you stop putting docker in the name of every single one of your products?
On the other hand, you really can run docker agent inside docker sbx and ask it to start docker containers, but that’s another story.
Let’s be honest for two minutes. How many of you have already started a coding agent with the option that disables every confirmation, because approving grep 47 times is a pain?
I haven't. Because I’m a big paranoid, but boy does it get on my nerves, especially since I still end up approving stuff I don’t 100% understand.
And yet on my laptop there are SSH keys, API keys, git credentials, and so on.
And just last week, an agent asked me whether it could kindly, just like that, run a find on / («Oh no, I can’t find what I’m looking for, I’ll go look higher up in the tree, let’s say ALL the way up?»)
The problem isn’t that the agent is malicious, let’s not grant it a morality it doesn’t have. The problem is that it executes what it reads. A booby-trapped README in a dependency, a carefully crafted GitHub issue, and your agent kindly sends your ~/.ssh/id_ed25519 to someone very grateful.
Docker Sandboxes (the CLI is called sbx) tackles this problem with a simple idea: the agent has every right, but inside a box whose walls you set.
# Whatever your OS.<1> mise use github:docker/sbx-releases@latest - Did I ever tell you I like mise?
The sandbox
Each sandbox runs on its own VM. Not a container shared with the rest of your machine: a VM. Four walls and an armored door.
Here’s what you get by default:
- Files Only the current folder is mounted (read/write with
sbx run). The rest of your disk doesn’t exist for the agent. You can even trigger a repository clone inside the sandbox. - Network All outbound TCP is blocked as long as no rule allows it. UDP disabled, ICMP blocked, and DNS goes through an internal resolver that enforces the policy.
- Secrets None by default. When you provide one (
sbx secret set), a host-side proxy injects it into outgoing HTTP headers. The agent never sees the real value. Forgittoo, yes, too. - Neighbouring sandboxes They don’t talk to each other. They don’t exist. What are you talking about?
And inside? The agent does whatever it wants: sudo, apt install, docker build, docker run... It can trash its VM as much as it likes, that’s kind of the point.
Wait, if the secret is injected by a proxy, what’s in the GH_TOKEN variable on the agent side? And what if I have a .env file in my project folder?
Well, the secret is a dummy value. The agent can print it, log it, post it on Pastebin if it feels like it (no it can’t, the network rules prevent it): it’s worthless. The real key is only added to requests heading to the declared domains.
- ⚠️ WARNING
- If you decide to mount your project directory in the sandbox, everything in it will be in the sandbox. Your project’s
.envfile will be accessible there.
Same goes for the.gitfolder: the agent commits straight into your repository, and its commits show up instantly on your machine. It can also drop a little script into.git/hooks, which will run outside the sandbox the next time you rungit commit. Oops.
If that bugs you (it bugs me), start the sandbox with--clone: the agent works on a standalone clone, and you’re the one fetching its work with agit fetch sandbox-<name>, when you decide to.
Whatever happens, and without an explicit action on your part, the agent won’t be able to push its changes.
On the network side, the local policy is managed with sbx policy:
sbx policy ls # ① sbx policy allow ... # ② - Lists the active rules. If your organization enforces a policy, the first line tells you so.
- Adds an allow rule on your machine. I’ll let you read
sbx policy allow --helprather than copy the syntax here.
Yes, there’s a whole part of the tooling dedicated to enterprise governance of this kind of question. It’s really a feature that should convince any CIO to look at the tool, but I couldn’t test it, so there you go.
A workload, some mixins, and Lego
Opening network ports by hand for every project doesn’t scale. That’s where kits come in.
A kit is an OCI image, as plain as can be. You can very well use its images with Podman, for instance.
What makes it special: a manifest annotation describing what the kit asks for (domains, secrets, volumes, install hooks, instructions for the agent). There are two kinds:
- workload The base environment and the launch command (an agent, a shell). Only one per sandbox. What you’d usually associate with a container image.
- mixin An add-on: a tool, its network rule, its secret, some context for the agent. As many as you want.
sbx run docker.io/sbx/docker-agent:latest \ ① --kit docker.io/jtama/sbx-mixin-kit-java27:dev # ② - The base image: docker-agent, in a yolo flavour. Because.
- A mixin that adds maven and java 27, because I’m worth it.
The real benefit is that each mixin carries its own rules. Here’s the one for the GitHub CLI, taken from the spec announcement:
capabilities: - type: com.docker.sandbox/network-policy@2 config: runtime: allow: - github.com - hosts: [api.github.com] methods: [GET, HEAD, POST, PATCH, PUT, DELETE] deny: # ① - hosts: [api.github.com] methods: [DELETE] paths: ["/repos/**"] - type: com.docker.sandbox/credential@1 optional: true # ② config: service: github phase: runtime apiKey: name: GH_TOKEN proxyManaged: true # ③ inject: - {domain: api.github.com, header: Authorization, format: "Bearer %s"} -
denywins overallow. The agent can open PRs, comment, push, but not delete a repository. For that alone, I’m sold. - The kit starts even if you haven’t provided a token.
- The famous proxy: the real value never enters the sandbox.
When you stack several kits, the order of the --kit flags doesn’t matter at all. Composition follows the provides/requires graph each kit declares. Network rules add up, hooks run in dependency order, and the instructions for the agent merge into a single document.
Quick quiz. The sbx-kit-claude workload provides Claude Code. You add a home-made mixin that also installs Claude Code, in another version. What happens?
Details
It refuses to start. Two kits declaring the same provides is an error, not a "last one wins".
Same thing if a requires isn’t satisfied within the set: sbx won’t go fetch the missing piece on its own. And if a mandatory request can’t be granted, the agent doesn’t start at all, rather than starting with more or fewer rights than planned.
Creating a mixin kit
Your Dockerfiles aren’t going in the bin.
In its latest version, a kit is ultimately just an OCI image with annotations. So we can reuse what we already know and, above all, take advantage of the gargantuan heritage of existing images.
A kit is a folder with at least two files that usually* share the same name:
my-mixin/ ├── my-mixin.yaml └── my-mixin.dockerfile * That’s the convention used by sbx kit build, but you’ll see later on that these file names get changed at build time.
Before
The dev image your team has been maintaining for two years, with the right JDK, the right Maven, the internal PKI certificate:
FROM maven:3-eclipse-temurin-27 RUN apt-get update && apt-get install -y git curl COPY corp-ca.crt /usr/local/share/ca-certificates/ After
Same base, turned into a mixin. The Dockerfile starts again from an image provided by Docker that already ships the agent:
FROM maven:3-eclipse-temurin-27 as src<1> FROM scratch ② COPY --from=src /opt/java/openjdk /opt/java/openjdk COPY --from=src /usr/share/maven /usr/share/maven COPY corp-ca.crt /usr/local/share/ca-certificates/ ③ COPY --chmod=0755 setup.sh /usr/local/lib/java-maven/setup.sh ④ - The base doesn’t change, it gives us the FS.
- We start again from a blank image.
- We copy the certificate.
- A small script that sets the java env variables and puts java on the path.
#!/bin/sh # Hook d'installation (root), exécuté à la création du sandbox. set -eu JAVA_HOME=/opt/java/openjdk MAVEN_HOME=/usr/share/maven # 0) Mettre java, javac, mvn... sur le PATH et exporter JAVA_HOME pour les shells ln -sf "$JAVA_HOME"/bin/* /usr/local/bin/ ln -sf "$MAVEN_HOME/bin/mvn" /usr/local/bin/mvn printf 'export JAVA_HOME=%s\nexport MAVEN_HOME=%s\n' "$JAVA_HOME" "$MAVEN_HOME" \ > /etc/profile.d/java-maven.sh # 3) Le volume ~/.m2 est monté en root : on le rend à l'utilisateur agent (UID 1000). mkdir -p /home/agent/.m2 chown 1000:1000 /home/agent/.m2 And the matching descriptor:
spec.yaml# syntax=docker/sandbox-kit:3 schemaVersion: "3" displayName: Java 27 + Maven description: Java 27 sourceUrl: https://github.com/cli/cli licenses: [MIT] kind: mixin provides: ["java@27", "maven@3"] ① capabilities: - type: com.docker.sandbox/lifecycle@1 ② config: install: - command: /usr/local/lib/java-maven/setup.sh user: "0" dockerfile: Dockerfile - Declares what the kit provides.
- Adds a capability to the kit, in this case on the lifecycle.
Using the kit without building it
_spoiler alert_ Yes, we actually build it.sbx run ./my-kit Locally, sbx also accepts the folder directly and, behind your back, starts a sbx-kit-builder micro-VM, which does contain a docker runtime, and builds your kit. The result, however, is only available in the sandbox you just created. Getting at it to export it takes some contortions, but of course anything is always possible.
Building the kit with docker
docker buildx build -f my-workload/my-workload.yaml -t my-workload:dev my-workload/ --push # ① sbx run --kit my-workload:dev # ② - The YAML is passed with
-f, it’s the one driving the build through the frontend. Careful: if you don’t push, it doesn’t work. - We can now use the kit.
- 🔥 CAUTION
-
FROMgets an image’s files, not its rights. If you start from the image of a published kit, its network rules, its secrets and its hooks don’t come along. To keep an existing kit’s capabilities and add tools to it, you need to compose a kit set (we’re getting there).
Building the kit with Podman
It’s more complicated because it isn’t baked into podman, but a kit, in the end, is still an OCI image.
With lots of annotations, but still.
The following script builds a mixin image (for a workload, the script would need to be a bit more involved, but it can be done).
The build happens in 2 steps:
- We create a first image containing the kit’s fs. In our example, java.
- We create the final image, which additionally contains the descriptor in the
/usr/share/sandbox/kit/<kit name>/folder and whose image is annotated with the descriptor’s content.
I wrote you a little jbang script that does just that. It produces an image tagged dev, up to you to retag it properly.
///usr/bin/env jbang "$0" "$@" ; exit $? //JAVA 21+ //DEPS com.fasterxml.jackson.dataformat:jackson-dataformat-yaml:2.17.2 //DEPS org.aesh:aesh:3.19.1 import com.fasterxml.jackson.databind.JsonNode; import com.fasterxml.jackson.databind.ObjectMapper; import com.fasterxml.jackson.dataformat.yaml.YAMLFactory; import org.aesh.AeshRuntimeRunner; import org.aesh.command.Command; import org.aesh.command.CommandDefinition; import org.aesh.command.CommandException; import org.aesh.command.CommandResult; import org.aesh.command.invocation.CommandInvocation; import org.aesh.command.option.Argument; import org.aesh.command.option.Option; import java.nio.file.Files; import java.nio.file.Path; import java.util.*; import java.util.stream.Collectors; import java.util.stream.Stream; import java.util.stream.StreamSupport; /** * Packages a v3 mixin Kit with Podman, without BuildKit or the Kit frontend. * <p> * Reads <kit-dir>/<kit_name>.yaml, builds <kit_name>.dockerfile, stages the sources * under /usr/share/sandbox/kit/<kit_name>/ and writes the manifest annotations * (SPEC-v3 §9.3 and §10). * <p> * Usage: jbang BuildMixinKit.java <kit-dir> <kit_name> * With the spec checkout, the result is validated by `task tck:kit:layout`. */ @CommandDefinition(name = "build", description = "Builds a mixin sbx kit", generateHelp = true) public class BuildMixinKit implements Command<CommandInvocation> { final ObjectMapper YAML = new ObjectMapper(new YAMLFactory()); final ObjectMapper JSON = new ObjectMapper(); final String KIT = "vnd.docker.sandbox.kit."; final String OCI = "org.opencontainers.image."; @Option(shortName = 'n', name = "name", description = "The kit image name", defaultValue = "") private String imageName; @Argument(description = "Kit directory", required = true) private Path kitDir; private CommandInvocation invocation; public static void main(String[] args) throws Exception { AeshRuntimeRunner.builder() .command(BuildMixinKit.class) .args(args) .execute(); } @Override public CommandResult execute(CommandInvocation commandInvocation) throws CommandException, InterruptedException { this.invocation = commandInvocation; imageName = imageName.isEmpty() ? kitDir.getFileName().toString() : imageName; String dockerFile = kitDir.resolve("Dockerfile").toString(); String kitFile = "spec.yaml"; JsonNode descriptor = null; try { descriptor = YAML.readTree(kitDir.resolve(kitFile).toFile()); checkSupported(descriptor, kitDir.resolve(dockerFile)); String contentRef = imageName + "-content:dev"; String kitRef = imageName + ":dev"; String tmpDir = imageName.substring(imageName.lastIndexOf("/")+1); invocation.println(tmpDir); Path work = Files.createTempDirectory(tmpDir + "-kit-"); invocation.println("Working directory (kept if the build fails): " + work); buildContentImage(kitDir, dockerFile, contentRef); Path staging = stageSources(kitDir, imageName, dockerFile, descriptor, work); buildKit(kitRef, contentRef, annotations(descriptor), staging); deleteRecursively(work); return CommandResult.SUCCESS; } catch (Exception e) { e.printStackTrace(); throw new CommandException(e); } } /** * Refuses what only the real frontend handles: workloads and build-phase args. */ void checkSupported(JsonNode d, Path dockerfile) { require("3".equals(d.path("schemaVersion").asText()), "schemaVersion must be \"3\""); require("mixin".equals(d.path("kind").asText()), "only kind: mixin is supported (workloads need derived deb/apk provides)"); require(Files.isRegularFile(dockerfile), "missing companion recipe " + dockerfile); for (JsonNode arg : d.path("args")) { require(!arg.has("buildArg"), "build-phase args (buildArg) are not supported"); } boolean hasVersion = d.has("version"); for (JsonNode p : d.path("provides")) { require(hasVersion || p.asText().contains("@"), "provides entry needs a version: " + p.asText()); } } void buildContentImage(Path kitDir, String dockerFile, String contentRef) throws Exception { invocation.println("Building content image " + contentRef); run(kitDir, "podman", "build", "--format", "oci", "--tag", contentRef, "--file", dockerFile, "."); } /** * kit.yaml (published descriptor), kit.dockerfile (recipe) and the packaging Containerfile. */ Path stageSources(Path kitDir, String kitName, String dockerFile, JsonNode descriptor, Path work) throws Exception { Path staging = Files.createDirectory(work.resolve("staging")); Files.writeString(staging.resolve("kit.yaml"), JSON.writeValueAsString(descriptor)); Files.copy(kitDir.resolve(dockerFile), staging.resolve("kit.dockerfile")); Files.writeString(staging.resolve("Containerfile"), """ ARG CONTENT_IMAGE FROM ${CONTENT_IMAGE} COPY . /usr/share/sandbox/kit/%s/ """.formatted(kitName)); return staging; } /** * SPEC-v3 §9.3, minus built-by: this tool is not the Kit frontend. */ Map<String, String> annotations(JsonNode d) throws Exception { Map<String, String> a = new LinkedHashMap<>(); a.put(KIT + "descriptor", JSON.writeValueAsString(d)); a.put(KIT + "schema-version", d.path("schemaVersion").asText()); a.put(KIT + "capabilities", stream(d.path("capabilities")) .map(c -> c.path("type").asText()).distinct().sorted() .collect(Collectors.joining(","))); a.put(OCI + "title", d.path("displayName").asText()); a.put(OCI + "description", d.path("description").asText()); a.put(OCI + "authors", d.path("author").asText()); a.put(OCI + "source", d.path("sourceUrl").asText()); a.put(OCI + "licenses", stream(d.path("licenses")).map(JsonNode::asText) .collect(Collectors.joining(","))); a.put(OCI + "version", d.path("version").asText()); a.values().removeIf(String::isEmpty); // empty fields emit no key return a; } void buildKit(String Source:https://dev.to/onepoint/docker-sbx-let-the-agent-wreck-everything-as-you-long-as-you-contain-the-chaos-5hdkRelated posts
I turned my whole server into a YAML file, and every change gets a diff first
Claude Code: subscription or API? Work it out from your own logs
One Setup for Claude Code, Codex, OpenCode, and Antigravity — With One-Command Undo
