deepagents-docker-sandbox

Docker sandbox integration for Deep Agents.

This package exposes DockerSandbox as the Deep Agents-compatible backend and DockerSandboxRuntime as the lower-level Docker runtime.

Quick install (PyPI)

When/if the project is published to PyPI end users should be able to install with:

pip install deepagents-docker-sandbox

Local development

The project installs deepagents from PyPI by default, so a standalone checkout can run with uv sync --group test or the test commands below.

Usage with DockerSandbox

from deepagents_docker_sandbox import DockerSandbox

with DockerSandbox.create(default_timeout=120) as sandbox:
    result = sandbox.execute("echo hello")
    print(result.output)

Low-level DockerSandboxRuntime example

For direct access to the lower-level Docker runtime:

from deepagents_docker_sandbox import DockerSandboxRuntime

with DockerSandboxRuntime.create() as runtime:
    runtime.write_file("/tmp/hello.txt", "hello")
    result = runtime.run("cat /tmp/hello.txt")
    print(result.stdout)

Requirements

This package requires a working Docker daemon for real sandbox execution.

The default runtime creates a container from python:3.11-slim, injects a small helper process, exposes that helper on a random host port, and applies conservative resource and security settings.

Security

Docker isolation depends on the host Docker daemon and container configuration. Do not treat this package as a complete multi-tenant security boundary without additional host hardening, image controls, network controls, and workload isolation.

Tests

Default suite:

PYTHONPATH=src uv run --group test pytest -q

Docker-gated runtime round trip:

DEEPAGENTS_DOCKER_SANDBOX_TESTS=1 PYTHONPATH=src uv run --group test pytest tests/test_docker_runtime.py::test_optional_docker_runtime_roundtrip -q

Deep Agents standard sandbox integration checks:

DEEPAGENTS_DOCKER_SANDBOX_RUN_INTEGRATION=1 PYTHONPATH=src uv run --group test pytest tests/integration_tests -q

Notebooks

Example notebooks live in notebooks/ and are not part of the installed library.

Release process

Releases are published through GitHub Actions with PyPI Trusted Publishing.

One-time publishing setup

Configure pending trusted publishers on TestPyPI and PyPI for the deepagents-docker-sandbox project:

• Owner: Alex2Yang97
• Repository: deepagents_docker_sandbox
• Workflow: publish.yml
• TestPyPI environment: testpypi
• PyPI environment: pypi

In GitHub repository settings, create matching Actions environments:

• testpypi: allow manual deployments from main.
• pypi: require reviewer approval and restrict deployments to release tags matching v* when available.

Protect main with pull request reviews, required CI status checks, resolved conversations, and disabled force pushes/deletions before publishing production releases.

Publishing a release

1. Open a pull request and wait for the CI workflow to pass.
2. Run the Publish workflow manually from main to publish the current version to TestPyPI.
3. Smoke test the TestPyPI package in a clean environment:

python -m pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ deepagents-docker-sandbox==0.0.1
python -c "from deepagents_docker_sandbox import DockerSandboxRuntime; print(DockerSandboxRuntime)"

4. Create and push a version tag, for example v0.0.1, to publish the same version to PyPI.

Before tagging a release, keep the version in pyproject.toml and src/deepagents_docker_sandbox/_version.py synchronized.