deepagents-docker 0.0.1__py3-none-any.whl

deepagents_docker/__init__.py

@@ -0,0 +1,7 @@
+"""Docker-backed sandbox backend for DeepAgents."""
+
+from deepagents_docker.backend import (
+    DockerSandbox,
+)
+
+__all__ = ["DockerSandbox"]

deepagents_docker/_docker.py

@@ -0,0 +1,82 @@
+"""Low-level helpers for invoking the Docker CLI."""
+
+from __future__ import annotations
+
+import json
+import subprocess
+from collections.abc import Sequence
+from dataclasses import dataclass
+
+
+class DockerError(RuntimeError):
+    """Raised when a Docker CLI invocation fails."""
+
+
+@dataclass(frozen=True)
+class DockerRunResult:
+    """Captured output from a Docker CLI subprocess."""
+
+    returncode: int
+    stdout: str
+    stderr: str
+
+
+def run_docker(
+    args: Sequence[str],
+    *,
+    timeout: float | None = None,
+    input_text: str | None = None,
+) -> DockerRunResult:
+    """Run `docker` with the given arguments."""
+    try:
+        completed = subprocess.run(  # noqa: S603
+            ["docker", *args],
+            check=False,
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+            input=input_text,
+        )
+    except subprocess.TimeoutExpired as exc:
+        msg = f"docker command timed out after {timeout} seconds"
+        raise DockerError(msg) from exc
+    except FileNotFoundError as exc:
+        msg = "docker executable not found on PATH"
+        raise DockerError(msg) from exc
+
+    return DockerRunResult(
+        returncode=completed.returncode,
+        stdout=completed.stdout or "",
+        stderr=completed.stderr or "",
+    )
+
+
+def docker_available() -> bool:
+    """Return True when the Docker daemon responds to `docker info`."""
+    result = run_docker(["info", "--format", "{{.ServerVersion}}"])
+    return result.returncode == 0
+
+
+def inspect_container_id(container_name: str) -> str:
+    """Return the container ID for a running container name."""
+    result = run_docker(
+        ["inspect", "--format", "{{.Id}}", container_name],
+    )
+    if result.returncode != 0:
+        msg = result.stderr.strip() or f"failed to inspect container {container_name!r}"
+        raise DockerError(msg)
+    return result.stdout.strip()
+
+
+def format_docker_error(result: DockerRunResult) -> str:
+    """Combine stderr/stdout into a single error string."""
+    detail = (result.stderr or result.stdout).strip()
+    if not detail:
+        detail = f"exit code {result.returncode}"
+    try:
+        payload = json.loads(detail)
+    except json.JSONDecodeError:
+        return detail
+    if isinstance(payload, dict) and "message" in payload:
+        return str(payload["message"])
+    return detail

deepagents_docker/backend.py

@@ -0,0 +1,292 @@
+"""DockerSandbox: isolated shell execution with host-backed workspace files."""
+
+from __future__ import annotations
+
+import atexit
+import shlex
+import subprocess
+import tempfile
+import uuid
+from pathlib import Path
+
+from deepagents.backends.filesystem import FilesystemBackend
+from deepagents.backends.protocol import ExecuteResponse, SandboxBackendProtocol
+
+from deepagents_docker._docker import (
+    DockerError,
+    docker_available,
+    format_docker_error,
+    inspect_container_id,
+    run_docker,
+)
+
+DEFAULT_EXECUTE_TIMEOUT = 120
+DEFAULT_IMAGE = "python:3.12-bookworm"
+CONTAINER_WORKDIR = "/workspace"
+
+
+class DockerSandbox(FilesystemBackend, SandboxBackendProtocol):
+    """Filesystem backend with shell commands executed inside a Docker container.
+
+    File operations (`ls`, `read`, `write`, `edit`, `grep`, `glob`) run against a
+    dedicated workspace directory on the host via `FilesystemBackend` with
+    `virtual_mode=True`. The same directory is bind-mounted into the container at
+    `/workspace`, and the `execute` tool runs commands there with Docker resource
+    and security limits.
+
+    This is defense in depth, not a perfect isolation boundary. Do not mount
+    secrets into the workspace, keep Docker patched, and prefer microVMs for
+    hostile multi-tenant workloads.
+    """
+
+    def __init__(
+        self,
+        *,
+        image: str = DEFAULT_IMAGE,
+        allow_outbound_traffic: bool = True,
+        workspace_dir: str | Path | None = None,
+        timeout: int = DEFAULT_EXECUTE_TIMEOUT,
+        max_output_bytes: int = 100_000,
+        memory: str = "512m",
+        cpus: float = 1.0,
+        pids_limit: int = 128,
+        auto_remove: bool = True,
+        extra_run_args: list[str] | None = None,
+    ) -> None:
+        """Create a sandbox container and workspace directory.
+
+        Args:
+            image: Docker image for command execution (default: official ``python:3.12-bookworm``).
+            workspace_dir: Host directory for agent files. A temporary directory is
+                created when omitted.
+            timeout: Default command timeout in seconds.
+            max_output_bytes: Maximum combined stdout/stderr captured per command.
+            memory: Docker memory limit (for example ``"512m"``).
+            cpus: Docker CPU limit.
+            pids_limit: Maximum number of PIDs inside the container.
+            outbound_traffic: Allow/deny outbound network traffic (default: allow).
+            auto_remove: Remove the container on ``close()``.
+            extra_run_args: Additional ``docker run`` flags appended before the image.
+        """
+        if timeout <= 0:
+            msg = f"timeout must be positive, got {timeout}"
+            raise ValueError(msg)
+        if cpus <= 0:
+            msg = f"cpus must be positive, got {cpus}"
+            raise ValueError(msg)
+        if pids_limit <= 0:
+            msg = f"pids_limit must be positive, got {pids_limit}"
+            raise ValueError(msg)
+
+        self._owns_workspace = workspace_dir is None
+        self._workspace = Path(
+            tempfile.mkdtemp(prefix="deepagents-docker-")
+            if workspace_dir is None
+            else workspace_dir,
+        ).resolve()
+        self._workspace.mkdir(parents=True, exist_ok=True)
+
+        super().__init__(
+            root_dir=self._workspace,
+            virtual_mode=True,
+            max_file_size_mb=10,
+        )
+
+        self._image = image
+        self._default_timeout = timeout
+        self._max_output_bytes = max_output_bytes
+        self._memory = memory
+        self._cpus = cpus
+        self._pids_limit = pids_limit
+        self._network_mode = "bridge" if allow_outbound_traffic else "none"
+        self._auto_remove = auto_remove
+        self._extra_run_args = list(extra_run_args or [])
+
+        self._container_name = f"deepagents-docker-{uuid.uuid4().hex[:12]}"
+        self._container_id: str | None = None
+        self._closed = False
+
+        self._start_container()
+        atexit.register(self.close)
+
+    @property
+    def workspace_dir(self) -> Path:
+        """Host path backing the agent workspace."""
+        return self._workspace
+
+    @property
+    def id(self) -> str:
+        """Unique identifier for this sandbox instance."""
+        return self._container_id or self._container_name
+
+    def _start_container(self) -> None:
+        if not docker_available():
+            msg = (
+                "Docker is not available. Install Docker, ensure the daemon is running, "
+                f"and pull the default image with `docker pull {DEFAULT_IMAGE}`"
+            )
+            raise DockerError(msg)
+
+        run_args = [
+            "run",
+            "-d",
+            "--name",
+            self._container_name,
+            "--network",
+            self._network_mode,
+            "--cpus",
+            str(self._cpus),
+            "--memory",
+            self._memory,
+            "--pids-limit",
+            str(self._pids_limit),
+            "--security-opt",
+            "no-new-privileges",
+            "--cap-drop",
+            "ALL",
+            "--read-only",
+            "--tmpfs",
+            "/tmp:rw,noexec,nosuid,size=64m",
+            "--tmpfs",
+            "/var/tmp:rw,noexec,nosuid,size=64m",
+            "-v",
+            f"{self._workspace}:{CONTAINER_WORKDIR}:rw",
+            "-w",
+            CONTAINER_WORKDIR,
+            *self._extra_run_args,
+            self._image,
+            "sleep",
+            "infinity",
+        ]
+        result = run_docker(run_args)
+        if result.returncode != 0:
+            msg = format_docker_error(result)
+            raise DockerError(f"failed to start sandbox container: {msg}")
+
+        self._container_id = inspect_container_id(self._container_name)
+
+    def _wrap_command(self, command: str) -> str:
+        """Run agent commands from the container workspace directory."""
+        return f"cd {shlex.quote(CONTAINER_WORKDIR)} && {command}"
+
+    def execute(
+        self,
+        command: str,
+        *,
+        timeout: int | None = None,
+    ) -> ExecuteResponse:
+        """Execute a shell command inside the sandbox container."""
+        if self._closed:
+            return ExecuteResponse(
+                output="Error: Sandbox has been closed.",
+                exit_code=1,
+                truncated=False,
+            )
+
+        if not command or not isinstance(command, str):
+            return ExecuteResponse(
+                output="Error: Command must be a non-empty string.",
+                exit_code=1,
+                truncated=False,
+            )
+
+        effective_timeout = timeout if timeout is not None else self._default_timeout
+        if effective_timeout <= 0:
+            msg = f"timeout must be positive, got {effective_timeout}"
+            raise ValueError(msg)
+
+        wrapped = self._wrap_command(command)
+        docker_args = [
+            "exec",
+            self._container_name,
+            "sh",
+            "-c",
+            wrapped,
+        ]
+
+        try:
+            completed = subprocess.run(  # noqa: S602
+                ["docker", *docker_args],
+                check=False,
+                capture_output=True,
+                text=True,
+                timeout=effective_timeout,
+            )
+        except subprocess.TimeoutExpired:
+            if timeout is not None:
+                msg = (
+                    f"Error: Command timed out after {effective_timeout} seconds "
+                    "(custom timeout). The command may be stuck or require more time."
+                )
+            else:
+                msg = (
+                    f"Error: Command timed out after {effective_timeout} seconds. "
+                    "For long-running commands, re-run using the timeout parameter."
+                )
+            return ExecuteResponse(output=msg, exit_code=124, truncated=False)
+        except FileNotFoundError:
+            return ExecuteResponse(
+                output="Error executing command (FileNotFoundError): docker executable not found on PATH",
+                exit_code=1,
+                truncated=False,
+            )
+        except Exception as exc:  # noqa: BLE001
+            return ExecuteResponse(
+                output=f"Error executing command ({type(exc).__name__}): {exc}",
+                exit_code=1,
+                truncated=False,
+            )
+
+        output_parts: list[str] = []
+        if completed.stdout:
+            output_parts.append(completed.stdout)
+        if completed.stderr:
+            stderr_lines = completed.stderr.strip().split("\n")
+            output_parts.extend(f"[stderr] {line}" for line in stderr_lines)
+
+        output = "\n".join(output_parts) if output_parts else "<no output>"
+        truncated = False
+        if len(output) > self._max_output_bytes:
+            output = output[: self._max_output_bytes]
+            output += f"\n\n... Output truncated at {self._max_output_bytes} bytes."
+            truncated = True
+
+        if completed.returncode != 0:
+            output = f"{output.rstrip()}\n\nExit code: {completed.returncode}"
+
+        return ExecuteResponse(
+            output=output,
+            exit_code=completed.returncode,
+            truncated=truncated,
+        )
+
+    def close(self) -> None:
+        """Stop and remove the sandbox container."""
+        if self._closed:
+            return
+        self._closed = True
+
+        stop = run_docker(["stop", "-t", "2", self._container_name], timeout=30)
+        if stop.returncode != 0 and "No such container" not in stop.stderr:
+            # Best-effort shutdown; container may already be gone.
+            pass
+
+        if self._auto_remove:
+            run_docker(["rm", "-f", self._container_name], timeout=30)
+
+        if self._owns_workspace:
+            import shutil
+
+            shutil.rmtree(self._workspace, ignore_errors=True)
+
+    def __enter__(self) -> DockerSandbox:
+        return self
+
+    def __exit__(self, *_exc: object) -> None:
+        self.close()
+
+    def __del__(self) -> None:
+        try:
+            self.close()
+        except Exception:  # noqa: BLE001, S110
+            pass

deepagents_docker-0.0.1.dist-info/METADATA

@@ -0,0 +1,139 @@
+Metadata-Version: 2.4
+Name: deepagents-docker
+Version: 0.0.1
+Summary: Docker-backed sandbox backend for DeepAgents
+Project-URL: Homepage, https://github.com/andybbruno/deepagents-docker
+Project-URL: Repository, https://github.com/andybbruno/deepagents-docker
+Author: Andrea Bruno
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,deepagents,docker,langchain,langgraph,sandbox
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.12
+Requires-Dist: deepagents>=0.6.7
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="assets/deepagents-docker-banner.png"  width="800" />
+</p>
+<div align="center">
+  <h3>Docker sandbox backend for <a href="https://github.com/langchain-ai/deepagents">Deep Agents</a>.</h3>
+</div>
+
+
+<div align="center">
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python](https://img.shields.io/badge/python-3.12%2B-blue)](https://www.python.org/downloads/)
+[![deepagents](https://img.shields.io/badge/built%20for-deepagents-orange)](https://github.com/langchain-ai/deepagents)
+
+</div>
+
+
+## Quickstart
+
+Requires [Docker](https://docs.docker.com/get-docker/) on your machine.
+
+Install with `uv`:
+```bash
+uv add deepagents-docker
+```
+or with `pip`:
+```bash
+pip install deepagents-docker
+```
+
+```python
+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 image, workspace path, command timeout, resource limits, outbound network access, and any extra `docker run` flags:
+
+```python
+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
+    workspace_dir="/path/to/project",  # host dir for agent files; see note below
+    timeout=120,                       # per-command timeout (seconds)
+    max_output_bytes=100_000,          # combined stdout/stderr cap per command
+    memory="512m",
+    cpus=1.0,
+    pids_limit=128,
+    auto_remove=True,                  # remove container on close()
+    extra_run_args=["--env", "FOO=bar"],
+)
+```
+
+> [!NOTE]
+> When `workspace_dir` is omitted, a temporary directory is created under the host temp folder and **removed on `close()`** when the sandbox owns it. Pass an explicit path to keep files after the container stops.
+
+
+## How it works
+
+`DockerSandbox` implements the Deep Agents backend protocol by splitting work across the host and a container:
+
+- **File tools** (`read`, `write`, `edit`, `grep`, `glob`, `ls`) run against a workspace directory on your machine.
+- **`execute`** runs shell commands in a long-lived Docker container. The same directory is bind-mounted at `/workspace`, so files stay in sync between tools and commands.
+
+On startup, the sandbox creates a container with conservative defaults:
+
+- [`python:3.12-bookworm`](https://hub.docker.com/_/python) as the default image
+- Outbound traffic allowed by default
+- No elevated Linux privileges
+- Read-only root filesystem (with small `tmpfs` mounts for `/tmp` and `/var/tmp`)
+- Memory, CPU, and PID limits
+
+
+> [!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:
+
+```python
+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!")
+```
+
+## Development
+
+```bash
+git clone https://github.com/andybbruno/deepagents-docker.git
+cd deepagents-docker
+uv sync
+uv run pytest
+```
+
+## Security
+
+Use this for trusted workloads and development, not as a hard multi-tenant boundary. Do not put secrets in the workspace. See [Deep Agents security](https://github.com/langchain-ai/deepagents?tab=security-ov-file).
+
+## License
+
+MIT — [LICENSE](LICENSE).

deepagents_docker-0.0.1.dist-info/RECORD

@@ -0,0 +1,7 @@
+deepagents_docker/__init__.py,sha256=9rLXj5-z9zLXbcCmxWatLYJR2xs2SQn30-fugCdlKhM,143
+deepagents_docker/_docker.py,sha256=LShf7lHkefxDc4LZPgttCpnBZVg_jSCRP8EcEjqdFRk,2363
+deepagents_docker/backend.py,sha256=4PuPPLCbwtLaTI3csA8fNx5PSoAxz-vAqLODU7lWJSQ,10089
+deepagents_docker-0.0.1.dist-info/METADATA,sha256=85MCxDk-3QF-JIo3aLd7u9AXSuq-otgXbqwW8_btyCk,4705
+deepagents_docker-0.0.1.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+deepagents_docker-0.0.1.dist-info/licenses/LICENSE,sha256=gjFKP2GBEc-AJ8kf_hWZ4UQ_bWoEpy1PbJoTenKEqSo,1095
+deepagents_docker-0.0.1.dist-info/RECORD,,

deepagents_docker-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

deepagents_docker-0.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepAgents Docker Sandbox contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.