deepagents-docker 0.1.2

deepagents-docker

Run Deep Agents in an isolated Docker container without compromising your host machine.

Quickstart

Requires Docker on your machine.

Install with uv:

uv add deepagents-docker

or with pip:

pip install deepagents-docker

from deepagents import create_deep_agent
from deepagents_docker import DockerSandbox

agent = create_deep_agent(
    model="openai:gpt-5.5",
    backend=DockerSandbox(),
    system_prompt="You are a research assistant.",
)

result = agent.invoke({"messages": "Research the latest trends in AI and write a summary."})

Configuration

Constructor options let you change the docker image of the container, shared folder path, command timeout, resource limits, outbound network access, and any extra docker run flags:

DockerSandbox(
    image="python:3.12-bookworm",      # default image (Debian-based, includes curl, etc.)
    allow_outbound_traffic=True,       # False → no network; True (default) → allow outbound traffic
    shared_dir="/path/to/project",     # host folder shared with the container; see note below
    timeout=120,                       # per-command timeout (seconds)
    max_output_bytes=100_000,          # per-stream stdout/stderr cap; output is streamed
                                       # and the command is killed once it is reached
    memory="256m",                     # default memory limit
    cpus=0.5,                          # default CPU limit
    pids_limit=128,
    auto_remove=True,                  # remove container on close()
    extra_run_args=["--env", "FOO=bar"],
)

[!NOTE] Pass an explicit shared_dir path to keep files after the container stops. When omitted, a temporary directory is created within the host filesystem and removed when the DockerSandbox is closed.

How it works

The creation of a DockerSandbox object results in the starting of a long-running docker container. Every shell command executed by the agent is actually run inside the container, not on your host OS. Therefore, library installations, cURL downloads, and any other filesystem changes stay inside Docker, not on your host. The only link between the container and your machine is shared_dir (if provided), a folder on disk that is mounted at /shared (with that directory as the shell working directory) so you can share files between the agent and your host.

[!NOTE] The container is stopped and removed automatically when the Python process exits (atexit). Use a context manager (below) to tear down earlier.

Using a context manager

Use a context manager when you want the container stopped and removed as soon as you leave the block:

from deepagents import create_deep_agent
from deepagents_docker import DockerSandbox

with DockerSandbox() as backend:
    agent = create_deep_agent(model="openai:gpt-5.5", backend=backend)
    agent.invoke({"messages": "..."})

# Container stopped and removed here.
print("Done!")

Examples

Prerequisites:

• An OpenAI API key
• Docker installed and running
• Python 3.12 or higher

Set the OpenAI API key:

export OPENAI_API_KEY=your_api_key

1. Pizza agent

The pizza agent searches the web for a Neapolitan pizza recipe and writes it to a file in the shared folder:

from deepagents import create_deep_agent
from deepagents_docker import DockerSandbox

backend = DockerSandbox(
    shared_dir="examples/data",
    allow_outbound_traffic=True,
)

agent = create_deep_agent(
    model="openai:gpt-5.5",
    backend=backend,
    system_prompt="You are a pizza chef.",
)

for step in agent.stream(
    {"messages": "Find the best neapolitan pizza recipe and write it to the recipe.md file."},
    stream_mode="updates",
):
    for update in step.values():
        if update and (messages := update.get("messages")):
            for message in messages:
                message.pretty_print()

The agent writes recipe.md under examples/data/.

2. Sales analyst

The sales analyst reads sales.csv from the shared folder, installs Python packages inside the container as needed (for example pandas, matplotlib), runs an analysis script, and writes a markdown report with charts:

from deepagents import create_deep_agent
from deepagents_docker import DockerSandbox

backend = DockerSandbox(
    shared_dir="examples/data",
    allow_outbound_traffic=True,
)

agent = create_deep_agent(
    model="openai:gpt-5.5",
    backend=backend,
    system_prompt="You are a sales analyst assistant.",
)

for step in agent.stream(
    {
        "messages": (
            'Analyze the "sales.csv" data and write a report (with charts) into '
            'a file called "sales_report.md". Put images in an "img" directory.'
        )
    },
    stream_mode="updates",
):
    for update in step.values():
        if update and (messages := update.get("messages")):
            for message in messages:
                message.pretty_print()

The agent writes sales_report.md and chart images under examples/data/img/.

Development

git clone https://github.com/andybbruno/deepagents-docker.git
cd deepagents-docker
uv sync
uv run pytest

Contributing

Contributions are welcome! Please feel free to open an issue or submit a pull request.

Security

Use this for trusted workloads and development, not as a hard multi-tenant boundary. Do not put secrets in the shared folder. See Deep Agents security.

License

MIT — LICENSE.