agent-container-sandbox 0.1.1__py3-none-any.whl

agent_container_sandbox/__init__.py

@@ -0,0 +1,36 @@
+"""Container sandbox backends for LangChain DeepAgents."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from .errors import (
+    ContainerNotRunningError,
+    ContainerReuseError,
+    DockerImageNotFound,
+    MissingPythonError,
+    MissingTimeoutError,
+    SandboxError,
+    SpecMismatchError,
+)
+from .managed import ManagedContainerSandbox
+from .provisioning import ContainerProvisioner, ContainerSpec
+from .sandbox import ContainerSandbox
+
+try:
+    __version__ = version("agent-container-sandbox")
+except PackageNotFoundError:  # running from a source checkout without install metadata
+    __version__ = "0+unknown"
+
+__all__ = [
+    "ContainerSandbox",
+    "ContainerProvisioner",
+    "ContainerSpec",
+    "SandboxError",
+    "DockerImageNotFound",
+    "MissingTimeoutError",
+    "MissingPythonError",
+    "ContainerReuseError",
+    "SpecMismatchError",
+    "ContainerNotRunningError",
+    "ManagedContainerSandbox",
+    "__version__",
+]

agent_container_sandbox/errors.py

@@ -0,0 +1,132 @@
+"""Exceptions raised by agent-container-sandbox.
+
+This module only defines exception classes. It must not import anything from
+the rest of the package, so that both ``sandbox`` and ``provisioning`` can
+import from it without risk of circular imports.
+
+Hierarchy::
+
+    SandboxError
+    ├── DockerImageNotFound
+    ├── MissingTimeoutError
+    ├── MissingPythonError
+    └── ContainerReuseError
+        ├── SpecMismatchError
+        └── ContainerNotRunningError
+
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Literal
+
+if TYPE_CHECKING:
+    from docker.models.containers import Container
+
+MismatchReason = Literal["not_created_by_library", "no_fingerprint", "different_spec"]
+
+
+class SandboxError(Exception):
+    """Base class for every error this library raises on purpose.
+
+    Catch this to handle any library-specific failure in one place.
+    """
+
+
+class DockerImageNotFound(SandboxError):
+    """Raised when an image is not available locally (and could not be pulled)."""
+
+    def __init__(self, image: str, detail: str | None = None) -> None:
+        self.image = image
+        message = f"Image '{image}' is not available locally."
+        if detail:
+            message += f" {detail}"
+        else:
+            message += f" Run `docker pull {image}` first, or enable auto_pull."
+        super().__init__(message)
+
+
+class MissingTimeoutError(SandboxError):
+    """Raised when a container cannot run commands under ``timeout``.
+
+    ``ContainerSandbox`` wraps every command in ``timeout``, so the image
+    must ship a ``timeout`` binary (GNU coreutils or compatible).
+    """
+
+
+class MissingPythonError(SandboxError):
+    """Raised when a container has no usable ``python3``.
+
+    The file helpers inherited from ``BaseSandbox`` (``read``, ``write``,
+    ``edit``, ``ls``, ``glob``) run Python inside the container.
+    ``execute`` and the file transfer methods do not need it.
+    """
+
+
+class ContainerReuseError(SandboxError):
+    """Raised when ``get_or_create`` finds the name but will not hand the container out.
+
+    Catch this to handle every reuse failure in one place. The container that
+    failed the check is available as ``container``, so recovery is a one-liner:
+    ``e.container.start()`` or ``provisioner.delete(e.container)``.
+    """
+
+    def __init__(self, name: str, container: Container, message: str) -> None:
+        self.name = name
+        self.container = container
+        super().__init__(message)
+
+
+class SpecMismatchError(ContainerReuseError):
+    """Raised when the container found is not the one this spec describes.
+
+    ``reason`` says which check failed:
+
+    - ``not_created_by_library``: the library's marker label is missing, so
+      the name belongs to something else.
+    - ``no_fingerprint``: the marker label is present but the spec fingerprint
+      is not, which means an earlier library version created it.
+    - ``different_spec``: the container's fingerprint differs from the spec's.
+    """
+
+    def __init__(self, name: str, container: Container, reason: MismatchReason) -> None:
+        self.reason = reason
+        if reason == "not_created_by_library":
+            message = (
+                f"Container '{name}' exists but was not created by agent-container-sandbox, "
+                "so get_or_create will not reuse it. Use another spec.name, or remove it "
+                "with provisioner.delete(e.container) if you are sure it is unused."
+            )
+        elif reason == "no_fingerprint":
+            message = (
+                f"Container '{name}' was created by agent-container-sandbox but has no spec "
+                "fingerprint, probably because an earlier library version created it, so "
+                "get_or_create cannot tell whether it matches this spec. Delete it with "
+                "provisioner.delete(e.container) to get a new one."
+            )
+        else:
+            message = (
+                f"Container '{name}' was created from a different spec (its spec "
+                "fingerprint differs). Delete it with provisioner.delete(e.container) to "
+                "get a fresh one from this spec, or use another spec.name."
+            )
+        super().__init__(name, container, message)
+
+
+class ContainerNotRunningError(ContainerReuseError):
+    """Raised when the container matches the spec but is not running.
+
+    ``status`` is the status string the runtime reported. An expired
+    ``max_lifetime_seconds`` is the common cause.
+    """
+
+    def __init__(self, name: str, container: Container, status: str) -> None:
+        self.status = status
+        super().__init__(
+            name,
+            container,
+            f"Container '{name}' matches the spec but is not running (status: {status}). "
+            "Start it with e.container.start(), or delete it with "
+            "provisioner.delete(e.container) to get a fresh one. An expired "
+            "max_lifetime_seconds is the common cause.",
+        )

agent_container_sandbox/managed.py

@@ -0,0 +1,161 @@
+"""Context manager for scripts: provision, adapt, and always delete.
+
+Convenience layer on top of ``ContainerProvisioner`` and ``ContainerSandbox``
+for the case where the container lives exactly as long as a ``with`` block.
+It adds no capability of its own and delegates everything. For anything more
+complex (reuse, leaving containers behind, direct container access), use the
+provisioner and sandbox directly.
+"""
+
+from __future__ import annotations
+
+import logging
+from types import TracebackType
+
+import docker
+from docker.models.containers import Container
+
+from .provisioning import ContainerProvisioner, ContainerSpec
+from .sandbox import (
+    _DEFAULT_COMMAND_TIMEOUT,
+    _DEFAULT_MAX_OUTPUT_SIZE,
+    ContainerSandbox,
+    _validate_limits,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class ManagedContainerSandbox:
+    """Provision a container, yield a sandbox for it, and always delete it.
+
+    Contract: the container lives exactly as long as the ``with`` block.
+    There is no option to keep it, no reuse of existing containers, and no
+    access to the underlying ``Container`` object. The yielded sandbox exposes
+    ``id`` (the short container ID) for ``docker logs`` / ``docker inspect``.
+
+    Instances are single-use: any second ``__enter__`` raises, even after the
+    first block has exited.
+
+    Args:
+        client: Docker client. Owned by the caller; never closed here.
+        spec: Description of the container to provision. If ``spec.name`` is
+            ``None``, the provisioner generates a unique name.
+        working_dir: Optional override passed to ``ContainerSandbox``. If
+            ``None``, the sandbox discovers the container's configured
+            working directory.
+        command_timeout: Default per-command timeout in seconds, passed to
+            ``ContainerSandbox``.
+        max_output_size: Output truncation limit, passed to
+            ``ContainerSandbox``.
+        verify_timeout: Run ``ContainerSandbox.verify_timeout()`` on entry so
+            an image without a usable ``timeout`` binary fails early with a
+            clear error.
+        verify_python: Run ``ContainerSandbox.verify_python()`` on entry so an
+            image without a usable ``python3`` binary fails early with a clear
+            error.
+    """
+
+    def __init__(
+        self,
+        client: docker.DockerClient,
+        spec: ContainerSpec,
+        *,
+        working_dir: str | None = None,
+        command_timeout: int = _DEFAULT_COMMAND_TIMEOUT,
+        max_output_size: int = _DEFAULT_MAX_OUTPUT_SIZE,
+        verify_timeout: bool = True,
+        verify_python: bool = True,
+    ) -> None:
+        """Store configuration only. No Docker calls happen until ``__enter__``."""
+        _validate_limits(command_timeout=command_timeout, max_output_size=max_output_size)
+        self._client = client
+        self._spec = spec
+        self._working_dir = working_dir
+        self._command_timeout = command_timeout
+        self._max_output_size = max_output_size
+        self._verify_timeout = verify_timeout
+        self._verify_python = verify_python
+        self._provisioner: ContainerProvisioner | None = None
+        self._container: Container | None = None  # private; never exposed
+        self._used = False  # set on first __enter__; never reset
+
+    def __enter__(self) -> ContainerSandbox:
+        """Provision the container and return a sandbox over it.
+
+        Raises:
+            RuntimeError: This instance was already entered (single-use).
+            MissingTimeoutError: ``verify_timeout`` is enabled and the image
+                cannot run commands under ``timeout``.
+            MissingPythonError: ``verify_python`` is enabled and the image
+                cannot run Python commands.
+
+        If anything fails after the container has been created, the container
+        is deleted before the exception propagates, because ``__exit__`` does
+        not run when ``__enter__`` raises.
+        """
+        if self._used:
+            raise RuntimeError(
+                "ManagedContainerSandbox is single-use and was already entered. "
+                "Create a new instance."
+            )
+        self._used = True
+
+        # provision() cleans up after itself on failure, so if it raises there
+        # is no container for us to delete and self._container stays None.
+        self._provisioner = ContainerProvisioner(self._client)
+        self._container = self._provisioner.provision(self._spec)
+
+        try:
+            sandbox = ContainerSandbox(
+                self._container,
+                working_dir=self._working_dir,
+                command_timeout=self._command_timeout,
+                max_output_size=self._max_output_size,
+            )
+            if self._verify_timeout:
+                sandbox.verify_timeout()
+            if self._verify_python:
+                sandbox.verify_python()
+        except BaseException:
+            # __exit__ will not run, so delete the container here.
+            self._cleanup()
+            raise
+
+        return sandbox
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        """Delete the container, even if the body raised.
+
+        The original exception always propagates (this returns a falsy value).
+        A failure during deletion is logged as a warning and never masks the
+        body's exception.
+        """
+        self._cleanup()
+
+    def _cleanup(self) -> None:
+        """Delete the container if one exists, logging instead of raising.
+
+        Shared by ``__enter__`` (failed setup) and ``__exit__``.
+        """
+        # Clear the reference first so a repeated call can never delete twice.
+        container, self._container = self._container, None
+        if container is None or self._provisioner is None:
+            return
+
+        try:
+            self._provisioner.delete(container)
+        except Exception:
+            # Never mask the body's exception (or a failed __enter__'s cause).
+            logger.warning(
+                "Cleanup of container %s failed; it will stop on its own after "
+                "max_lifetime_seconds. Find leftovers with: "
+                "docker ps -a --filter label=created-by=agent-container-sandbox",
+                container.short_id,
+                exc_info=True,
+            )

agent_container_sandbox/provisioning.py

@@ -0,0 +1,273 @@
+"""Container provisioning: create, find, and delete containers.
+
+Owns lifecycle only. ContainerSandbox (sandbox.py) owns the adapter logic and
+never creates or deletes anything. The Docker client is injected and owned by
+the caller; this module never closes it.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import logging
+import shlex
+import uuid
+from dataclasses import asdict, dataclass, field
+from typing import Any
+
+import docker
+from docker.errors import APIError, ImageNotFound
+from docker.models.containers import Container
+
+from .errors import ContainerNotRunningError, DockerImageNotFound, SpecMismatchError
+
+logger = logging.getLogger(__name__)
+
+# Applied to every container this module creates, regardless of what the
+# caller passes in ContainerSpec.labels. Lets a reaper script find orphans
+# ("docker ps -a --filter label=created-by=agent-container-sandbox") even if
+# the caller supplied no labels of their own.
+_MARKER_LABEL_KEY = "created-by"
+_MARKER_LABEL_VALUE = "agent-container-sandbox"
+
+# Hash of the spec a container was created from (see _spec_fingerprint). Set
+# after the marker and the caller's labels, so neither can override it.
+_FINGERPRINT_LABEL_KEY = "agent-container-sandbox.spec-fingerprint"
+
+_DEFAULT_WORKING_DIR = "/workspace"
+_DEFAULT_MAX_LIFETIME_SECONDS = 3600  # hard upper bound; not an idle timeout
+
+
+@dataclass(frozen=True, kw_only=True)
+class ContainerSpec:
+    """Immutable description of a container to provision.
+
+    Fields:
+        image: Image name.
+        name: Container name. optional; None means the provisioner generates
+        a unique name; a name is required for ``ContainerProvisioner.find`` /
+        ``get_or_create``.
+        volumes: Volume mounts, ``{"/host": {"bind": "/container", "mode": "rw"}}``.
+        working_dir: Working directory inside the container. Created if missing.
+        max_lifetime_seconds: Hard upper bound on how long the container's
+            main process runs. The main process is ``sleep <seconds>``, so the
+            container stops on its own even if the caller's process crashes.
+            This is a maximum lifetime, not an idle timeout — Docker has no
+            idle TTL.
+        labels: Additional labels merged with the module's fixed marker
+            label; callers cannot omit or override the marker this way.
+
+    ``get_or_create`` reuses an existing container only if it carries the
+    fingerprint of this spec (every field except ``name``) and is running.
+    """
+
+    image: str
+    name: str | None = None
+    volumes: dict[str, dict[str, str]] = field(default_factory=dict)
+    working_dir: str = _DEFAULT_WORKING_DIR
+    max_lifetime_seconds: int = _DEFAULT_MAX_LIFETIME_SECONDS
+    labels: dict[str, str] = field(default_factory=dict)
+    mem_limit: str | None = "2g"
+    cpus: float | None = 2.0
+    network_mode: str | None = "none"
+    pids_limit: int | None = 512
+    no_new_privileges: bool = True
+    cap_drop_all: bool = True
+    cap_add: tuple[str, ...] = ()
+
+
+def _spec_fingerprint(spec: ContainerSpec) -> str:
+    """SHA-256 of the spec's canonical JSON, excluding ``name``.
+
+    The name is the lookup key, and ``provision`` generates one when it is
+    None, so including it would stop a container created from a nameless spec
+    from ever matching. ``cap_add`` is sorted because its order is irrelevant;
+    dictionary keys are sorted by the JSON encoder.
+    """
+    data = asdict(spec)
+    data.pop("name")
+    data["cap_add"] = sorted(data["cap_add"])
+    canonical = json.dumps(data, sort_keys=True, separators=(",", ":"))
+    return hashlib.sha256(canonical.encode()).hexdigest()
+
+
+def _hardening_kwargs(spec: ContainerSpec) -> dict[str, Any]:
+    """Translate the spec's hardening fields into ``containers.create`` arguments.
+
+    Disabled settings are omitted, except ``pids_limit``: it is sent as -1
+    ("unlimited") so the daemon's own default cannot silently apply.
+    """
+    kwargs: dict[str, Any] = {}
+    if spec.mem_limit is not None:
+        kwargs["mem_limit"] = spec.mem_limit
+        kwargs["memswap_limit"] = spec.mem_limit  # no swap beyond the cap
+    if spec.cpus is not None:
+        kwargs["nano_cpus"] = int(spec.cpus * 1_000_000_000)
+    if spec.network_mode is not None:
+        kwargs["network_mode"] = spec.network_mode
+    # Always sent. Omitting it would let the daemon apply its own default
+    # (2048 on Podman), so None would not actually mean "unlimited".
+    kwargs["pids_limit"] = spec.pids_limit if spec.pids_limit is not None else -1
+    if spec.no_new_privileges:
+        kwargs["security_opt"] = ["no-new-privileges:true"]
+    if spec.cap_drop_all:
+        kwargs["cap_drop"] = ["ALL"]
+    if spec.cap_add:
+        kwargs["cap_add"] = list(spec.cap_add)
+    return kwargs
+
+
+class ContainerProvisioner:
+    """Creates, finds, and deletes containers via an injected Docker client.
+
+    Concurrency note: ``get_or_create`` is not safe against two callers
+    racing to create a container with the same name at the same time; this
+    is a documented limitation, not handled by retrying on a name conflict.
+    """
+
+    def __init__(self, client: docker.DockerClient) -> None:
+        self._client = client
+
+    def _check_image(self, image: str, auto_pull: bool = False) -> None:
+        """Ensure ``image`` is available locally, optionally pulling it.
+
+        Args:
+            image: Image name and tag, e.g. ``"python:3.13-slim"``.
+            auto_pull: If True, pull the image when it is not found locally.
+                If False (the default), a missing image raises immediately.
+
+        Raises:
+            DockerImageNotFound: The image is missing and ``auto_pull`` is False,
+                or the pull was attempted and failed (the cause is chained).
+            docker.errors.APIError: The Docker daemon failed while checking for
+                the image. Propagated unchanged.
+        """
+        try:
+            self._client.images.get(image)
+        except ImageNotFound:
+            if not auto_pull:
+                raise DockerImageNotFound(image) from None
+            try:
+                self._client.images.pull(image)
+            except APIError as e:
+                raise DockerImageNotFound(image, detail=f"Pulling it failed: {e}") from e
+
+    def provision(self, spec: ContainerSpec) -> Container:
+        """Create and start a new container from ``spec`` and prepare it for use.
+
+        If anything fails after the container has been created (starting it or
+        creating the working directory), the container is deleted before the
+        exception propagates, so a failed call never leaves a container behind.
+        If creation itself fails (for example a name conflict), nothing is
+        deleted: no container was created by this call.
+        """
+        self._check_image(spec.image, auto_pull=True)
+        name = spec.name or f"agent-container-sandbox-{uuid.uuid4().hex[:12]}"
+        # The main process is only a placeholder that keeps the container alive;
+        # real work arrives later via exec_run. The entrypoint is set explicitly so
+        # an image's own ENTRYPOINT cannot interfere, and init=True runs it behind
+        # tini so SIGTERM is forwarded and orphaned child processes are reaped.
+        container = self._client.containers.create(
+            image=spec.image,
+            name=name,
+            entrypoint=["sleep", str(spec.max_lifetime_seconds)],
+            working_dir=spec.working_dir,
+            volumes=spec.volumes,
+            labels={
+                **spec.labels,
+                _MARKER_LABEL_KEY: _MARKER_LABEL_VALUE,
+                _FINGERPRINT_LABEL_KEY: _spec_fingerprint(spec),
+            },
+            stdin_open=False,
+            init=True,
+            tty=False,
+            **_hardening_kwargs(spec),
+        )
+
+        # Everything from here on may leave a created container behind, so start()
+        # belongs inside the try. create() stays outside: if it raises, no container
+        # was assigned and a same-named one belongs to someone else.
+        try:
+            container.start()
+            exit_code, output_bytes = container.exec_run(
+                cmd=["sh", "-c", f"mkdir -p {shlex.quote(spec.working_dir)}"],
+                workdir=spec.working_dir,
+            )
+            if exit_code != 0:
+                detail = (output_bytes or b"").decode("utf-8", errors="replace")
+                raise RuntimeError(f"mkdir -p {spec.working_dir} failed: {detail}")
+        except BaseException:
+            try:
+                self.delete(container)
+            except Exception:
+                logger.warning("Cleanup of %s failed", container.short_id, exc_info=True)
+            raise
+
+        return container
+
+    def find(self, name: str) -> Container | None:
+        """Look up an existing container by name.
+
+        Returns:
+            The container if one with this name exists, else ``None``.
+            Does not distinguish "never existed" from "existed and was
+            removed" — both return ``None``.
+        """
+        candidates = self._client.containers.list(all=True, filters={"name": name})
+        exact = [c for c in candidates if c.name == name]
+        return exact[0] if exact else None
+
+    def _check_reusable(self, container: Container, spec: ContainerSpec) -> None:
+        """Raise unless ``container`` is the running container ``spec`` describes.
+
+        Identity before state: a stopped container with a different spec raises
+        ``SpecMismatchError``, because "just start it" would be wrong advice.
+        """
+        labels = container.labels or {}
+        name = spec.name or ""
+        if labels.get(_MARKER_LABEL_KEY) != _MARKER_LABEL_VALUE:
+            raise SpecMismatchError(name, container, "not_created_by_library")
+        stored = labels.get(_FINGERPRINT_LABEL_KEY)
+        if stored is None:
+            raise SpecMismatchError(name, container, "no_fingerprint")
+        if stored != _spec_fingerprint(spec):
+            raise SpecMismatchError(name, container, "different_spec")
+        if container.status != "running":
+            raise ContainerNotRunningError(name, container, container.status)
+
+    def get_or_create(self, spec: ContainerSpec) -> Container:
+        """Return the running container created from ``spec``, or provision one.
+
+        Looks the container up by ``spec.name``. If one exists, it must carry
+        the library's marker label and the fingerprint of this exact spec, and
+        it must be running. Nothing is started, stopped or deleted on failure.
+
+        Raises:
+            ValueError: ``spec.name`` is empty.
+            SpecMismatchError: The container is not the one this spec describes
+                (see its ``reason``).
+            ContainerNotRunningError: It is the right container but not running.
+        """
+        if not spec.name:
+            raise ValueError("get_or_create requires spec.name; it is the lookup key.")
+        container = self.find(spec.name)
+        if container:
+            self._check_reusable(container, spec)
+            return container
+        return self.provision(spec)
+
+    def delete(self, container: Container) -> None:
+        """Stop and remove a container.
+
+        Tolerates the container already being gone (``docker.errors.NotFound``,
+        from either ``stop()`` or ``remove()``) without raising, since that's a
+        successful end state, not a failure.
+        """
+        try:
+            container.stop(timeout=5)
+            container.remove(force=True)
+        except docker.errors.NotFound:
+            logger.debug("Container %s already gone", container.short_id)
+            return
+
+        logger.info("Container %s removed", container.short_id)

agent_container_sandbox/sandbox.py

@@ -0,0 +1,310 @@
+from __future__ import annotations
+
+import codecs
+import io
+import logging
+import shlex
+import tarfile
+import threading
+import time
+from typing import Any
+
+import docker
+from deepagents.backends.protocol import (
+    ExecuteResponse,
+    FileDownloadResponse,
+    FileUploadResponse,
+)
+from deepagents.backends.sandbox import BaseSandbox
+from docker.models.containers import Container
+
+from .errors import MissingPythonError, MissingTimeoutError
+
+logger = logging.getLogger(__name__)
+
+_DEFAULT_COMMAND_TIMEOUT = 150  # seconds
+_DEFAULT_MAX_OUTPUT_SIZE = 64 * 1024  # 64 KiB
+_KILL_DELAY = 2  # seconds to wait after sending SIGTERM before sending SIGKILL
+_GO_MODE_DIR = 1 << 31  # os.ModeDir: Docker's path stat uses Go's FileMode, not POSIX bits
+_TIMEOUT_GRACE_SECONDS = 5  # headroom for the container-side kill to land before we give up waiting
+_TIMEOUT_PROBE = "timeout -k 1 1 true"  # must match the form execute() uses
+_PYTHON_PROBE = "python3 -c pass"
+_POSIX_TIMEOUT_EXIT_CODE = 124
+_SANDBOX_ERROR_PREFIX = "Sandbox error:"
+
+
+def _decode_and_truncate(raw: bytes, limit: int) -> tuple[str, bool]:
+    """Decode command output, cutting it at ``limit`` raw bytes.
+
+    No note is appended: deepagents' helpers parse the output and only forgive a
+    torn final line when ``truncated`` is set, and its execute tool adds its own
+    notice from that flag.
+    """
+    if len(raw) <= limit:
+        return raw.decode("utf-8", errors="replace"), False
+    decoder = codecs.getincrementaldecoder("utf-8")(errors="replace")
+    return decoder.decode(raw[:limit], final=False), True  # holds back a split trailing character
+
+
+def _resolve_path(path: str, working_dir: str) -> str:
+    return path if path.startswith("/") else f"{working_dir}/{path}"
+
+
+def _build_single_file_tar(file_path: str, content: bytes) -> io.BytesIO:
+    """Build a single-file tar archive ready for put_archive."""
+    tar_stream = io.BytesIO()
+    with tarfile.open(fileobj=tar_stream, mode="w") as tar:
+        info = tarfile.TarInfo(name=file_path.lstrip("/"))
+        info.size = len(content)
+        info.mtime = int(time.time())  # TarInfo defaults to 0, which dates files 1970
+        tar.addfile(info, io.BytesIO(content))
+    tar_stream.seek(0)
+    return tar_stream
+
+
+def _is_directory(path_stat: dict | None) -> bool:
+    return path_stat is not None and bool(path_stat.get("mode", 0) & _GO_MODE_DIR)
+
+
+def _extract_single_file(tar_data: io.BytesIO) -> tuple[bytes | None, str | None]:
+    """Given a downloaded tar archive, return (content, error)."""
+    with tarfile.open(fileobj=tar_data, mode="r") as tar:
+        members = tar.getmembers()
+        f = tar.extractfile(members[0]) if members else None
+        if f is None:
+            return None, "file_not_found"
+        return f.read(), None
+
+
+def _validate_limits(*, command_timeout: int, max_output_size: int) -> None:
+    """Reject settings that have no sensible meaning. Raises ValueError."""
+    if command_timeout <= 0:
+        raise ValueError(f"command_timeout must be positive, got {command_timeout}.")
+    if max_output_size <= 0:
+        raise ValueError(f"max_output_size must be positive, got {max_output_size}.")
+
+
+class ContainerSandbox(BaseSandbox):
+    """Deep Agents sandbox backed by an existing, running Docker container.
+
+    A thin adapter: it runs commands and transfers files inside a container
+    you already have. It never creates, stops, or removes containers and never
+    closes the Docker client. Use ``ContainerProvisioner`` for lifecycle.
+
+    The container image must provide ``sh`` and a ``timeout`` binary.
+    Commands exceeding their timeout are killed inside the container and
+    return exit code 124.
+
+    Args:
+        container: A running container. The caller owns its lifecycle.
+        working_dir: Directory used for commands and relative paths. If None,
+            the container's configured working directory is used (``/`` if the
+            image sets none). If given, it must already exist.
+        command_timeout: Default per-command timeout in seconds.
+        max_output_size: Output beyond this size is truncated.
+    """
+
+    def __init__(
+        self,
+        container: Container,
+        *,
+        working_dir: str | None = None,
+        command_timeout: int = _DEFAULT_COMMAND_TIMEOUT,
+        max_output_size: int = _DEFAULT_MAX_OUTPUT_SIZE,
+    ) -> None:
+        _validate_limits(command_timeout=command_timeout, max_output_size=max_output_size)
+        self._container = container
+        self._working_dir = working_dir or self._discover_working_dir()
+        self._default_timeout = command_timeout
+        self._max_output_bytes = max_output_size
+
+    @property
+    def id(self) -> str:
+        return self._container.short_id
+
+    def execute(
+        self,
+        command: str,
+        *,
+        timeout: int | None = None,
+    ) -> ExecuteResponse:
+        if not command or not isinstance(command, str):
+            return ExecuteResponse(
+                output=f"{_SANDBOX_ERROR_PREFIX} Command must be a non-empty string.",
+                exit_code=1,
+                truncated=False,
+            )
+        if timeout is not None and timeout <= 0:
+            return ExecuteResponse(
+                output=(
+                    f"{_SANDBOX_ERROR_PREFIX} timeout must be a positive "
+                    f"number of seconds (got {timeout})."
+                ),
+                exit_code=1,
+                truncated=False,
+            )
+        effective_timeout = timeout if timeout is not None else self._default_timeout
+
+        result_holder: dict[str, Any] = {}
+        execution_done = threading.Event()
+
+        def run_command() -> None:
+            try:
+                exit_code, output_bytes = self._container.exec_run(
+                    cmd=[
+                        "timeout",
+                        "-k",
+                        str(_KILL_DELAY),
+                        str(effective_timeout),
+                        "sh",
+                        "-c",
+                        command,
+                    ],
+                    stdout=True,
+                    stderr=True,
+                    demux=False,
+                    workdir=self._working_dir,
+                )
+                output, truncated = _decode_and_truncate(
+                    output_bytes or b"", self._max_output_bytes
+                )
+                if exit_code == _POSIX_TIMEOUT_EXIT_CODE:
+                    output += (
+                        f"\n\n[Command timed out after {effective_timeout} seconds and was killed.]"
+                    )
+                result_holder.update(exit_code=exit_code, output=output, truncated=truncated)
+            except Exception as e:
+                result_holder.update(
+                    exit_code=1,
+                    output=(
+                        f"{_SANDBOX_ERROR_PREFIX} Error executing command: {type(e).__name__}: {e}"
+                    ),
+                    truncated=False,
+                )
+            finally:
+                execution_done.set()
+
+        thread = threading.Thread(target=run_command, daemon=True)
+        thread.start()
+
+        if not execution_done.wait(
+            timeout=effective_timeout + _KILL_DELAY + _TIMEOUT_GRACE_SECONDS
+        ):
+            # The container's own `timeout` should have killed the command by
+            # effective_timeout. Reaching here means even that didn't work --
+            # Docker itself is unresponsive, not just the command running long.
+            return ExecuteResponse(
+                output=(
+                    f"{_SANDBOX_ERROR_PREFIX} No response from Docker within "
+                    f"{effective_timeout + _KILL_DELAY + _TIMEOUT_GRACE_SECONDS} seconds; "
+                    f"the command's state is unknown. The sandbox may be unhealthy."
+                ),
+                exit_code=124,
+                truncated=False,
+            )
+
+        return ExecuteResponse(
+            output=result_holder["output"],
+            exit_code=result_holder["exit_code"],
+            truncated=result_holder["truncated"],
+        )
+
+    def upload_files(self, files: list[tuple[str, bytes]]) -> list[FileUploadResponse]:
+        """Upload files to the container via tar archive."""
+        responses: list[FileUploadResponse] = []
+
+        for file_path, content in files:
+            try:
+                file_path = _resolve_path(file_path, self._working_dir)
+                dir_path = file_path.rsplit("/", 1)[0] or "/"
+
+                tar_stream = _build_single_file_tar(file_path, content)
+
+                mkdir_result = self.execute(f"mkdir -p {shlex.quote(dir_path)}")
+                if mkdir_result.exit_code != 0:
+                    raise RuntimeError(f"mkdir -p {dir_path} failed: {mkdir_result.output}")
+
+                # put_archive would silently replace a directory with a file (observed
+                # on Podman), deleting its content. Not atomic with the write below.
+                check = self.execute(f"test -d {shlex.quote(file_path)}")
+                if check.exit_code == 0:
+                    raise IsADirectoryError(
+                        f"{file_path} is an existing directory; refusing to replace it"
+                    )
+
+                self._container.put_archive("/", tar_stream)
+
+                responses.append(FileUploadResponse(path=file_path, error=None))
+                logger.debug("Uploaded file: %s (%d bytes)", file_path, len(content))
+
+            except Exception as e:
+                error_msg = f"Failed to upload {file_path}: {type(e).__name__}: {e}"
+                logger.error("%s", error_msg)
+                responses.append(FileUploadResponse(path=file_path, error=error_msg))
+
+        return responses
+
+    def _download_one(self, file_path: str) -> FileDownloadResponse:
+        path = _resolve_path(file_path, self._working_dir)
+        try:
+            tar_stream, path_stat = self._container.get_archive(path)
+            if _is_directory(path_stat):
+                # Return before iterating: a large directory is never loaded into memory.
+                return FileDownloadResponse(path=file_path, content=None, error="is_directory")
+            tar_data = io.BytesIO()
+            for chunk in tar_stream:
+                tar_data.write(chunk)
+            tar_data.seek(0)
+            content, error = _extract_single_file(tar_data)
+        except docker.errors.NotFound:
+            content, error = None, self._not_found_error(path)
+        except Exception as e:
+            error_msg = f"Failed to download {path}: {type(e).__name__}: {e}"
+            logger.error("%s", error_msg)
+            content, error = None, error_msg
+        return FileDownloadResponse(path=file_path, content=content, error=error)
+
+    def _not_found_error(self, path: str) -> str:
+        """The daemon raises NotFound for a missing file and for a missing container."""
+        try:
+            self._container.reload()
+        except docker.errors.NotFound:
+            return f"Failed to download {path}: container no longer exists"
+        except Exception:
+            logger.debug("reload() failed while classifying NotFound", exc_info=True)
+        return "file_not_found"
+
+    def download_files(self, paths: list[str]) -> list[FileDownloadResponse]:
+        return [self._download_one(p) for p in paths]
+
+    def verify_timeout(self) -> None:
+        """Raise if the container cannot run commands under ``timeout``."""
+        exit_code, output_bytes = self._container.exec_run(
+            cmd=["sh", "-c", _TIMEOUT_PROBE],
+            workdir="/",  # not working_dir: the probe shouldn't depend on it existing
+        )
+        if exit_code != 0:
+            detail = (output_bytes or b"").decode("utf-8", errors="replace").strip()
+            raise MissingTimeoutError(
+                f"Container image cannot run `{_TIMEOUT_PROBE}` (exit {exit_code}): "
+                f"{detail}. ContainerSandbox requires a `timeout` binary "
+                f"(GNU coreutils or compatible)."
+            )
+
+    def verify_python(self) -> None:
+        """Raise if the container has no usable ``python3``."""
+        exit_code, output_bytes = self._container.exec_run(
+            cmd=["sh", "-c", _PYTHON_PROBE], workdir="/"
+        )
+        if exit_code != 0:
+            detail = (output_bytes or b"").decode("utf-8", errors="replace").strip()
+            raise MissingPythonError(
+                f"Container cannot run `{_PYTHON_PROBE}` (exit {exit_code}): {detail}. "
+                "The file helpers inherited from BaseSandbox (read, write, edit, ls, glob) "
+                "need `python3`. If you only use execute and file transfer, you can skip this "
+                "check (e.g., verify_python=False in ManagedContainerSandbox)."
+            )
+
+    def _discover_working_dir(self) -> str:
+        self._container.reload()  # refresh attrs from the daemon
+        return self._container.attrs.get("Config", {}).get("WorkingDir") or "/"

agent_container_sandbox-0.1.1.dist-info/METADATA

@@ -0,0 +1,334 @@
+Metadata-Version: 2.4
+Name: agent-container-sandbox
+Version: 0.1.1
+Summary: Docker container sandbox for LangChain Deep Agents, with the container lifecycle kept separate from the sandbox.
+Keywords: langchain,deepagents,docker,sandbox,agents
+Author: Konovor
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Dist: deepagents>=0.7.10,<0.8
+Requires-Dist: docker>=7.2.0
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/Konovor/agent-container-sandbox
+Project-URL: Issues, https://github.com/Konovor/agent-container-sandbox/issues
+Description-Content-Type: text/markdown
+
+# agent-container-sandbox
+
+Docker container sandbox for [LangChain Deep Agents](https://github.com/langchain-ai/deepagents): run commands and move files inside a container, with the container lifecycle kept separate from the sandbox itself.
+
+- **`ContainerSandbox`** is a thin adapter around a container you already have. It runs commands and transfers files. It never creates, stops, or removes containers.
+- **`ContainerProvisioner`** creates, finds, and deletes containers. It never runs your commands.
+- **`ContainerSpec`** is an immutable description of the container you want.
+- **`ManagedContainerSandbox`** is a context manager for scripts. It provisions a container, hands you a `ContainerSandbox`, and always deletes the container when the `with` block ends.
+
+You own the Docker client. The library never closes it. You also own the container lifecycle, unless you hand it to `ManagedContainerSandbox`.
+
+## Installation
+
+```bash
+pip install agent-container-sandbox
+```
+
+or with uv: `uv add agent-container-sandbox`. To install from git instead: `uv add git+https://github.com/Konovor/agent-container-sandbox@v0.1.1`.
+
+**Prerequisites**
+
+- Docker installed and running. Podman works through its Docker-compatible socket: point `DOCKER_HOST` at it, and `docker.from_env()` picks it up.
+- An image that provides `sh`, `sleep`, and `timeout` (GNU coreutils). Very minimal images (for example `scratch`-based ones) will not work.
+- `python3` in the image, if you use the file helpers inherited from `BaseSandbox` (`read`, `write`, `edit`, `ls`, `glob`). They run Python inside the container. Without it, `read`, `write`, `edit` and `glob` return an error, but `ls` returns an empty list instead of an error. `grep`, `execute`, `upload_files` and `download_files` do not need it (observed with deepagents 0.7.19 and 0.7.32). `ManagedContainerSandbox` checks for `python3` by default and fails early if it is missing.
+
+The recommended image meets all of this:
+
+```bash
+docker pull ghcr.io/astral-sh/uv:0.10.0-python3.13-trixie-slim
+```
+
+Pulling beforehand is optional: the provisioner pulls a missing image automatically (this needs registry access and can make the first `provision()` slow). If the pull fails, it raises `DockerImageNotFound`.
+
+## Quick start
+
+```python
+import docker
+
+from agent_container_sandbox import ContainerSpec, ManagedContainerSandbox
+
+IMAGE = "ghcr.io/astral-sh/uv:0.10.0-python3.13-trixie-slim"
+
+client = docker.from_env()
+try:
+    with ManagedContainerSandbox(client, ContainerSpec(image=IMAGE)) as sandbox:
+        result = sandbox.execute("echo 'Hello from your sandbox!'")
+        print(result.output)  # Hello from your sandbox!
+        print(result.exit_code)  # 0
+finally:
+    client.close()
+```
+
+The container is deleted when the block ends, even if the body raises. You still close the client yourself.
+
+Pass any `docker.DockerClient`; see the docker-py documentation for remote and TLS setups.
+
+### Manual lifecycle
+
+Use the provisioner and sandbox directly when you need reuse, want to leave the container running, or need the `Container` object:
+
+```python
+import docker
+
+from agent_container_sandbox import ContainerProvisioner, ContainerSandbox, ContainerSpec
+
+IMAGE = "ghcr.io/astral-sh/uv:0.10.0-python3.13-trixie-slim"
+
+client = docker.from_env()
+provisioner = ContainerProvisioner(client)
+container = provisioner.provision(ContainerSpec(image=IMAGE, name="my-sandbox"))
+
+try:
+    sandbox = ContainerSandbox(container)
+    print(sandbox.execute("echo 'Hello from your sandbox!'").output)
+finally:
+    provisioner.delete(container)
+    client.close()
+```
+
+Always delete the container in a `finally` block. If your process crashes, `max_lifetime_seconds` (see below) is the safety net.
+
+## Using it with an agent
+
+Any LangChain chat model works. This example uses Google Gemini, which requires `langchain-google-genai` and a `GOOGLE_API_KEY`.
+
+```python
+from deepagents import create_deep_agent
+from langchain.chat_models import init_chat_model
+
+# `sandbox` is the ContainerSandbox from the snippets above
+agent = create_deep_agent(
+    model=init_chat_model("google_genai:gemini-3.5-flash-lite"),
+    system_prompt="You are a coding assistant with sandbox access.",
+    backend=sandbox,
+)
+result = agent.invoke(
+    {"messages": [{"role": "user", "content": "Write and run a script for Armstrong numbers"}]}
+)
+```
+
+The container has no network by default, so tasks that need `pip install`, `git clone` or web requests require `ContainerSpec(image=IMAGE, network_mode="bridge")`.
+
+For plain LangChain agents, pass the sandbox through `FilesystemMiddleware(backend=sandbox)` from `deepagents.middleware.filesystem`.
+
+With `ManagedContainerSandbox`, keep the agent call inside the `with` block. The container is gone afterwards.
+
+### Direct usage
+
+`ContainerSandbox` inherits the file helpers from `BaseSandbox` (`read`, `write`, `ls`, `edit`, and so on) and adds binary transfer:
+
+```python
+sandbox.write("/workspace/test.txt", "Hello, World!")
+
+sandbox.upload_files([("data.bin", b"\x00\x01\x02")])  # relative paths resolve to working_dir
+files = sandbox.download_files(["data.bin"])
+print(files[0].content)  # b'\x00\x01\x02'
+
+result = sandbox.execute("sleep 10", timeout=2)
+print(result.exit_code)  # 124
+```
+
+`upload_files` and `download_files` are intended for the developer, not the model: you control what enters the sandbox and what you extract.
+
+## Container lifecycle
+
+### `ContainerSpec`
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `image` | `str` | required | Image name. Pulled automatically if missing locally. |
+| `name` | `str \| None` | `None` | Container name. If omitted, a unique name is generated. Required for `find` and `get_or_create`, where it is the lookup key. |
+| `volumes` | `dict` | `{}` | Mounts, e.g. `{"/host": {"bind": "/container", "mode": "rw"}}`. |
+| `working_dir` | `str` | `/workspace` | Working directory. Created if missing. |
+| `max_lifetime_seconds` | `int` | `3600` | Hard upper bound on the container's life (see below). |
+| `labels` | `dict` | `{}` | Extra labels. The marker label below and a spec fingerprint label are always added and cannot be overridden. |
+| `mem_limit` | `str \| None` | `"2g"` | Memory cap. Swap is capped at the same value. `None` = unlimited. |
+| `cpus` | `float \| None` | `2.0` | CPU cap in cores. `None` = unlimited. |
+| `network_mode` | `str \| None` | `"none"` | Container network mode. `"none"` disables networking. Use `"bridge"` for normal network access. `"host"` shares the host's network stack and removes the isolation. `None` sends nothing, so the daemon's default applies (usually full network access). |
+| `pids_limit` | `int \| None` | `512` | Maximum processes and threads. `None` = unlimited. |
+| `no_new_privileges` | `bool` | `True` | Block privilege gain through setuid binaries. |
+| `cap_drop_all` | `bool` | `True` | Drop all Linux capabilities. |
+| `cap_add` | `tuple[str, ...]` | `()` | Capabilities to add back after dropping, e.g. `("CHOWN", "DAC_OVERRIDE")`. |
+
+All fields are keyword-only: write `ContainerSpec(image=IMAGE)`, not `ContainerSpec(IMAGE)`.
+
+### `ContainerProvisioner`
+
+| Method | Description |
+|--------|-------------|
+| `provision(spec)` | Create and start a new container. Cleans up after itself if setup fails. |
+| `find(name)` | Return the container with exactly this name, or `None`. |
+| `get_or_create(spec)` | Return the running container created from this spec, looked up by `spec.name`, or provision one. Raises `SpecMismatchError` or `ContainerNotRunningError` if the existing container does not match or is not running. |
+| `delete(container)` | Stop and remove a container. Tolerates it already being gone. |
+
+**Reusing containers.** `get_or_create` lets several `ContainerSandbox` objects share one container, or attach to one that another process started from the same spec. It looks the container up by `spec.name` and hands it out only if it carries the library's marker label and the fingerprint of this exact spec (every field except `name`), and is running. Otherwise it raises and leaves the container as it is: nothing is started, stopped, or deleted. The error carries the container as `e.container`, so you can recover without a second lookup:
+
+```python
+from agent_container_sandbox import ContainerNotRunningError, SpecMismatchError
+
+try:
+    container = provisioner.get_or_create(spec)
+except ContainerNotRunningError as e:
+    e.container.start()  # or provisioner.delete(e.container), then get_or_create(spec) again
+    container = e.container
+except SpecMismatchError as e:
+    # e.reason: "not_created_by_library", "no_fingerprint" or "different_spec"
+    provisioner.delete(e.container)  # only if you are sure it is unused
+    container = provisioner.get_or_create(spec)
+```
+
+A container that is not running is usually one whose `max_lifetime_seconds` has expired. A `SpecMismatchError` means the container is not the one your spec describes, so check what it is before you delete it. Catch `ContainerReuseError` to handle both failures in one place.
+
+`find()` does not verify the container, and `get_or_create()` does. `ContainerSandbox` accepts any running container as it is and does not check its configuration, so the hardening only applies to containers created from a `ContainerSpec`. A sandbox over a container that did not come from your spec uses that container's own working directory, which may differ from your spec. `ManagedContainerSandbox` does not reuse containers.
+
+### `ManagedContainerSandbox`
+
+A convenience layer over `ContainerProvisioner` and `ContainerSandbox`. It adds no capability of its own.
+
+```python
+with ManagedContainerSandbox(client, spec) as sandbox:
+    ...  # sandbox is a ContainerSandbox
+```
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `client` | `DockerClient` | required | Your Docker client. Never closed by this class. |
+| `spec` | `ContainerSpec` | required | The container to provision. If `spec.name` is `None`, a unique name is generated. |
+| `working_dir` | `str \| None` | container's configured working directory | Passed to `ContainerSandbox`. |
+| `command_timeout` | `int` | `150` | Passed to `ContainerSandbox`. Must be positive. |
+| `max_output_size` | `int` | `65536` | Passed to `ContainerSandbox`. Must be positive. |
+| `verify_timeout` | `bool` | `True` | Run `verify_timeout()` on entry, so an image without a usable `timeout` binary fails early. |
+| `verify_python` | `bool` | `True` | Run `verify_python()` on entry, so an image without `python3` fails early. Set it to `False` if you only use `execute` and file transfer. |
+
+- **Cleanup is guaranteed.** The container is deleted on exit, including when the body raises. If setup fails after the container was created (for example `MissingTimeoutError` or `MissingPythonError`), it is deleted before the exception propagates.
+- **Errors are never masked.** If deletion itself fails, a warning is logged and your original exception still propagates. The container then stops on its own after `max_lifetime_seconds`.
+- **Single-use.** Entering the same instance twice raises `RuntimeError`. Create a new instance.
+- **Fixed names can collide.** With an explicit `spec.name`, entering while a container of that name still exists fails with a docker-py error. Omit the name unless you need it.
+
+### How the container is kept alive
+
+The provisioner starts the container with a placeholder process, `sleep <max_lifetime_seconds>`, and real work arrives later through `exec_run`. When the sleep ends, the container stops on its own, even if your Python process crashed. This is a maximum lifetime, not an idle timeout (Docker has no idle TTL), so raise `max_lifetime_seconds` for long sessions.
+
+### Hardening
+
+Containers are hardened by default, to limit the damage an agent can do to the host by accident or by mistake. Every setting is a `ContainerSpec` field.
+
+| Setting | Default | Protects against | What the agent sees when it hits the limit |
+|---------|---------|------------------|--------------------------------------------|
+| `mem_limit` (plus equal swap cap) | `2g` | A runaway allocation exhausting host memory | The process is killed: `Killed`, exit code `137` |
+| `pids_limit` | `512` | Fork bombs exhausting the host's process table | `Cannot fork` errors from the shell |
+| `cpus` | `2.0` | One container starving the rest of the host | Commands run slower, so they reach their timeout sooner |
+| `network_mode` | `none` | Reaching your LAN, cloud metadata endpoints, and the internet | Name-resolution or connection errors, for example `Temporary failure in name resolution` |
+| `no_new_privileges` | on | Privilege escalation through setuid binaries such as `sudo` | `sudo` and similar tools stop working |
+| `cap_drop_all` | on | Kernel attack surface reachable through Linux capabilities | `Permission denied` on some root-only operations |
+
+Mention these limits in your system prompt or tool description, so the model can tell an exceeded limit from a bug in its own code.
+
+**Adjusting the defaults.** Set a field to `None` or `False` to remove a restriction, for example `ContainerSpec(image=IMAGE, mem_limit="8g", pids_limit=None)`. `pids_limit=None` sends an explicit unlimited value, so a daemon-wide default (Podman applies 2048, for example) cannot apply. For the network, `network_mode="bridge"` allows access, which reaches your LAN, cloud metadata endpoints, and the internet, and `None` leaves the daemon's default. `"host"` shares the host's network stack and removes the isolation entirely. With all capabilities dropped, root inside the container loses some abilities. The most likely surprise is writing to a mounted host directory owned by another user, which needs `DAC_OVERRIDE`. `apt-get` needs `SETUID`, `SETGID`, and `CHOWN`, plus a `network_mode` that allows network access. Add back only what you need with `cap_add=("CHOWN", "DAC_OVERRIDE")`.
+
+**Verifying the setup.** Confirm that Docker applied the settings:
+
+```python
+sandbox.execute("grep -E 'CapEff|NoNewPrivs' /proc/self/status")
+# CapEff: 0000000000000000, NoNewPrivs: 1   (with the default empty cap_add)
+```
+
+### Finding orphans
+
+Every container created by this library carries the label `created-by=agent-container-sandbox`, even if you pass no labels. To list leftovers:
+
+```bash
+docker ps -a --filter label=created-by=agent-container-sandbox
+```
+
+## Execution behavior
+
+### `ContainerSandbox`
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `container` | `Container` | required | A running container. You own its lifecycle. |
+| `working_dir` | `str \| None` | container's configured working directory (`/` if none) | Directory for commands and relative paths. If omitted, it is read from the container's configuration, which for provisioned containers is `ContainerSpec.working_dir`. If you pass it explicitly, it must already exist. |
+| `command_timeout` | `int` | `150` | Default per-command timeout in seconds. Must be positive. |
+| `max_output_size` | `int` | `65536` | Output beyond this many bytes is truncated. Must be positive. |
+
+A non-positive `command_timeout` or `max_output_size` raises `ValueError` in the constructor, before any call to Docker. `execute()` returns the deepagents `ExecuteResponse` (`output`, `exit_code`, `truncated`).
+
+- **`timeout` must be positive.** A per-call `timeout` of zero or less is rejected without running anything: `execute()` returns exit code `1` and a `Sandbox error:` message that names the value. Zero does not mean "no limit" here. For long-running commands, pass a large value instead.
+- **Timeouts are enforced inside the container.** Each command runs as `timeout -k 2 N sh -c <command>`: SIGTERM at the deadline, SIGKILL 2 seconds later if the process is still running. The exit code is `124` after a normal timeout. It is `137` when SIGKILL was needed, which is also the code for an out-of-memory kill. Busybox-based images such as Alpine report `143` instead, without the "timed out" note. Processes that detach (`setsid`, double fork) can outlive `timeout`. Deleting the container is the only hard guarantee.
+- **Docker-level hangs are reported separately.** If Docker itself does not answer within the timeout plus 7 seconds, you get exit code `124` and a message that the command's state is unknown and the sandbox may be unhealthy. The command may still be running.
+- **Output is truncated by bytes**, without splitting a UTF-8 character, and `truncated` is set to `True`. Output is read fully into memory first, so avoid commands that print gigabytes.
+- **Errors raised by the sandbox itself** are prefixed with `Sandbox error:` in `output`, to tell them apart from errors printed by your command.
+
+`download_files` reports problems per file in `FileDownloadResponse.error`: `"file_not_found"`, `"is_directory"`, or a message string for anything else. A container that no longer exists produces a message string, not `"file_not_found"`. `upload_files` reports failures in `FileUploadResponse.error`. Neither raises for a single bad file.
+
+`upload_files` never replaces an existing directory. If the target path is a directory, that file gets a per-file error and the directory is left untouched.
+
+### Checking a container
+
+Every `execute()` call needs `timeout` inside the container. `ContainerProvisioner` does not check for it, because its own keep-alive command does not use it. If your image might lack `timeout`, or you hand `ContainerSandbox` a container you did not provision, check once up front:
+
+```python
+sandbox = ContainerSandbox(container)
+sandbox.verify_timeout()  # raises MissingTimeoutError if `timeout` is unusable
+sandbox.verify_python()  # raises MissingPythonError if `python3` is unusable
+```
+
+Without the `timeout` check, every `execute()` call fails with exit code `127` and an "executable file not found in $PATH" message from the container runtime in `output`. `execute()` does not raise, so an agent would see this on every command and may misread it as a problem with its own code. `verify_timeout()` turns it into a single `MissingTimeoutError` at setup time.
+
+`verify_python()` matters for the file helpers `read`, `write`, `edit`, `ls` and `glob`, which run Python inside the container. Without it, `ls` returns an empty list instead of an error, so an agent can conclude that a directory is empty. `execute()` and file transfer do not need Python, so `verify_python()` is a separate, optional call.
+
+`ManagedContainerSandbox` runs both checks on entry by default, `timeout` first. Turn either off with `verify_timeout=False` or `verify_python=False`.
+
+## Errors
+
+Everything the library raises on purpose inherits from `SandboxError`:
+
+```
+SandboxError
+├── DockerImageNotFound           image missing and could not be pulled (including auth or rate-limit failures); has an .image attribute
+├── MissingTimeoutError           the container cannot run commands under `timeout`
+├── MissingPythonError            the container has no usable `python3`
+└── ContainerReuseError           get_or_create found the name but will not hand the container out; has .name and .container attributes
+    ├── SpecMismatchError         it is not the container this spec describes; has a .reason attribute
+    └── ContainerNotRunningError  it is the right container, but it is not running; has a .status attribute
+```
+
+```python
+from agent_container_sandbox import DockerImageNotFound
+
+try:
+    container = provisioner.provision(spec)
+except DockerImageNotFound as e:
+    print(f"Could not get image {e.image}: {e}")
+```
+
+Other failures, such as a container that cannot start or a daemon that is unreachable, surface as the underlying `docker-py` exceptions. Entering a `ManagedContainerSandbox` twice raises a plain `RuntimeError`, and a non-positive `command_timeout` or `max_output_size` raises a plain `ValueError`, because both are programming errors.
+
+## Known limitations
+
+- **`get_or_create` checks the spec, not the live container.** It verifies that the container carries the library's marker label and the fingerprint of the spec, and that it is running. It cannot see settings changed on a live container (for example with `docker update`), a mutable image tag such as `latest` that now points to different content, or a later library version translating the same spec into different Docker arguments.
+- **`get_or_create` is not safe against races.** Two callers creating the same name at the same moment can conflict.
+- **`ls` and `grep` do not report clipped output.** When a listing or a search exceeds `max_output_size`, the deepagents helpers return the part that fit without any signal that results are missing, so the answer looks complete (observed with deepagents 0.7.19 and 0.7.32, reported as [deepagents#7480](https://github.com/langchain-ai/deepagents/issues/7480)). `glob` and `execute` do report truncation. Raise `max_output_size` for large directories or trees.
+- **Network access is all or nothing.** The library can switch networking on or off but cannot restrict it to specific hosts. If the agent needs some access but not all of it, attach the container to a dedicated Docker network or use firewall rules.
+- **Mounted directories are exposed.** A read-write volume gives the agent full access to its contents. Mount a dedicated directory, never a home directory, and never the Docker socket. Likewise, if your own code runs in a container, mounting the host socket gives that container control of the host's Docker daemon.
+- **Commands run as the image's default user,** which is usually root inside the container. Capabilities are dropped, but the container is not rootless.
+- **Disk usage is not limited.** The container's writable layer can grow until the host's disk is full.
+- **Docker is not a hard security boundary.** Containers share the host kernel, so a kernel vulnerability bypasses all of the settings above. For untrusted code, add a stronger runtime such as gVisor or Kata, or run Docker in rootless mode.
+
+## License
+
+MIT, see LICENSE

agent_container_sandbox-0.1.1.dist-info/RECORD

@@ -0,0 +1,10 @@
+agent_container_sandbox/__init__.py,sha256=0hw7kL7HiCvM7Z-zgxvA4JjuASWt393uuh_g5nopGjg,960
+agent_container_sandbox/errors.py,sha256=XIUCvnQs09r0ec77pCz52zfAetGrio8RF_MQW65mqoo,4994
+agent_container_sandbox/managed.py,sha256=WLrn4mc0rXCj1HLRWHlSE7HHbfy2w8vOEqYvZ6tpxOA,6388
+agent_container_sandbox/provisioning.py,sha256=8JkMNUWRjv5__vigRab3ZVwJrB7AJ4lDSxs49wCn9Rc,11729
+agent_container_sandbox/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+agent_container_sandbox/sandbox.py,sha256=u0NqlNovpqMpX21R6xp1EO3OdMU-p2IrcL44G40c3Qc,12964
+agent_container_sandbox-0.1.1.dist-info/licenses/LICENSE,sha256=HvdJk-UfUM_ilrrHXS86YzY5Q44wsSKAwxEve2eLyJw,1063
+agent_container_sandbox-0.1.1.dist-info/WHEEL,sha256=xDCZ-UyfvkGuEHPeI7BcJzYKIZzdqN8A8o1M5Om8IyA,79
+agent_container_sandbox-0.1.1.dist-info/METADATA,sha256=k8ptfNsifiJsLRZVQF-PwILZZEcexHtd8uzmIYE8_pM,23053
+agent_container_sandbox-0.1.1.dist-info/RECORD,,

agent_container_sandbox-0.1.1.dist-info/WHEEL

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

agent_container_sandbox-0.1.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Konovor
+
+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.