{"slug": "empty-sandboxes-break-developer-experience", "title": "Empty sandboxes break developer experience", "summary": "Docker's sandbox kits, defined in spec.yaml files, let developers pre-configure isolated environments with tools, network rules, and credential proxying, reducing setup friction that otherwise pushes developers to run agents on their hosts. The kits feature, part of Docker Sandboxes, installs tools, sets environment variables, and injects credentials via a host proxy so secrets never enter the microVM, addressing the annoyance of empty sandboxes that require repeated manual setup.", "body_md": "I work on [Docker Sandboxes](https://docs.docker.com/ai/sandboxes/), so I spend a lot of time talking about isolation, microVMs, disposable filesystems, blast radii, all the good infrastructure things.\n\nBut the Docker Sandboxes feature I keep reaching for in daily use is [kits](https://docs.docker.com/ai/sandboxes/customize/kits/).\n\nKits sound like a packaging detail until you try to use a sandbox for real work. An empty sandbox is a good boundary. It’s also (eventually) ephemeral and empty, and that combination means annoyance and repeated setup work.\n\nThe agent gets a clean filesystem, a baseline restricted network, and a clean credentials environment. Then it immediately needs `gcloud`\n\n, Java, Maven, some internal CLI, your package registry credentials, and that one skill where you distilled the tacit knowledge your team accumulated for years.\n\nKits are the escape hatch from that ritual. A kit lets you describe what the sandbox needs, how it should get it, what it may reach, and which credentials it can use, then apply that description when the sandbox starts.\n\n## Empty means setup work\n\nThe usual sandboxing story is security-shaped: put the risky thing behind a boundary and limit the blast radius.\n\nDevelopers rarely keep using tools because the architecture diagram has a nice boundary on it. They keep using tools when the workflow is less annoying than the alternative.\n\nA blank sandbox starts from a place developers rarely start from in practice. Real developer machines have: SDKs, package managers, cloud CLIs, shell setup, local credentials, project docs, cached tools, and configuration nobody wants to reconstruct from memory. Some of it is good engineering. Some of it is archaeology. Both affect whether the agent can complete the task.\n\nThe failure is rarely dramatic. The agent spends a few minutes installing packages, hits a blocked registry, asks for an API key it should never see, and the sandbox starts to feel like the thing between you and the work.\n\nAt that point, the developer has a choice: spend ten minutes preparing the isolated environment, or run the agent on the host and move on with their life.\n\nWe all know which one will win.\n\n## What is an sbx kit?\n\nThe [kits docs](https://docs.docker.com/ai/sandboxes/customize/kits/) describe a kit as a `spec.yaml`\n\nplus optional files. The useful mental model is simpler: a kit is the contract between the sandbox and the tool you want available inside it.\n\nA kit can install tools:\n\n```\nschemaVersion: \"1\"\nkind: mixin\nname: jq\n\ncommands:\n  install:\n    - command: \"apt-get update && apt-get install -y jq\"\n```\n\nThat is the smallest version. Useful kits usually do more. They can drop files into `/home/agent/`\n\nor the workspace, set non-secret environment variables, run startup commands, start background services, and add agent context to files such as `CLAUDE.md`\n\nor `AGENTS.md`\n\n.\n\nThey can also describe the outside world the sandbox is allowed to touch:\n\n```\nnetwork:\n  allowedDomains:\n    - api.example.com\n    - \"*.cdn.example.com\"\n  deniedDomains:\n    - telemetry.example.com\n```\n\nAnd they can connect credentials without copying real secrets into the microVM. The standard pattern keeps the credential on the host, gives the agent a sentinel value, and lets the sandbox proxy inject the real header only when the request goes to an approved service.\n\n```\nnetwork:\n  allowedDomains:\n    - api.example.com\n  serviceDomains:\n    api.example.com: my-service\n  serviceAuth:\n    my-service:\n      headerName: Authorization\n      valueFormat: \"Bearer %s\"\n\ncredentials:\n  sources:\n    my-service:\n      env:\n        - MY_SERVICE_API_KEY\n\nenvironment:\n  proxyManaged:\n    # Agent sees \"proxy-managed\"; the host proxy injects the real token.\n    - MY_SERVICE_API_KEY\n```\n\nInside the sandbox the agent sees `MY_SERVICE_API_KEY=proxy-managed`\n\n. The actual secret stays on the host. The proxy replaces the header on the way out.\n\nThat distinction is why credential support belongs in the kit contract. If the sandbox exists to keep the agent away from host secrets, copying those secrets into the microVM would be a strange way to celebrate.\n\n## Mixin kits are the norm\n\nThere are two kit shapes in the spec. A `kind: sandbox`\n\nkit defines a full agent runtime: image, entrypoint, policy, the whole thing. Use that when you are building an agent.\n\nMost integrations should be mixins.\n\nA mixin kit extends an existing sandbox with one capability. It installs the tool, opens the narrow network path, wires credentials, and gives the agent enough instructions to use the thing. The runtime stays with the agent kit.\n\nThat is the shape I use for most of my own kits. For example, the kits I keep using daily are [ agy](https://github.com/shelajev/agy-sbx-kit),\n\n[, and](https://github.com/shelajev/yt-transcript-sbx-kit)\n\n`yt-transcript`\n\n[.](https://github.com/shelajev/tessl-sbx-kit)\n\n`tessl`\n\nThe YouTube kit is exactly what you think: give the sandbox the tools to fetch transcripts and media metadata without turning every new sandbox into a small dependency archaeology project. The Tessl kit is even more direct. It brings skills into the agent running inside the sandbox, so I do not need to inject them manually like a medieval peasant.\n\nThe nice part of mixins is that they stack.\n\nA giant “Oleg’s entire laptop, but in a microVM” kit would be funny once and then become a maintenance incident. You want small kits with clear jobs:\n\n- a Java kit that installs a JDK, Maven, SDKMAN!, team Maven settings, and links to Spring docs;\n- a\n`gcloud`\n\nkit that installs the CLI, allows the right Google API domains, and wires credentials through the proxy; - a Google Workspace kit that gives the agent access to your email and Google Docs;\n- a Tessl kit that brings skills into the sandbox;\n- a YouTube transcript kit that adds\n`yt-dlp`\n\n,`ffmpeg`\n\n, and whatever network access those need.\n\nThen a sandbox can be assembled for the task:\n\n```\nsbx run claude . \\\n  --kit docker.io/acme/sbx-java-kit:1.0 \\\n  --kit docker.io/acme/sbx-gcloud-kit:1.0 \\\n  --kit docker.io/acme/sbx-tessl-kit:1.0\n```\n\nThe same agent now starts with a different contract around it.\n\nAt that point kits stop being a packaging mechanism and start being a productivity feature. The sandbox stays disposable, but the setup becomes repeatable. The developer can throw away the environment without throwing away the knowledge of how to rebuild it.\n\n## Sharing is caring\n\nLocal setup scripts are fine until the second person needs them. At that point they become documentation, and documentation becomes stale with excellent punctuality. Then someone pastes a token into a config file because the happy path was missing.\n\nA kit gives that setup a place to live.\n\nVendors can publish kits for their CLIs or APIs. Inside a company, the same pattern works for package registries, cloud accounts, corporate proxy certificates, and preferred language toolchains. The user gets one `--kit`\n\nflag instead of a wiki page and a feeling of mild dread.\n\nDistribution matters here. Kits support local directories, Git URLs, and OCI artifacts. For shared kits, OCI distribution is the obvious path because users can reference a versioned artifact directly:\n\n```\nsbx run claude --kit docker.io/acme/sbx-my-product-kit:1.0\n```\n\nKeep the source in GitHub or wherever your team collaborates. Publish the artifact to Docker Hub or another OCI registry. The source repo is where people review, patch, and complain politely. The registry is what makes the kit easy to consume.\n\n## All in all\n\nSecurity is a good reason to care about kits. The network and credential contract becomes explicit, which is useful by itself. The daily-use reason is more prosaic: kits make sandboxes survivable as a development tool.\n\nAn empty sandbox is a boundary. A configured sandbox is a place where an agent can actually work. Kits are how that configuration becomes repeatable, reviewable, and shareable.\n\nThe [kits docs](https://docs.docker.com/ai/sandboxes/customize/kits/) and [examples](https://docs.docker.com/ai/sandboxes/customize/kit-examples/) are enough to build a first mixin kit without inventing the shape from scratch.\n\nIsolation only survives contact with developers when it is at least as convenient as skipping it.", "url": "https://wpnews.pro/news/empty-sandboxes-break-developer-experience", "canonical_source": "https://www.docker.com/blog/empty-sandboxes-break-developer-experience/", "published_at": "2026-08-03 13:00:00+00:00", "updated_at": "2026-08-10 06:40:21.391904+00:00", "lang": "en", "topics": ["developer-tools", "ai-infrastructure", "ai-agents"], "entities": ["Docker Sandboxes", "Docker"], "alternates": {"html": "https://wpnews.pro/news/empty-sandboxes-break-developer-experience", "markdown": "https://wpnews.pro/news/empty-sandboxes-break-developer-experience.md", "text": "https://wpnews.pro/news/empty-sandboxes-break-developer-experience.txt", "jsonld": "https://wpnews.pro/news/empty-sandboxes-break-developer-experience.jsonld"}}