Running DeepAgents in a Docker Sandbox, with no cloud keys
Agent frameworks are easy to pip install and surprisingly hard to run responsibly. The moment you give an agent a filesystem, a shell, and a network, you have handed arbitrary generated code the same reach your laptop has. You also inherit a second problem that has nothing to do with safety: reproducing the exact environment, the exact package versions, and the exact model wiring on someone…
DeepAgents, a framework for creating agents using the LangGraph library, presents challenges when it comes to running them responsibly. Granting an agent access to a filesystem, shell, and network can expose the system to significant risks. On top of that, ensuring the same environment, package versions, and model wiring on other machines adds another layer of complexity. This article explores a solution to both problems through the use of a Docker Sandbox Kit.
The kit packages the DeepAgents harness, allowing it to run in an isolated Docker sandbox without requiring any cloud credentials. With a total size of four files, the kit is published on Docker Hub and can be run with a single command. The DeepAgents harness itself is an opinionated agent harness built on LangGraph, providing features like a planning tool, virtual filesystem, sub-agent delegation, and a detailed system prompt.
What sets the DeepAgents framework apart is that it is a library rather than a turnkey CLI. This means it ships the useful unit as "deepagents," already installed and wired to a model, ready for import. Additionally, the framework defaults to a cloud model (Anthropic) which requires an API key and open egress to a provider. However, the goal is to avoid both of these requirements.
A Docker Sandbox Kit is a unit of composition that includes a Docker image with a descriptor, layers for the root filesystem, entrypoint, user, working directory, and mixins. In the case of DeepAgents, it acts as a mixin, adding capabilities to a base workload that already includes a Python runtime, such as the stock docker/sbx-kit-shell image.
The architecture of the kit involves the Docker Model Runner, which communicates with the agent via the OpenAI wire format on port 12434. No traffic leaves the machine during this process. The kit consists of four files: deepagents.yaml, deepagents.dockerfile, agent guidance (system_prompt), and README.md.
The descriptor in the kit declares the identity, version, and capabilities requested. One of the key features is the phase-scoped network policy, where egress is granted per phase. The install phase can reach PyPI, while the running agent can only access the Model Runner. The PyPI grant closes before the agent starts, ensuring no unnecessary exposure.
Written by urgent.news from Dev.to's reporting — not their text. Machine-written — may contain errors; check the original before relying on it.
