feat(workspaces): mount volumes and name the container of a DockerWorkspace

A tool run from a project directory - pydantic-deep's CLI in Docker mode -
wants its project mounted in the container and the same container every
time it starts, and has no message history to carry a ref in. Both were
reachable only by building DockerWorkspaceBackend with a sandbox factory.

volumes mounts host directories. container_name names one container for
every run: created on first use, attached after. A ref naming it must
still find it there, and no ref reaches another container through it.

Also ships py.typed, without which type checkers in projects installing
this package read every name as Any.

Verified: 1320 tests at 100% coverage; ruff, pyright, mypy. On a real
daemon a mounted host file reads inside, a file written inside appears on
the host, and a second backend reaches the same container by name.

Author: DEENUU1

CHANGELOG.md

@@ -7,6 +7,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- **`DockerWorkspace(volumes=..., container_name=...)`.** `volumes` mounts host
+  directories into the container, so an agent can work on a project in place.
+  `container_name` gives every run the same container, named by whoever
+  configures the workspace: created on first use, attached after, by this
+  process or the next. A ref naming it must still find it there, and no ref
+  reaches another container through it. Both were reachable only by building
+  `DockerWorkspaceBackend` with a sandbox factory of your own.
+
+### Fixed
+
+- **The package ships `py.typed`.** Its annotations were invisible to type
+  checkers in projects that install it, which read every name as `Any`.
+
 ## [0.2.30] - 2026-10-05
 
 **⚠️ Breaking: the library is now built on Pydantic AI workspaces.** Pydantic AI

docs/concepts/docker.md

@@ -118,15 +118,33 @@ with the conversation, and every turn reaches the same environment; a different
 gets a container of its own. Call `destroy(ref)` when a conversation is deleted — nothing
 removes a container for you.
 
+### One container, named by you
+
+A tool that runs from a project directory - a CLI, an editor plugin - wants the same
+container every time it starts, with the project mounted inside, and has no history to
+carry a ref in. Name the container and mount the project:
+
+```python
+workspace = DockerWorkspace(
+    container_name="my-project-sandbox",
+    volumes={"/home/me/my-project": "/workspace"},
+)
+```
+
+The first run creates `my-project-sandbox`; every later one, in this process or the next,
+attaches to it, installed packages included. A ref naming it still has to find it there -
+one that outlived the container is `WorkspaceUnavailableError` - and a ref naming any other
+container is left to another capability. `destroy(ref)` removes it like any other.
+
 What `DockerWorkspace` does not do is manage a fleet: idle reaping, a ceiling on running
 containers, per-tenant capacity, hibernation. That is what [`sandboxd`](remote.md) is for,
 built on the same `DockerSandbox` and the same command path.
 
 ## Options
 
-`image`, `runtime`, `work_dir`, `network_mode`, `mem_limit`, `cpus` and `oci_runtime` are
-fields of `DockerWorkspace`. For a container option it does not expose — volumes, a tmpfs,
-a pids limit — build the backend yourself with a factory that returns the `DockerSandbox`
+`image`, `runtime`, `work_dir`, `network_mode`, `mem_limit`, `cpus`, `oci_runtime`, `env`,
+`volumes` and `container_name` are fields of `DockerWorkspace`. For a container option it
+does not expose — a tmpfs, a pids limit — build the backend yourself with a factory that returns the `DockerSandbox`
 you want:
 
 ```python

src/pydantic_ai_backends/py.typed

@@ -79,6 +79,10 @@ class DockerWorkspaceBackend(ContainerWorkspaceBackend):
             the image, runtime and limits, and must not start the container.
         ref: The workspace to attach to; `None` creates one on first use.
         env: Variables every command gets, under any a call passes.
+        container_name: A container chosen by whoever configures the workspace
+            rather than by this class: created under that name on first use
+            when it does not exist, attached when it does. A ref naming it must
+            still find it there, and no ref reaches any other container.
     """
 
     def __init__(
@@ -87,11 +91,16 @@ def __init__(
         sandbox_factory: SandboxFactory,
         ref: WorkspaceRef | None = None,
         env: Mapping[str, str] | None = None,
+        container_name: str | None = None,
     ) -> None:
         async def open_container(name: str | None) -> tuple[str, RunnerSandbox]:
-            if name is None:
+            if container_name is not None and name is None:
+                # First use of a configured container: whatever state it is in,
+                # it is the one asked for, and starting the sandbox creates it.
+                name = container_name
+            elif name is None:
                 name = f"{CONTAINER_PREFIX}{uuid.uuid4().hex[:16]}"
-            elif not _created_here(name):
+            elif name != container_name and not _created_here(name):
                 raise SandboxUnavailableError(
                     f"container {name!r} was not created by a DockerWorkspace"
                 )
@@ -161,6 +170,22 @@ class DockerWorkspace(AbstractCapability[object]):
     env: Mapping[str, str] | None = field(default=None, repr=False)
     """Variables every command gets. Nothing is read from the host's environment."""
 
+    volumes: Mapping[str, str] | None = None
+    """Host directories mounted into the container, as `{"/host/path": "/container/path"}`.
+
+    Mounting a project at `work_dir` lets the agent work on its files in place;
+    the container then reaches exactly those host files.
+    """
+
+    container_name: str | None = None
+    """One container for every run, named by you: created on first use, attached after.
+
+    Without it each run without a ref gets a new container and only the ref
+    leads back to it. With it a later process finds the same container -
+    installed packages included - by name. A ref naming another container is
+    left to another capability.
+    """
+
     def __post_init__(self) -> None:
         if self.defer_loading:
             raise UserError(
@@ -178,11 +203,17 @@ def _sandbox(self, name: str) -> DockerSandbox:
             mem_limit=self.mem_limit,
             cpus=self.cpus,
             oci_runtime=self.oci_runtime,
+            volumes=dict(self.volumes) if self.volumes else None,
         )
 
     def backend(self, ref: WorkspaceRef | None = None) -> DockerWorkspaceBackend:
         """A backend for `ref`, or for a new container; no I/O until its first operation."""
-        return DockerWorkspaceBackend(sandbox_factory=self._sandbox, ref=ref, env=self.env)
+        return DockerWorkspaceBackend(
+            sandbox_factory=self._sandbox,
+            ref=ref,
+            env=self.env,
+            container_name=self.container_name,
+        )
 
     def get_workspace(
         self, ctx: RunContext[object], *, ref: WorkspaceRef | None
@@ -191,6 +222,8 @@ def get_workspace(
         del ctx
         if ref is not None and ref.provider != DOCKER_PROVIDER:
             return None
+        if ref is not None and self.container_name is not None and ref.id != self.container_name:
+            return None
         return self.backend(ref)
 
     async def destroy(self, ref: WorkspaceRef) -> None:
@@ -202,6 +235,6 @@ async def destroy(self, ref: WorkspaceRef) -> None:
         """
         if ref.provider != DOCKER_PROVIDER:
             raise ValueError(f"expected a {DOCKER_PROVIDER!r} workspace ref, got {ref.provider!r}")
-        if not _created_here(ref.id):
+        if ref.id != self.container_name and not _created_here(ref.id):
             raise ValueError(f"container {ref.id!r} was not created by a DockerWorkspace")
         await anyio.to_thread.run_sync(_remove_container, ref.id)

src/pydantic_ai_backends/workspaces/_docker.py

@@ -491,3 +491,63 @@ def test_a_valid_timeout_passes(self) -> None:
     def test_a_finished_outcome_needs_an_exit_code(self) -> None:
         with pytest.raises(ValueError, match="exit code"):
             command_result(CommandOutcome(stdout="", stderr=""), timeout=None, limit=1)
+
+
+class TestAConfiguredContainer:
+    """A container named by whoever configures the workspace, for every run."""
+
+    async def test_is_created_under_its_name_on_first_use(self, client: _Client) -> None:
+        factory = _Factory()
+        backend = DockerWorkspaceBackend(sandbox_factory=factory, container_name="project-box")
+        await backend.run(["true"])
+        assert factory.built[0].name == "project-box"
+        assert backend.ref == WorkspaceRef(provider="docker", id="project-box")
+
+    async def test_a_ref_to_it_attaches_while_it_is_there(self, client: _Client) -> None:
+        client.containers.known["project-box"] = _Container(client.api, status="exited")
+        factory = _Factory()
+        backend = DockerWorkspaceBackend(
+            sandbox_factory=factory,
+            ref=WorkspaceRef(provider="docker", id="project-box"),
+            container_name="project-box",
+        )
+        await backend.run(["true"])
+        assert factory.built[0].name == "project-box"
+
+    async def test_a_ref_to_it_once_it_is_gone_is_unavailable(self, client: _Client) -> None:
+        backend = DockerWorkspaceBackend(
+            sandbox_factory=_Factory(),
+            ref=WorkspaceRef(provider="docker", id="project-box"),
+            container_name="project-box",
+        )
+        with pytest.raises(WorkspaceUnavailableError, match="no longer exists"):
+            await backend.working_dir()
+
+    async def test_no_ref_reaches_another_container(self, client: _Client) -> None:
+        client.containers.known["postgres"] = _Container(client.api)
+        backend = DockerWorkspaceBackend(
+            sandbox_factory=_Factory(),
+            ref=WorkspaceRef(provider="docker", id="postgres"),
+            container_name="project-box",
+        )
+        with pytest.raises(WorkspaceUnavailableError, match="not created by a DockerWorkspace"):
+            await backend.working_dir()
+
+    def test_the_capability_leaves_other_refs_alone(self) -> None:
+        capability = DockerWorkspace(container_name="project-box")
+        ctx: Any = None
+        assert capability.get_workspace(ctx, ref=WorkspaceRef(provider="docker", id="x")) is None
+        own = capability.get_workspace(ctx, ref=WorkspaceRef(provider="docker", id="project-box"))
+        assert isinstance(own, DockerWorkspaceBackend)
+
+    async def test_destroy_removes_it(self, client: _Client) -> None:
+        box = _Container(client.api)
+        client.containers.known["project-box"] = box
+        await DockerWorkspace(container_name="project-box").destroy(
+            WorkspaceRef(provider="docker", id="project-box")
+        )
+        assert box.removed
+
+    def test_volumes_reach_the_sandbox(self) -> None:
+        sandbox = DockerWorkspace(volumes={"/host/project": "/workspace"})._sandbox("name")
+        assert sandbox._volumes == {"/host/project": "/workspace"}