Skip to content

sandboxd API

The sandbox service and the read-only archive of what its sessions left behind. See sandboxd for the concepts and the security model; the client is SandboxdWorkspace.

WorkspaceArchive

Read-only view of the files sessions left behind, with no sandbox running. Needs the remote extra.

pydantic_ai_backends.remote.archive.WorkspaceArchive

Read-only view of the files sessions left behind.

Reads the service's host volume directly, so a session reaped long ago is still browsable and listing a conversation's files costs no container start.

This raises rather than degrading. Nothing here is in an agent's tool path — the caller is an application answering a user who asked to see some files, and it needs to tell "there are none" apart from "the service is misconfigured".

Requires the service to be running with SandboxdConfig.workspace_root set, and the service token: a reaped session has no token of its own left, and the intended caller is a backend applying its own authorization first.

Parameters:

Name Type Description Default
service_url str

Base URL of the service. Ignored when client is supplied.

'http://localhost:8080'
token str

Service token.

''
timeout float

Request timeout in seconds.

DEFAULT_TIMEOUT_SECONDS
client Client | None

Pre-built httpx.Client, to share a connection pool or drive an in-process ASGI app.

None
Example
Python
from pydantic_ai_backends.remote import WorkspaceArchive

archive = WorkspaceArchive("http://sandboxd:8080", token="...")
for entry in archive.ls(session_id):
    print(entry["path"], entry["size"])
print(archive.read(session_id, "report.md"))
Path("chart.png").write_bytes(archive.read_bytes(session_id, "chart.png"))
Source code in src/pydantic_ai_backends/remote/archive.py
Python
class WorkspaceArchive:
    """Read-only view of the files sessions left behind.

    Reads the service's host volume directly, so a session reaped long ago is
    still browsable and listing a conversation's files costs no container start.

    This **raises** rather than degrading. Nothing here is in an agent's tool
    path — the caller is an application answering a user who asked to see some
    files, and it needs to tell "there are none" apart from "the service is
    misconfigured".

    Requires the service to be running with `SandboxdConfig.workspace_root` set,
    and the service token: a reaped session has no token of its own left, and the
    intended caller is a backend applying its own authorization first.

    Args:
        service_url: Base URL of the service. Ignored when `client` is supplied.
        token: Service token.
        timeout: Request timeout in seconds.
        client: Pre-built `httpx.Client`, to share a connection pool or drive an
            in-process ASGI app.

    Example:
        ```python
        from pydantic_ai_backends.remote import WorkspaceArchive

        archive = WorkspaceArchive("http://sandboxd:8080", token="...")
        for entry in archive.ls(session_id):
            print(entry["path"], entry["size"])
        print(archive.read(session_id, "report.md"))
        Path("chart.png").write_bytes(archive.read_bytes(session_id, "chart.png"))
        ```
    """

    def __init__(
        self,
        service_url: str = "http://localhost:8080",
        *,
        token: str = "",
        timeout: float = DEFAULT_TIMEOUT_SECONDS,
        client: httpx.Client | None = None,
    ) -> None:
        self._token = token
        self._timeout = timeout
        if client is not None:
            self._http = client
            self._owns_client = False
        else:
            httpx_module = load("httpx", purpose="WorkspaceArchive")
            self._http = httpx_module.Client(
                base_url=service_url.rstrip("/"),
                timeout=httpx_module.Timeout(timeout),
            )
            self._owns_client = True

    def ls(self, session_id: str, path: str = ".") -> list[FileInfo]:
        """List one directory of a stored workspace.

        Args:
            session_id: Session whose files are wanted.
            path: Directory to list. An absolute in-container path works, so a
                path taken from a live session's listing can be handed straight
                back.

        Raises:
            WorkspaceArchiveError: If the workspace or directory is absent, the
                path escapes the workspace, or the service cannot be reached.
        """
        payload = wire.LsRequest(path=path).model_dump(mode="json")
        response = self._post(f"/workspaces/{session_id}/ls", payload)
        entries = [wire.FileEntry.model_validate(row) for row in response.json()]
        return [
            FileInfo(
                name=e.name, path=e.path, is_dir=e.is_dir, size=e.size, modified_at=e.modified_at
            )
            for e in entries
        ]

    def tree(
        self,
        session_id: str,
        path: str = ".",
        *,
        max_depth: int = 6,
        max_entries: int = 2000,
    ) -> WorkspaceTree:
        """List a directory of a stored workspace and the directories under it.

        One request where walking with :meth:`ls` takes one per directory. Needs
        a service from 0.2.35; an older one answers 404.

        Args:
            session_id: Session whose files are wanted.
            path: Directory to start from, as for :meth:`ls`.
            max_depth: Levels to list; 1 is `path` alone, as :meth:`ls` lists it.
            max_entries: Most entries to return.

        Raises:
            WorkspaceArchiveError: If the workspace or directory is absent, the
                path escapes the workspace, or the service cannot be reached.
        """
        payload = wire.TreeRequest(
            path=path, max_depth=max_depth, max_entries=max_entries
        ).model_dump(mode="json")
        response = self._post(f"/workspaces/{session_id}/tree", payload)
        return _tree(wire.TreeResponse.model_validate(response.json()))

    def trees(
        self,
        session_ids: Sequence[str],
        path: str = ".",
        *,
        max_depth: int = 6,
        max_entries: int = 2000,
    ) -> dict[str, WorkspaceTree | WorkspaceArchiveError]:
        """:meth:`tree` for several stored workspaces, in one request.

        For a page that draws many workspaces at once: one round trip, where a
        `tree` per workspace was a request each. Each workspace is answered on
        its own - a tree, or the `WorkspaceArchiveError` that `tree` would have
        raised for it alone. Needs a service from 0.2.37; an older one answers
        404, raised here.

        Args:
            session_ids: Sessions whose files are wanted, at most 100.
            path: Directory to start from in each, as for :meth:`ls`.
            max_depth: Levels to list in each.
            max_entries: Most entries to return for each.

        Raises:
            WorkspaceArchiveError: If the request as a whole is refused or the
                service cannot be reached.
        """
        payload = wire.TreesRequest(
            sessions=list(session_ids), path=path, max_depth=max_depth, max_entries=max_entries
        ).model_dump(mode="json")
        response = self._post("/workspaces/trees", payload)
        answer = wire.TreesResponse.model_validate(response.json())
        return {
            result.session_id: (
                _tree(result.tree)
                if result.tree is not None
                else WorkspaceArchiveError(result.error or "", status_code=result.status_code)
            )
            for result in answer.results
        }

    def read(self, session_id: str, path: str, offset: int = 0, limit: int = 2000) -> str:
        """Read a slice of a stored workspace file.

        Decoded exactly as a live session would decode it, so the archive and the
        sandbox never disagree about what a file says.

        Raises:
            WorkspaceArchiveError: If the file is absent, too large, not readable
                as text, outside the workspace, or the service is unreachable.
        """
        payload = wire.ReadRequest(path=path, offset=offset, limit=limit).model_dump(mode="json")
        response = self._post(f"/workspaces/{session_id}/read", payload)
        return wire.ReadResponse.model_validate(response.json()).content

    def read_bytes(self, session_id: str, path: str) -> bytes:
        """Read a whole stored workspace file as bytes.

        The sibling of :meth:`read`, and the one to use for anything an agent
        produced that is not text - a chart, a rendered PDF, an image it fetched.
        Those are the commonest contents of a real workspace, and `read` decodes
        them: the result re-encodes to a corrupt file that nonetheless downloads
        successfully, which is worse than an error, so a caller serving downloads
        had to refuse them instead.

        Whole rather than sliced, because a byte range means nothing for the
        formats this exists for. `ls` carries `size`, so a caller that wants to
        bound a read can look first.

        Raises:
            WorkspaceArchiveError: If the file is absent, over the service's read
                ceiling, outside the workspace, or the service is unreachable.
        """
        payload = wire.ReadBytesRequest(path=path).model_dump(mode="json")
        response = self._post(f"/workspaces/{session_id}/read_bytes", payload)
        encoded = wire.ReadBytesResponse.model_validate(response.json()).content_b64
        return base64.b64decode(encoded)

    def close(self) -> None:
        """Close the HTTP client, when this object built it."""
        if self._owns_client:
            with contextlib.suppress(Exception):
                self._http.close()

    def _post(self, url: str, payload: dict[str, Any]) -> Any:
        """POST with the service token, raising on anything but success."""
        try:
            response = self._http.post(
                url,
                json=payload,
                headers={wire.TOKEN_HEADER: self._token},
                timeout=self._timeout,
            )
        except Exception as exc:
            raise WorkspaceArchiveError(f"Could not reach the sandbox service: {exc}") from exc

        if response.status_code >= 400:
            raise WorkspaceArchiveError(response.text, status_code=response.status_code)
        return response

__init__(service_url='http://localhost:8080', *, token='', timeout=DEFAULT_TIMEOUT_SECONDS, client=None)

Source code in src/pydantic_ai_backends/remote/archive.py
Python
def __init__(
    self,
    service_url: str = "http://localhost:8080",
    *,
    token: str = "",
    timeout: float = DEFAULT_TIMEOUT_SECONDS,
    client: httpx.Client | None = None,
) -> None:
    self._token = token
    self._timeout = timeout
    if client is not None:
        self._http = client
        self._owns_client = False
    else:
        httpx_module = load("httpx", purpose="WorkspaceArchive")
        self._http = httpx_module.Client(
            base_url=service_url.rstrip("/"),
            timeout=httpx_module.Timeout(timeout),
        )
        self._owns_client = True

ls(session_id, path='.')

List one directory of a stored workspace.

Parameters:

Name Type Description Default
session_id str

Session whose files are wanted.

required
path str

Directory to list. An absolute in-container path works, so a path taken from a live session's listing can be handed straight back.

'.'

Raises:

Type Description
WorkspaceArchiveError

If the workspace or directory is absent, the path escapes the workspace, or the service cannot be reached.

Source code in src/pydantic_ai_backends/remote/archive.py
Python
def ls(self, session_id: str, path: str = ".") -> list[FileInfo]:
    """List one directory of a stored workspace.

    Args:
        session_id: Session whose files are wanted.
        path: Directory to list. An absolute in-container path works, so a
            path taken from a live session's listing can be handed straight
            back.

    Raises:
        WorkspaceArchiveError: If the workspace or directory is absent, the
            path escapes the workspace, or the service cannot be reached.
    """
    payload = wire.LsRequest(path=path).model_dump(mode="json")
    response = self._post(f"/workspaces/{session_id}/ls", payload)
    entries = [wire.FileEntry.model_validate(row) for row in response.json()]
    return [
        FileInfo(
            name=e.name, path=e.path, is_dir=e.is_dir, size=e.size, modified_at=e.modified_at
        )
        for e in entries
    ]

tree(session_id, path='.', *, max_depth=6, max_entries=2000)

List a directory of a stored workspace and the directories under it.

One request where walking with :meth:ls takes one per directory. Needs a service from 0.2.35; an older one answers 404.

Parameters:

Name Type Description Default
session_id str

Session whose files are wanted.

required
path str

Directory to start from, as for :meth:ls.

'.'
max_depth int

Levels to list; 1 is path alone, as :meth:ls lists it.

6
max_entries int

Most entries to return.

2000

Raises:

Type Description
WorkspaceArchiveError

If the workspace or directory is absent, the path escapes the workspace, or the service cannot be reached.

Source code in src/pydantic_ai_backends/remote/archive.py
Python
def tree(
    self,
    session_id: str,
    path: str = ".",
    *,
    max_depth: int = 6,
    max_entries: int = 2000,
) -> WorkspaceTree:
    """List a directory of a stored workspace and the directories under it.

    One request where walking with :meth:`ls` takes one per directory. Needs
    a service from 0.2.35; an older one answers 404.

    Args:
        session_id: Session whose files are wanted.
        path: Directory to start from, as for :meth:`ls`.
        max_depth: Levels to list; 1 is `path` alone, as :meth:`ls` lists it.
        max_entries: Most entries to return.

    Raises:
        WorkspaceArchiveError: If the workspace or directory is absent, the
            path escapes the workspace, or the service cannot be reached.
    """
    payload = wire.TreeRequest(
        path=path, max_depth=max_depth, max_entries=max_entries
    ).model_dump(mode="json")
    response = self._post(f"/workspaces/{session_id}/tree", payload)
    return _tree(wire.TreeResponse.model_validate(response.json()))

read(session_id, path, offset=0, limit=2000)

Read a slice of a stored workspace file.

Decoded exactly as a live session would decode it, so the archive and the sandbox never disagree about what a file says.

Raises:

Type Description
WorkspaceArchiveError

If the file is absent, too large, not readable as text, outside the workspace, or the service is unreachable.

Source code in src/pydantic_ai_backends/remote/archive.py
Python
def read(self, session_id: str, path: str, offset: int = 0, limit: int = 2000) -> str:
    """Read a slice of a stored workspace file.

    Decoded exactly as a live session would decode it, so the archive and the
    sandbox never disagree about what a file says.

    Raises:
        WorkspaceArchiveError: If the file is absent, too large, not readable
            as text, outside the workspace, or the service is unreachable.
    """
    payload = wire.ReadRequest(path=path, offset=offset, limit=limit).model_dump(mode="json")
    response = self._post(f"/workspaces/{session_id}/read", payload)
    return wire.ReadResponse.model_validate(response.json()).content

read_bytes(session_id, path)

Read a whole stored workspace file as bytes.

The sibling of :meth:read, and the one to use for anything an agent produced that is not text - a chart, a rendered PDF, an image it fetched. Those are the commonest contents of a real workspace, and read decodes them: the result re-encodes to a corrupt file that nonetheless downloads successfully, which is worse than an error, so a caller serving downloads had to refuse them instead.

Whole rather than sliced, because a byte range means nothing for the formats this exists for. ls carries size, so a caller that wants to bound a read can look first.

Raises:

Type Description
WorkspaceArchiveError

If the file is absent, over the service's read ceiling, outside the workspace, or the service is unreachable.

Source code in src/pydantic_ai_backends/remote/archive.py
Python
def read_bytes(self, session_id: str, path: str) -> bytes:
    """Read a whole stored workspace file as bytes.

    The sibling of :meth:`read`, and the one to use for anything an agent
    produced that is not text - a chart, a rendered PDF, an image it fetched.
    Those are the commonest contents of a real workspace, and `read` decodes
    them: the result re-encodes to a corrupt file that nonetheless downloads
    successfully, which is worse than an error, so a caller serving downloads
    had to refuse them instead.

    Whole rather than sliced, because a byte range means nothing for the
    formats this exists for. `ls` carries `size`, so a caller that wants to
    bound a read can look first.

    Raises:
        WorkspaceArchiveError: If the file is absent, over the service's read
            ceiling, outside the workspace, or the service is unreachable.
    """
    payload = wire.ReadBytesRequest(path=path).model_dump(mode="json")
    response = self._post(f"/workspaces/{session_id}/read_bytes", payload)
    encoded = wire.ReadBytesResponse.model_validate(response.json()).content_b64
    return base64.b64decode(encoded)

close()

Close the HTTP client, when this object built it.

Source code in src/pydantic_ai_backends/remote/archive.py
Python
def close(self) -> None:
    """Close the HTTP client, when this object built it."""
    if self._owns_client:
        with contextlib.suppress(Exception):
            self._http.close()

pydantic_ai_backends.remote.archive.WorkspaceTree dataclass

A directory and what is under it, from :meth:WorkspaceArchive.tree.

Source code in src/pydantic_ai_backends/remote/archive.py
Python
@dataclass(frozen=True)
class WorkspaceTree:
    """A directory and what is under it, from :meth:`WorkspaceArchive.tree`."""

    entries: list[FileInfo]
    """Each directory's entries before its children's."""

    truncated: bool
    """Whether a bound or an unreadable directory left something out. A
    listing shorter than the workspace that did not say so reads as complete."""

entries instance-attribute

Each directory's entries before its children's.

truncated instance-attribute

Whether a bound or an unreadable directory left something out. A listing shorter than the workspace that did not say so reads as complete.

pydantic_ai_backends.remote.archive.WorkspaceArchiveError

Bases: Exception

Raised when a stored workspace cannot be listed or read.

Attributes:

Name Type Description
status_code

What the service answered, or None when it could not be reached at all. An application proxying file views to its own users maps this onto its own response.

Source code in src/pydantic_ai_backends/remote/archive.py
Python
class WorkspaceArchiveError(Exception):
    """Raised when a stored workspace cannot be listed or read.

    Attributes:
        status_code: What the service answered, or `None` when it could not be
            reached at all. An application proxying file views to its own users
            maps this onto its own response.
    """

    def __init__(self, message: str, status_code: int | None = None) -> None:
        self.status_code = status_code
        super().__init__(message)

SandboxdConfig

Everything the service decides on a client's behalf. Needs the server extra.

pydantic_ai_backends.remote.server.SandboxdConfig dataclass

Everything the service decides on a client's behalf.

Attributes:

Name Type Description
token str

Service token. Required to open, list or inspect any session.

runtimes Mapping[str, str | SandboxRuntime]

Allowlist mapping a client-visible alias to what may run under it — a bare image string, or a :class:SandboxRuntime carrying its own ceilings and, if it needs them, packages to build in. A request naming anything else is rejected; this is what stops a client from running an image of its choosing.

default_runtime str

Alias used when a request names none. Empty — the default — takes the first entry in runtimes, so the shipped allowlist defaults to coding while an operator who supplies their own gets whichever they listed first. Naming a specific alias here still wins; what it no longer does is force every custom allowlist to contain a particular key.

max_sessions int | None

Ceiling on resident sandboxes across the service, or None for no ceiling. Together with the largest per-runtime memory ceiling this is what bounds the worst case an operator has to size the host for, so None is for hosts where something else does the bounding. It does not bound how many sessions may exist — see max_open_sessions.

max_open_sessions int | None

Ceiling on sessions that exist, resident or hibernated, or None for no ceiling. A hibernated session costs disk and a few kilobytes of bookkeeping rather than memory, so this number is properly much larger than max_sessions — that gap is the difference between the sessions a host can carry and the ones it can run at once. Only meaningful with evict_idle_after, which is what demotes a session to hibernated in the first place.

evict_idle_after int | None

Seconds of inactivity after which a session at the ceiling may be hibernated to make room for a new one, instead of the new one being refused with 429. This is what turns max_sessions from a hard cap on how many sessions may exist into a working-set size: the hibernated session keeps its token, its event log and its files, and its next request wakes it where it left off. None refuses instead of evicting. Requires workspace_root — hibernating a session whose files live only in its container would discard them silently, which is not a trade a config should make quietly.

max_sessions_per_tenant int | None

Ceiling on simultaneous sessions carrying one tenant label. Without it, one tenant of the calling application can occupy the whole pool and every other tenant gets 429.

mem_limit str | None

Default memory ceiling per sandbox, in Docker syntax. A runtime naming its own overrides this, upwards or downwards.

memswap_limit str | None

Default ceiling on memory and swap combined. None pins it to mem_limit, so a sandbox at its ceiling is killed rather than allowed to swap — which is right when swap is a disk, because one swapping sandbox slows every other one on the host.

Raise it only where swap is zram. There the pages stay in RAM compressed at roughly 3:1, so a sandbox briefly over its ceiling costs CPU instead of the whole host's responsiveness, and on a small box that trade is what turns an OOM kill into a slow command.

cpus float | None

Default hard CPU ceiling per sandbox, in cores. None leaves sandboxes free to use whatever is idle, bounded only by cpu_shares.

cpu_shares int | None

Default relative CPU weight, applied only under contention. Preferable to a hard cpus on a small host, where capping each sandbox to one core leaves the others unused while a single agent waits.

tmpfs_size str | None

Size of an in-memory /tmp given to every sandbox, in Docker syntax. Scratch writes then never reach the container's write layer, which is both faster and the difference between a busy sandbox growing on disk and not. None leaves /tmp on the overlay.

Sized against mem_limit rather than on top of it, because tmpfs pages are charged to the container's own memory cgroup — so this is memory taken away from the workload, and worth keeping small when many sessions are open at once.

pids_limit int | None

Default process ceiling per sandbox.

network_mode str | None

Default Docker network mode. "none" because a service handing sandboxes to untrusted code should not give them the network unless that is a deliberate choice, per runtime or service-wide.

oci_runtime str | None

Default low-level runtime for every sandbox, overridable per runtime. None takes the daemon's default — which is the right default for us to ship, because naming a runtime the host has not registered turns every session into a 502. Set it to "runsc" once gVisor is installed to put every sandbox behind a userspace syscall layer; crun belongs in the daemon's own config instead, since it is a faster runc rather than a different isolation model.

work_dir str

Working directory inside every sandbox. Applied to built runtimes as well, overriding whatever their RuntimeConfig says, so that one directory is where the workspace volume is mounted, what the archive endpoints read, and what a client's paths resolve against. Three places disagreeing about it is how files go missing.

workspace_root str | None

Host directory backing each sandbox's work directory, as {workspace_root}/{session_id}/workspace. Without it a sandbox's files live only in the container's write layer, so idle reaping destroys them — which a session spanning several runs will notice. Session ids are pattern-checked before they reach here, so one cannot traverse out of this root.

prewarm bool

Pull and build the whole allowlist in the background at startup. Without it the first session on a built runtime pays for the image build — a measured ten seconds and upwards — and pays it in the middle of somebody's request. Only applies to the default Docker builder, since nothing else knows how to warm a custom one.

persist_containers bool

Give each sandbox a stable container name, so a reaped session keeps its filesystem and the next attach restarts the same container. workspace_root alone preserves only the work directory — packages installed with pip or apt live in the container's write layer, and an agent that reinstalls them after every idle timeout is not working in "the same" machine. The cost is that stopped containers accumulate until a session is closed with purge, so this is off by default.

idle_timeout int

Seconds of inactivity before a session is reaped.

cleanup_interval int

Seconds between reaping passes.

workspace_ttl int | None

Seconds an unused workspace directory is kept before it is swept, timed from when its session was last opened. None — the default — keeps a session's files for ever, which is usually what an agent's user expects: the notes and scripts are the work. Set it only where a retention policy says otherwise. Only meaningful with workspace_root.

container_ttl int | None

Seconds a stopped persisted container is kept before it is removed, timed from when it stopped. This reclaims what a session installed inside its container — the build, the wheels, the node_modules — while leaving its workspace untouched, so the files survive and only the rebuildable part goes. None keeps them. Only meaningful with persist_containers.

sandbox_uid int | None

Run every built runtime's sandbox as this unprivileged user instead of root, and give each session's workspace to it. None — the default — keeps the current behaviour, where a sandbox runs as root.

Worth turning on. A container escape starts from whoever the container runs as, and every file an agent writes into its bind-mounted workspace is owned by that user on the host — as root, a sandboxd running unprivileged cannot clean up after its own sessions. The image is built around the uid: a real account, a home directory, and a virtualenv it owns first on PATH, without which an agent's pip install fails and uv — having no --user mode — fails with no way forward.

Two things it asks of the deployment. The service must be able to chown each session's workspace to this uid, which means either running with the privilege or running as that uid so the directories are created owned by it; a service that can do neither is told so when the session opens rather than handing an agent a workspace it cannot write to. And ready-made runtimes are left as root, since an image nobody built for this has no such user and no virtualenv, so an agent inside one could install nothing.

max_read_bytes int

Largest single file a client may read out of a sandbox.

execute_timeout int

Hard ceiling applied to every command, so one client cannot occupy a worker indefinitely.

max_workers int

Threads dedicated to blocking sandbox calls. Sandbox commands are long, so this pool is kept separate from asyncio's shared default one.

max_running_commands int

Commands that may run at once across every session. Each running command holds a thread for as long as it runs, reading its output, and the thread pool behind them defaulted to 40: the forty-first command - an ls, in somebody else's session - waited for one of them to finish.

native_files bool

Serve a session's file operations from its directory on the host instead of a command in its container, where the service keeps workspaces on disk. A read or a write is then a millisecond rather than one or more docker execs. Writes are native only when the sandbox runs as this service's own user or as root, or the files the service created would not be the sandbox's to change.

ui_enabled bool

Serve the bundled dashboard at /ui. Off by default: the page asks a human for the service token, and that token can start containers on the host, so it belongs on localhost or a private network and never on a public listener. The HTTP API is unaffected either way.

Source code in src/pydantic_ai_backends/remote/server.py
Python
@dataclass(slots=True)
class SandboxdConfig:
    """Everything the service decides on a client's behalf.

    Attributes:
        token: Service token. Required to open, list or inspect any session.
        runtimes: Allowlist mapping a client-visible alias to what may run
            under it — a bare image string, or a :class:`SandboxRuntime` carrying
            its own ceilings and, if it needs them, packages to build in. A
            request naming anything else is rejected; this is what stops a client
            from running an image of its choosing.
        default_runtime: Alias used when a request names none. Empty — the
            default — takes the first entry in `runtimes`, so the shipped
            allowlist defaults to `coding` while an operator who supplies their
            own gets whichever they listed first. Naming a specific alias here
            still wins; what it no longer does is force every custom allowlist
            to contain a particular key.
        max_sessions: Ceiling on *resident sandboxes* across the service, or
            `None` for no ceiling. Together with the largest per-runtime memory
            ceiling this is what bounds the worst case an operator has to size
            the host for, so `None` is for hosts where something else does the
            bounding. It does not bound how many sessions may exist — see
            `max_open_sessions`.
        max_open_sessions: Ceiling on sessions that *exist*, resident or
            hibernated, or `None` for no ceiling. A hibernated session costs
            disk and a few kilobytes of bookkeeping rather than memory, so this
            number is properly much larger than `max_sessions` — that gap is the
            difference between the sessions a host can carry and the ones it can
            run at once. Only meaningful with `evict_idle_after`, which is what
            demotes a session to hibernated in the first place.
        evict_idle_after: Seconds of inactivity after which a session at the
            ceiling may be hibernated to make room for a new one, instead of the
            new one being refused with `429`. This is what turns `max_sessions`
            from a hard cap on how many sessions may *exist* into a working-set
            size: the hibernated session keeps its token, its event log and its
            files, and its next request wakes it where it left off. `None`
            refuses instead of evicting. Requires `workspace_root` — hibernating
            a session whose files live only in its container would discard them
            silently, which is not a trade a config should make quietly.
        max_sessions_per_tenant: Ceiling on simultaneous sessions carrying one
            `tenant` label. Without it, one tenant of the calling application can
            occupy the whole pool and every other tenant gets `429`.
        mem_limit: Default memory ceiling per sandbox, in Docker syntax. A
            runtime naming its own overrides this, upwards or downwards.
        memswap_limit: Default ceiling on memory and swap combined. `None` pins
            it to `mem_limit`, so a sandbox at its ceiling is killed rather than
            allowed to swap — which is right when swap is a disk, because one
            swapping sandbox slows every other one on the host.

            Raise it only where swap is `zram`. There the pages stay in RAM
            compressed at roughly 3:1, so a sandbox briefly over its ceiling
            costs CPU instead of the whole host's responsiveness, and on a small
            box that trade is what turns an OOM kill into a slow command.
        cpus: Default hard CPU ceiling per sandbox, in cores. `None` leaves
            sandboxes free to use whatever is idle, bounded only by `cpu_shares`.
        cpu_shares: Default relative CPU weight, applied only under contention.
            Preferable to a hard `cpus` on a small host, where capping each
            sandbox to one core leaves the others unused while a single agent
            waits.
        tmpfs_size: Size of an in-memory `/tmp` given to every sandbox, in Docker
            syntax. Scratch writes then never reach the container's write layer,
            which is both faster and the difference between a busy sandbox
            growing on disk and not. `None` leaves `/tmp` on the overlay.

            Sized against `mem_limit` rather than on top of it, because tmpfs
            pages are charged to the container's own memory cgroup — so this is
            memory taken away from the workload, and worth keeping small when
            many sessions are open at once.
        pids_limit: Default process ceiling per sandbox.
        network_mode: Default Docker network mode. `"none"` because a service
            handing sandboxes to untrusted code should not give them the network
            unless that is a deliberate choice, per runtime or service-wide.
        oci_runtime: Default low-level runtime for every sandbox, overridable per
            runtime. `None` takes the daemon's default — which is the right
            default for us to ship, because naming a runtime the host has not
            registered turns every session into a `502`. Set it to `"runsc"` once
            gVisor is installed to put every sandbox behind a userspace syscall
            layer; `crun` belongs in the daemon's own config instead, since it is
            a faster `runc` rather than a different isolation model.
        work_dir: Working directory inside every sandbox. Applied to built
            runtimes as well, overriding whatever their `RuntimeConfig` says, so
            that one directory is where the workspace volume is mounted, what
            the archive endpoints read, and what a client's paths resolve
            against. Three places disagreeing about it is how files go missing.
        workspace_root: Host directory backing each sandbox's work directory, as
            `{workspace_root}/{session_id}/workspace`. Without it a sandbox's
            files live only in the container's write layer, so idle reaping
            destroys them — which a session spanning several runs will notice.
            Session ids are pattern-checked before they reach here, so one
            cannot traverse out of this root.
        prewarm: Pull and build the whole allowlist in the background at
            startup. Without it the first session on a built runtime pays for the
            image build — a measured ten seconds and upwards — and pays it in the
            middle of somebody's request. Only applies to the default Docker
            builder, since nothing else knows how to warm a custom one.
        persist_containers: Give each sandbox a stable container name, so a
            reaped session keeps its filesystem and the next attach restarts the
            same container. `workspace_root` alone preserves only the work
            directory — packages installed with `pip` or `apt` live in the
            container's write layer, and an agent that reinstalls them after
            every idle timeout is not working in "the same" machine. The cost is
            that stopped containers accumulate until a session is closed with
            `purge`, so this is off by default.
        idle_timeout: Seconds of inactivity before a session is reaped.
        cleanup_interval: Seconds between reaping passes.
        workspace_ttl: Seconds an unused workspace directory is kept before it is
            swept, timed from when its session was last opened. `None` — the
            default — keeps a session's **files** for ever, which is usually what
            an agent's user expects: the notes and scripts are the work. Set it
            only where a retention policy says otherwise. Only meaningful with
            `workspace_root`.
        container_ttl: Seconds a *stopped* persisted container is kept before it
            is removed, timed from when it stopped. This reclaims what a session
            installed inside its container — the build, the wheels, the
            `node_modules` — while leaving its workspace untouched, so the files
            survive and only the rebuildable part goes. `None` keeps them.
            Only meaningful with `persist_containers`.
        sandbox_uid: Run every built runtime's sandbox as this unprivileged
            user instead of root, and give each session's workspace to it.
            `None` — the default — keeps the current behaviour, where a sandbox
            runs as root.

            Worth turning on. A container escape starts from whoever the
            container runs as, and every file an agent writes into its
            bind-mounted workspace is owned by that user on the host — as root,
            a `sandboxd` running unprivileged cannot clean up after its own
            sessions. The image is built around the uid: a real account, a home
            directory, and a virtualenv it owns first on `PATH`, without which
            an agent's `pip install` fails and `uv` — having no `--user` mode —
            fails with no way forward.

            Two things it asks of the deployment. The service must be able to
            `chown` each session's workspace to this uid, which means either
            running with the privilege or running *as* that uid so the
            directories are created owned by it; a service that can do neither
            is told so when the session opens rather than handing an agent a
            workspace it cannot write to. And ready-made runtimes are left as
            root, since an image nobody built for this has no such user and no
            virtualenv, so an agent inside one could install nothing.
        max_read_bytes: Largest single file a client may read out of a sandbox.
        execute_timeout: Hard ceiling applied to every command, so one client
            cannot occupy a worker indefinitely.
        max_workers: Threads dedicated to blocking sandbox calls. Sandbox
            commands are long, so this pool is kept separate from asyncio's
            shared default one.
        max_running_commands: Commands that may run at once across every
            session. Each running command holds a thread for as long as it runs,
            reading its output, and the thread pool behind them defaulted to 40:
            the forty-first command - an `ls`, in somebody else's session - waited
            for one of them to finish.
        native_files: Serve a session's file operations from its directory on
            the host instead of a command in its container, where the service
            keeps workspaces on disk. A read or a write is then a millisecond
            rather than one or more `docker exec`s. Writes are native only when
            the sandbox runs as this service's own user or as root, or the files
            the service created would not be the sandbox's to change.
        ui_enabled: Serve the bundled dashboard at `/ui`. Off by default: the
            page asks a human for the service token, and that token can start
            containers on the host, so it belongs on localhost or a private
            network and never on a public listener. The HTTP API is unaffected
            either way.
    """

    token: str
    runtimes: Mapping[str, str | SandboxRuntime] = field(
        default_factory=lambda: dict(DEFAULT_RUNTIMES)
    )
    default_runtime: str = ""
    max_sessions: int | None = 20
    max_open_sessions: int | None = None
    max_sessions_per_tenant: int | None = None
    evict_idle_after: int | None = None
    mem_limit: str | None = "1g"
    memswap_limit: str | None = None
    cpus: float | None = 2.0
    cpu_shares: int | None = None
    pids_limit: int | None = 512
    tmpfs_size: str | None = "64m"
    network_mode: str | None = "none"
    oci_runtime: str | None = None
    work_dir: str = "/workspace"
    workspace_root: str | None = None
    persist_containers: bool = False
    prewarm: bool = True
    idle_timeout: int = 1800
    cleanup_interval: int = 300
    workspace_ttl: int | None = None
    container_ttl: int | None = None
    sandbox_uid: int | None = None
    max_read_bytes: int = 8 * 1024 * 1024
    execute_timeout: int = 300
    max_workers: int = 32
    max_running_commands: int = 256
    native_files: bool = True
    ui_enabled: bool = False
    policy_overrides: str | None = None
    """JSON file holding a `PolicyUpdate`, re-read while the service runs.

    The alternative to `PUT /policy` for a deployment that would rather not expose
    a write endpoint. Both go through the same validation and write the same live
    configuration, so neither can put the service in a state the other cannot
    describe. `None` disables it, which is the default.
    """

    def __post_init__(self) -> None:
        if not self.token:
            raise ValueError("SandboxdConfig.token must not be empty")
        if not self.runtimes:
            raise ValueError("SandboxdConfig.runtimes must allow at least one image")
        if not self.default_runtime:
            self.default_runtime = next(iter(self.runtimes))
        if self.default_runtime not in self.runtimes:
            raise ValueError(
                f"default_runtime {self.default_runtime!r} is not in runtimes "
                f"({', '.join(sorted(self.runtimes))})"
            )
        if self.evict_idle_after is not None and self.workspace_root is None:
            raise ValueError(
                "evict_idle_after needs workspace_root: hibernating a session whose "
                "files live only in its container would discard them silently"
            )
        if (
            self.max_open_sessions is not None
            and self.max_sessions is not None
            and self.max_open_sessions < self.max_sessions
        ):
            raise ValueError(
                f"max_open_sessions ({self.max_open_sessions}) is below max_sessions "
                f"({self.max_sessions}): a session has to exist to be resident"
            )

    def resolve_runtime(self, alias: str | None) -> tuple[str, SandboxRuntime]:
        """Resolve a client-supplied alias to an allowed runtime.

        Args:
            alias: Runtime alias from the request, or `None` for the default.

        Returns:
            The `(alias, runtime)` pair to use.

        Raises:
            KeyError: If the alias is not on the allowlist.
        """
        chosen = alias or self.default_runtime
        return chosen, _as_runtime(self.runtimes[chosen])

    def limits_for(self, runtime: SandboxRuntime) -> dict[str, Any]:
        """The ceilings one runtime actually runs under.

        Its own values where it names them, the service defaults otherwise.
        """
        return {
            "mem_limit": runtime.mem_limit if runtime.mem_limit is not None else self.mem_limit,
            "memswap_limit": (
                runtime.memswap_limit if runtime.memswap_limit is not None else self.memswap_limit
            ),
            "cpus": runtime.cpus if runtime.cpus is not None else self.cpus,
            "cpu_shares": (
                runtime.cpu_shares if runtime.cpu_shares is not None else self.cpu_shares
            ),
            "pids_limit": (
                runtime.pids_limit if runtime.pids_limit is not None else self.pids_limit
            ),
            "network_mode": (
                runtime.network_mode if runtime.network_mode is not None else self.network_mode
            ),
            "oci_runtime": (
                runtime.oci_runtime if runtime.oci_runtime is not None else self.oci_runtime
            ),
        }

resolve_runtime(alias)

Resolve a client-supplied alias to an allowed runtime.

Parameters:

Name Type Description Default
alias str | None

Runtime alias from the request, or None for the default.

required

Returns:

Type Description
tuple[str, SandboxRuntime]

The (alias, runtime) pair to use.

Raises:

Type Description
KeyError

If the alias is not on the allowlist.

Source code in src/pydantic_ai_backends/remote/server.py
Python
def resolve_runtime(self, alias: str | None) -> tuple[str, SandboxRuntime]:
    """Resolve a client-supplied alias to an allowed runtime.

    Args:
        alias: Runtime alias from the request, or `None` for the default.

    Returns:
        The `(alias, runtime)` pair to use.

    Raises:
        KeyError: If the alias is not on the allowlist.
    """
    chosen = alias or self.default_runtime
    return chosen, _as_runtime(self.runtimes[chosen])

limits_for(runtime)

The ceilings one runtime actually runs under.

Its own values where it names them, the service defaults otherwise.

Source code in src/pydantic_ai_backends/remote/server.py
Python
def limits_for(self, runtime: SandboxRuntime) -> dict[str, Any]:
    """The ceilings one runtime actually runs under.

    Its own values where it names them, the service defaults otherwise.
    """
    return {
        "mem_limit": runtime.mem_limit if runtime.mem_limit is not None else self.mem_limit,
        "memswap_limit": (
            runtime.memswap_limit if runtime.memswap_limit is not None else self.memswap_limit
        ),
        "cpus": runtime.cpus if runtime.cpus is not None else self.cpus,
        "cpu_shares": (
            runtime.cpu_shares if runtime.cpu_shares is not None else self.cpu_shares
        ),
        "pids_limit": (
            runtime.pids_limit if runtime.pids_limit is not None else self.pids_limit
        ),
        "network_mode": (
            runtime.network_mode if runtime.network_mode is not None else self.network_mode
        ),
        "oci_runtime": (
            runtime.oci_runtime if runtime.oci_runtime is not None else self.oci_runtime
        ),
    }

SandboxRuntime

One entry in the service's allowlist: what an alias runs, and under which ceilings.

pydantic_ai_backends.remote.server.SandboxRuntime dataclass

One entry in the service's runtime allowlist.

A client names the alias this is registered under and nothing else, so everything here is the operator's decision. Give it either a ready-made image, or a runtime whose packages are built into an image on first use.

The ceilings are per runtime, because they are not one number for a whole service: a notebook-style data runtime needs several gigabytes where a plain shell needs a few hundred megabytes, and forcing one value on both either starves the first or over-commits the host for the second. A ceiling left None takes the service-wide default from :class:SandboxdConfig, which is a default rather than a maximum — a runtime may name more.

Attributes:

Name Type Description
image str | None

Ready-made image, started as-is.

runtime RuntimeConfig | str | None

RuntimeConfig (or the name of a built-in one) whose packages are installed into an image the first time this runtime is used. Later sessions hit the build cache.

description str

What this environment is for, shown in the dashboard.

mem_limit str | None

Memory ceiling in Docker syntax, e.g. "2g".

memswap_limit str | None

Ceiling on memory and swap combined. None pins it to mem_limit, denying the sandbox swap. Only worth raising on a host whose swap is zram, where the pages stay in compressed RAM and the alternative to a little swapping is an OOM kill.

cpus float | None

Hard CPU ceiling in cores. A sandbox never exceeds it — and so cannot use cores that are idle.

cpu_shares int | None

Relative CPU weight, which applies only under contention. On a small host this is usually the better knob: one active sandbox may take the whole machine, and several are still divided fairly.

pids_limit int | None

Process ceiling.

network_mode str | None

Docker network mode. Naming anything but "none" here is how one runtime is allowed the network while others are not.

oci_runtime str | None

Low-level runtime the daemon starts this runtime's containers with — "runsc" for gVisor, "kata" for a microVM per container. Unlike the ceilings above this changes the isolation boundary, and it is per runtime for the same reason they are: the runtime that installs arbitrary packages off the network is the one worth paying gVisor's I/O overhead for, while a plain shell is not. Must be registered with the daemon; None takes its default.

Source code in src/pydantic_ai_backends/remote/server.py
Python
@dataclass(frozen=True, slots=True)
class SandboxRuntime:
    """One entry in the service's runtime allowlist.

    A client names the *alias* this is registered under and nothing else, so
    everything here is the operator's decision. Give it either a ready-made
    `image`, or a `runtime` whose packages are built into an image on first use.

    The ceilings are per runtime, because they are not one number for a whole
    service: a notebook-style data runtime needs several gigabytes where a plain
    shell needs a few hundred megabytes, and forcing one value on both either
    starves the first or over-commits the host for the second. A ceiling left
    `None` takes the service-wide default from :class:`SandboxdConfig`, which is
    a *default* rather than a maximum — a runtime may name more.

    Attributes:
        image: Ready-made image, started as-is.
        runtime: `RuntimeConfig` (or the name of a built-in one) whose packages
            are installed into an image the first time this runtime is used.
            Later sessions hit the build cache.
        description: What this environment is for, shown in the dashboard.
        mem_limit: Memory ceiling in Docker syntax, e.g. `"2g"`.
        memswap_limit: Ceiling on memory and swap combined. `None` pins it to
            `mem_limit`, denying the sandbox swap. Only worth raising on a host
            whose swap is `zram`, where the pages stay in compressed RAM and the
            alternative to a little swapping is an OOM kill.
        cpus: Hard CPU ceiling in cores. A sandbox never exceeds it — and so
            cannot use cores that are idle.
        cpu_shares: Relative CPU weight, which applies only under contention. On
            a small host this is usually the better knob: one active sandbox may
            take the whole machine, and several are still divided fairly.
        pids_limit: Process ceiling.
        network_mode: Docker network mode. Naming anything but `"none"` here is
            how one runtime is allowed the network while others are not.
        oci_runtime: Low-level runtime the daemon starts this runtime's
            containers with — `"runsc"` for gVisor, `"kata"` for a microVM per
            container. Unlike the ceilings above this changes the *isolation
            boundary*, and it is per runtime for the same reason they are: the
            runtime that installs arbitrary packages off the network is the one
            worth paying gVisor's I/O overhead for, while a plain shell is not.
            Must be registered with the daemon; `None` takes its default.
    """

    image: str | None = None
    runtime: RuntimeConfig | str | None = None
    description: str = ""
    mem_limit: str | None = None
    memswap_limit: str | None = None
    cpus: float | None = None
    cpu_shares: int | None = None
    pids_limit: int | None = None
    network_mode: str | None = None
    oci_runtime: str | None = None

    def __post_init__(self) -> None:
        if (self.image is None) == (self.runtime is None):
            raise ValueError("A SandboxRuntime needs exactly one of image or runtime")

    @property
    def builds(self) -> bool:
        """Whether first use builds an image rather than pulling a ready one."""
        return self.runtime is not None

    def resolved_runtime(self) -> RuntimeConfig | None:
        """The `RuntimeConfig` this entry builds, looked up when named."""
        if self.runtime is None:
            return None
        if isinstance(self.runtime, str):
            return get_runtime(self.runtime)
        return self.runtime

    def describes(self) -> str:
        """Human-readable summary of what will run, for the policy view."""
        if self.description:
            return self.description
        built = self.resolved_runtime()
        if built is not None:
            return built.description or f"built from {built.base_image or built.image}"
        return self.image or ""

    def image_label(self) -> str:
        """The image, or what it is built from when there is not one yet."""
        if self.image is not None:
            return self.image
        built = self.resolved_runtime()
        assert built is not None
        return built.image or f"{built.base_image} + {len(built.packages)} package(s)"

builds property

Whether first use builds an image rather than pulling a ready one.

resolved_runtime()

The RuntimeConfig this entry builds, looked up when named.

Source code in src/pydantic_ai_backends/remote/server.py
Python
def resolved_runtime(self) -> RuntimeConfig | None:
    """The `RuntimeConfig` this entry builds, looked up when named."""
    if self.runtime is None:
        return None
    if isinstance(self.runtime, str):
        return get_runtime(self.runtime)
    return self.runtime

describes()

Human-readable summary of what will run, for the policy view.

Source code in src/pydantic_ai_backends/remote/server.py
Python
def describes(self) -> str:
    """Human-readable summary of what will run, for the policy view."""
    if self.description:
        return self.description
    built = self.resolved_runtime()
    if built is not None:
        return built.description or f"built from {built.base_image or built.image}"
    return self.image or ""

image_label()

The image, or what it is built from when there is not one yet.

Source code in src/pydantic_ai_backends/remote/server.py
Python
def image_label(self) -> str:
    """The image, or what it is built from when there is not one yet."""
    if self.image is not None:
        return self.image
    built = self.resolved_runtime()
    assert built is not None
    return built.image or f"{built.base_image} + {len(built.packages)} package(s)"

create_app

pydantic_ai_backends.remote.server.create_app(config, *, sandbox_builder=None)

Build the sandbox service.

Parameters:

Name Type Description Default
config SandboxdConfig

Service policy. See :class:SandboxdConfig.

required
sandbox_builder SandboxBuilder | None

Override for how a sandbox is constructed, receiving (session_id, image). Defaults to :class:DockerSandbox configured from config. Supply one to embed a different sandbox type, or to test without a Docker daemon.

None

Returns:

Type Description
FastAPI

A configured FastAPI application.

Source code in src/pydantic_ai_backends/remote/server.py
Python
def create_app(
    config: SandboxdConfig,
    *,
    sandbox_builder: SandboxBuilder | None = None,
) -> FastAPI:
    """Build the sandbox service.

    Args:
        config: Service policy. See :class:`SandboxdConfig`.
        sandbox_builder: Override for how a sandbox is constructed, receiving
            `(session_id, image)`. Defaults to :class:`DockerSandbox` configured
            from `config`. Supply one to embed a different sandbox type, or to
            test without a Docker daemon.

    Returns:
        A configured `FastAPI` application.
    """
    # Prewarming and the container sweep only make sense for the builder that
    # knows what an image is; an injected builder may have nothing to pull and no
    # daemon to ask.
    service = _Service(
        config,
        sandbox_builder or _default_builder(config),
        prewarm=None if sandbox_builder else _default_prewarm(config),
        docker_client=None if sandbox_builder else _default_docker_client,
        reattach_sandbox=None if sandbox_builder else _default_builder(config, reattach_only=True),
    )

    @asynccontextmanager
    async def lifespan(_: FastAPI) -> AsyncIterator[None]:
        service.startup()
        try:
            yield
        finally:
            await service.shutdown()

    app = FastAPI(
        title="sandboxd",
        summary="Sandbox execution service for AI agents",
        lifespan=lifespan,
    )
    app.state.service = service
    _register_session_routes(app, service)
    _register_workspace_routes(app, service)
    _register_run_routes(app, service)
    return app

Configuration from the environment

Every field of SandboxdConfig is SANDBOXD_ plus its name in upper case. The shipped entrypoint — python -m pydantic_ai_backends.remote.server — is this plus uvicorn, and it is importable so a service embedded in something larger can parse the environment and then adjust what it produced.

pydantic_ai_backends.remote.env.config_from_env(env)

The service configuration these variables describe.

Parameters:

Name Type Description Default
env Mapping[str, str]

Usually os.environ. Taken as an argument so a configuration can be tested without touching the process.

required

Returns:

Type Description
SandboxdConfig

A validated SandboxdConfig. Absent variables take the dataclass

SandboxdConfig

default, so an empty environment (bar the token) is the shipped policy.

Raises:

Type Description
SandboxdConfigError

If a variable is missing, unparseable, or describes a combination the service refuses.

Source code in src/pydantic_ai_backends/remote/env.py
Python
def config_from_env(env: Mapping[str, str]) -> SandboxdConfig:
    """The service configuration these variables describe.

    Args:
        env: Usually `os.environ`. Taken as an argument so a configuration can
            be tested without touching the process.

    Returns:
        A validated `SandboxdConfig`. Absent variables take the dataclass
        default, so an empty environment (bar the token) is the shipped policy.

    Raises:
        SandboxdConfigError: If a variable is missing, unparseable, or describes
            a combination the service refuses.
    """
    token = _text(env, "TOKEN", "")
    if not token:
        raise SandboxdConfigError(
            f"{PREFIX}TOKEN is required. It authorises opening a session, and a "
            "session can run commands on this host — generate a long random value."
        )

    # A sentinel instance, read for the shipped value of each scalar field so
    # this module does not keep a second copy of thirty defaults to drift from.
    # `default_runtime` is deliberately *not* taken from it: `__post_init__`
    # resolves an empty one to the first entry of the allowlist, so reading it
    # back would pin every deployment to the first of the *shipped* allowlist
    # and refuse any custom one. `test_env.py` guards the rest against becoming
    # derived in the same way.
    defaults = SandboxdConfig(token=token, runtimes=DEFAULT_RUNTIMES)
    raw_runtimes = env.get(PREFIX + "RUNTIMES")
    try:
        return SandboxdConfig(
            token=token,
            runtimes=(DEFAULT_RUNTIMES if raw_runtimes is None else _parse_runtimes(raw_runtimes)),
            default_runtime=_text(env, "DEFAULT_RUNTIME", ""),
            max_sessions=_optional(env, "MAX_SESSIONS", defaults.max_sessions, _as_int),
            max_open_sessions=_optional(
                env, "MAX_OPEN_SESSIONS", defaults.max_open_sessions, _as_int
            ),
            max_sessions_per_tenant=_optional(
                env, "MAX_SESSIONS_PER_TENANT", defaults.max_sessions_per_tenant, _as_int
            ),
            evict_idle_after=_optional(env, "EVICT_IDLE_AFTER", defaults.evict_idle_after, _as_int),
            mem_limit=_optional(env, "MEM_LIMIT", defaults.mem_limit, str),
            memswap_limit=_optional(env, "MEMSWAP_LIMIT", defaults.memswap_limit, str),
            cpus=_optional(env, "CPUS", defaults.cpus, _as_float),
            cpu_shares=_optional(env, "CPU_SHARES", defaults.cpu_shares, _as_int),
            pids_limit=_optional(env, "PIDS_LIMIT", defaults.pids_limit, _as_int),
            tmpfs_size=_optional(env, "TMPFS_SIZE", defaults.tmpfs_size, str),
            network_mode=_optional(env, "NETWORK_MODE", defaults.network_mode, str),
            oci_runtime=_optional(env, "OCI_RUNTIME", defaults.oci_runtime, str),
            work_dir=_required_text(env, "WORK_DIR", defaults.work_dir),
            workspace_root=_optional(env, "WORKSPACE_ROOT", defaults.workspace_root, str),
            persist_containers=_flag(env, "PERSIST_CONTAINERS", defaults.persist_containers),
            prewarm=_flag(env, "PREWARM", defaults.prewarm),
            idle_timeout=_value(env, "IDLE_TIMEOUT", defaults.idle_timeout, _as_int),
            cleanup_interval=_value(env, "CLEANUP_INTERVAL", defaults.cleanup_interval, _as_int),
            workspace_ttl=_optional(env, "WORKSPACE_TTL", defaults.workspace_ttl, _as_int),
            container_ttl=_optional(env, "CONTAINER_TTL", defaults.container_ttl, _as_int),
            sandbox_uid=_optional(env, "SANDBOX_UID", defaults.sandbox_uid, _as_int),
            max_read_bytes=_value(env, "MAX_READ_BYTES", defaults.max_read_bytes, _as_int),
            execute_timeout=_value(env, "EXECUTE_TIMEOUT", defaults.execute_timeout, _as_int),
            max_workers=_value(env, "MAX_WORKERS", defaults.max_workers, _as_int),
            max_running_commands=_value(
                env, "MAX_RUNNING_COMMANDS", defaults.max_running_commands, _as_int
            ),
            native_files=_flag(env, "NATIVE_FILES", defaults.native_files),
            ui_enabled=_flag(env, "UI_ENABLED", defaults.ui_enabled),
            policy_overrides=_optional(env, "POLICY_OVERRIDES", defaults.policy_overrides, str),
        )
    except ValueError as e:
        # `SandboxdConfig` refuses combinations no single variable is wrong in —
        # `evict_idle_after` without `workspace_root`, a `default_runtime` no
        # entry defines. Its messages name the fields, which are the variables
        # in lower case, so they are re-raised rather than paraphrased.
        raise SandboxdConfigError(str(e)) from e

pydantic_ai_backends.remote.env.bind_from_env(env)

The address to serve on: SANDBOXD_HOST and SANDBOXD_PORT.

Separate from the service policy because it is not part of it — the same configuration served on a different port is the same service.

Source code in src/pydantic_ai_backends/remote/env.py
Python
def bind_from_env(env: Mapping[str, str]) -> tuple[str, int]:
    """The address to serve on: `SANDBOXD_HOST` and `SANDBOXD_PORT`.

    Separate from the service policy because it is not part of it — the same
    configuration served on a different port is the same service.
    """
    return _text(env, "HOST", "127.0.0.1"), _value(env, "PORT", 8080, _as_int)

pydantic_ai_backends.remote.env.SandboxdConfigError

Bases: ValueError

The environment does not describe a service that could start.

A ValueError rather than SystemExit: turning a bad configuration into an exit code is the entrypoint's decision, and a caller embedding the service in its own application wants to catch this, not be terminated by it.

Source code in src/pydantic_ai_backends/remote/env.py
Python
class SandboxdConfigError(ValueError):
    """The environment does not describe a service that could start.

    A `ValueError` rather than `SystemExit`: turning a bad configuration into an
    exit code is the entrypoint's decision, and a caller embedding the service
    in its own application wants to catch this, not be terminated by it.
    """

Wire protocol

The HTTP contract as Pydantic models — one source of truth for both sides.

Wire protocol between sandboxd and its clients.

These models are the single source of truth for the HTTP contract: sessions, /run for a Pydantic AI workspace, the archive reads, the policy.

Binary payloads travel base64-encoded (content_b64) because JSON cannot carry arbitrary bytes, and a workspace holds real files.

CreateSessionRequest

Bases: BaseModel

Open a sandbox session.

Deliberately carries no container settings. Image, mounts, network mode and every resource ceiling come from the server's configuration, because a process holding the Docker socket can start a privileged container that mounts the host — a client that could name its own image or volumes would own the machine.

Source code in src/pydantic_ai_backends/remote/wire.py
Python
class CreateSessionRequest(BaseModel):
    """Open a sandbox session.

    Deliberately carries no container settings. Image, mounts, network mode and
    every resource ceiling come from the server's configuration, because a
    process holding the Docker socket can start a privileged container that
    mounts the host — a client that could name its own image or volumes would
    own the machine.
    """

    session_id: str | None = Field(default=None, pattern=SESSION_ID_PATTERN)
    runtime: str | None = None
    """Alias of a server-allowed runtime. `None` selects the server default."""

    tenant: str | None = Field(default=None, pattern=TENANT_PATTERN)
    """Who this session is opened on behalf of, for the per-tenant ceiling.

    Declared by the client rather than derived from `session_id`, so the service
    imposes no naming convention on ids. Only a caller holding the service token
    can open a session at all, so this is a capacity label from a trusted
    application — not an authorization claim, and it grants nothing.
    """

    reuse: bool = False
    """Attach to the session under `session_id` when one is already open.

    Off by default, so an id collision is reported rather than silently sharing
    somebody else's sandbox. Turn it on for a session that spans several runs —
    one conversation, say — where the second run has to reach the files the
    first one wrote. The runtime of an attached session is whatever it was
    opened with; a `runtime` that disagrees is rejected rather than ignored.
    """

    attach: bool = False
    """Only attach, never create: refuse with 404 when `session_id` names neither
    an open session nor a workspace this service still holds.

    What a client continuing earlier work needs. `reuse` alone opens a fresh,
    empty session when the old one is gone, so the caller would carry on in an
    empty directory believing its files were there. Implies `reuse`.
    """

runtime = None class-attribute instance-attribute

Alias of a server-allowed runtime. None selects the server default.

tenant = Field(default=None, pattern=TENANT_PATTERN) class-attribute instance-attribute

Who this session is opened on behalf of, for the per-tenant ceiling.

Declared by the client rather than derived from session_id, so the service imposes no naming convention on ids. Only a caller holding the service token can open a session at all, so this is a capacity label from a trusted application — not an authorization claim, and it grants nothing.

reuse = False class-attribute instance-attribute

Attach to the session under session_id when one is already open.

Off by default, so an id collision is reported rather than silently sharing somebody else's sandbox. Turn it on for a session that spans several runs — one conversation, say — where the second run has to reach the files the first one wrote. The runtime of an attached session is whatever it was opened with; a runtime that disagrees is rejected rather than ignored.

attach = False class-attribute instance-attribute

Only attach, never create: refuse with 404 when session_id names neither an open session nor a workspace this service still holds.

What a client continuing earlier work needs. reuse alone opens a fresh, empty session when the old one is gone, so the caller would carry on in an empty directory believing its files were there. Implies reuse.

RunRequest

Bases: BaseModel

Run one program, under the contract a Pydantic AI workspace needs.

The streams come back apart, a dead sandbox is reported as one rather than as a command that failed, and a command whose caller gave up can be stopped.

Source code in src/pydantic_ai_backends/remote/wire.py
Python
class RunRequest(BaseModel):
    """Run one program, under the contract a Pydantic AI workspace needs.

    The streams come back apart, a dead sandbox is reported as one rather than
    as a command that failed, and a command whose caller gave up can be stopped.
    """

    argv: list[str] = Field(min_length=1)
    """The program and its arguments, passed through literally. A shell command
    is `["/bin/sh", "-c", "..."]`, spelled out by the client."""

    env: dict[str, str] = Field(default_factory=dict)
    """Variables layered over the sandbox's own environment."""

    timeout_seconds: float | None = Field(default=None, gt=0)
    """Deadline for the command. Clamped to the service's `execute_timeout`, and
    that ceiling applies when this is `None`."""

    run_id: str = Field(pattern=RUN_ID_PATTERN)
    """Chosen by the client, so it can stop the run from another request when it
    stops waiting for this one."""

argv = Field(min_length=1) class-attribute instance-attribute

The program and its arguments, passed through literally. A shell command is ["/bin/sh", "-c", "..."], spelled out by the client.

env = Field(default_factory=dict) class-attribute instance-attribute

Variables layered over the sandbox's own environment.

timeout_seconds = Field(default=None, gt=0) class-attribute instance-attribute

Deadline for the command. Clamped to the service's execute_timeout, and that ceiling applies when this is None.

run_id = Field(pattern=RUN_ID_PATTERN) class-attribute instance-attribute

Chosen by the client, so it can stop the run from another request when it stops waiting for this one.

RunResponse

Bases: BaseModel

How a /run command ended: finished, timed out, or over its output limit.

A non-zero exit_code is a result. timed_out and output_limited carry no exit code and only the beginning of each stream, because the command was stopped rather than allowed to finish.

Source code in src/pydantic_ai_backends/remote/wire.py
Python
class RunResponse(BaseModel):
    """How a `/run` command ended: finished, timed out, or over its output limit.

    A non-zero `exit_code` is a result. `timed_out` and `output_limited` carry no
    exit code and only the beginning of each stream, because the command was
    stopped rather than allowed to finish.
    """

    stdout: str
    stderr: str
    exit_code: int | None = None
    timed_out: bool = False
    output_limited: bool = False
    output_limit: int | None = None
    """The ceiling an `output_limited` command crossed, in bytes."""

output_limit = None class-attribute instance-attribute

The ceiling an output_limited command crossed, in bytes.

SessionCreated

Bases: BaseModel

A freshly opened session and the token scoped to it.

Source code in src/pydantic_ai_backends/remote/wire.py
Python
class SessionCreated(BaseModel):
    """A freshly opened session and the token scoped to it."""

    session: SessionInfo
    token: str
    """Grants access to this session only. The service token also works."""

token instance-attribute

Grants access to this session only. The service token also works.

SessionInfo

Bases: BaseModel

Observable state of one session.

Source code in src/pydantic_ai_backends/remote/wire.py
Python
class SessionInfo(BaseModel):
    """Observable state of one session."""

    session_id: str
    runtime: str
    tenant: str | None = None
    """Whoever the session was opened for, when the client said."""
    alive: bool
    state: Literal["running", "hibernated"] = "running"
    """Whether the session holds a sandbox, or was stopped to free a slot and is
    waiting for its next request to wake it. A hibernated session is never
    `alive`; it still has its token, its event log and its files."""
    created_at: float
    last_activity: float
    idle_seconds: float
    usage: SessionUsage | None = None

tenant = None class-attribute instance-attribute

Whoever the session was opened for, when the client said.

state = 'running' class-attribute instance-attribute

Whether the session holds a sandbox, or was stopped to free a slot and is waiting for its next request to wake it. A hibernated session is never alive; it still has its token, its event log and its files.

SessionList

Bases: BaseModel

Every open session, for monitoring.

Source code in src/pydantic_ai_backends/remote/wire.py
Python
class SessionList(BaseModel):
    """Every open session, for monitoring."""

    sessions: list[SessionInfo] = Field(default_factory=list)
    limit: int | None = None
    """Configured `max_sessions` — the ceiling on *resident* sandboxes."""
    open_limit: int | None = None
    """Configured `max_open_sessions`, or `None` when uncapped."""
    tenant_limit: int | None = None
    """Configured `max_sessions_per_tenant`, or `None` when uncapped."""

limit = None class-attribute instance-attribute

Configured max_sessions — the ceiling on resident sandboxes.

open_limit = None class-attribute instance-attribute

Configured max_open_sessions, or None when uncapped.

tenant_limit = None class-attribute instance-attribute

Configured max_sessions_per_tenant, or None when uncapped.

SessionUsage

Bases: BaseModel

Point-in-time resource usage for one sandbox.

Source code in src/pydantic_ai_backends/remote/wire.py
Python
class SessionUsage(BaseModel):
    """Point-in-time resource usage for one sandbox."""

    memory_bytes: int | None = None
    memory_limit_bytes: int | None = None
    cpu_percent: float | None = None
    pids: int | None = None

SessionEvent

Bases: BaseModel

One operation performed against a session.

Records what was asked for and how it went — never file contents or command output, which would turn an audit trail into a data leak and grow without bound.

Source code in src/pydantic_ai_backends/remote/wire.py
Python
class SessionEvent(BaseModel):
    """One operation performed against a session.

    Records what was asked for and how it went — never file contents or command
    output, which would turn an audit trail into a data leak and grow without
    bound.
    """

    seq: int
    """Monotonic per-session sequence number, for incremental polling."""
    at: float
    op: str
    """Operation name: `run` for a command, which is the one operation a session takes."""
    target: str
    """Command or path the operation addressed, truncated."""
    ok: bool
    detail: str = ""
    """Short outcome summary, e.g. `exit 0` or `14 entries`."""
    duration_ms: float = 0.0

seq instance-attribute

Monotonic per-session sequence number, for incremental polling.

op instance-attribute

Operation name: run for a command, which is the one operation a session takes.

target instance-attribute

Command or path the operation addressed, truncated.

detail = '' class-attribute instance-attribute

Short outcome summary, e.g. exit 0 or 14 entries.

SessionEvents

Bases: BaseModel

A slice of a session's activity log.

Source code in src/pydantic_ai_backends/remote/wire.py
Python
class SessionEvents(BaseModel):
    """A slice of a session's activity log."""

    events: list[SessionEvent] = Field(default_factory=list)
    latest_seq: int = 0
    """Highest sequence number the service holds; pass it back as `after`."""

latest_seq = 0 class-attribute instance-attribute

Highest sequence number the service holds; pass it back as after.

ServiceHealth

Bases: BaseModel

Liveness and capacity summary. Unauthenticated.

Source code in src/pydantic_ai_backends/remote/wire.py
Python
class ServiceHealth(BaseModel):
    """Liveness and capacity summary. Unauthenticated."""

    status: str = "ok"
    sessions: int = 0
    """Sessions holding a sandbox right now."""
    limit: int | None = None
    open_sessions: int = 0
    """Sessions that exist, resident and hibernated together."""
    open_limit: int | None = None
    runtimes: list[str] = Field(default_factory=list)

sessions = 0 class-attribute instance-attribute

Sessions holding a sandbox right now.

open_sessions = 0 class-attribute instance-attribute

Sessions that exist, resident and hibernated together.

ServicePolicy

Bases: BaseModel

The ceilings and allowlist the service imposes on every sandbox.

Authenticated, because it describes the host's configuration — though it holds nothing a caller with the service token is not already subject to. Exists so an operator can see the limits actually in force rather than inferring them from a config file.

Source code in src/pydantic_ai_backends/remote/wire.py
Python
class ServicePolicy(BaseModel):
    """The ceilings and allowlist the service imposes on every sandbox.

    Authenticated, because it describes the host's configuration — though it
    holds nothing a caller with the service token is not already subject to.
    Exists so an operator can see the limits actually in force rather than
    inferring them from a config file.
    """

    runtimes: list[RuntimePolicy] = Field(default_factory=list)
    """Every allowed runtime, with the ceilings it actually runs under."""
    default_runtime: str = ""
    max_sessions: int | None = None
    """Ceiling on resident sandboxes."""
    max_open_sessions: int | None = None
    """Ceiling on sessions that exist, resident or hibernated."""
    max_sessions_per_tenant: int | None = None
    evict_idle_after: int | None = None
    """Seconds after which an idle session may be hibernated to free a slot."""
    mem_limit: str | None = None
    memswap_limit: str | None = None
    """Default memory-plus-swap ceiling, or `None` when swap is pinned to memory."""
    cpus: float | None = None
    cpu_shares: int | None = None
    pids_limit: int | None = None
    network_mode: str | None = None
    oci_runtime: str | None = None
    """Default low-level runtime, or `None` for whatever the daemon defaults to."""

    work_dir: str = ""
    idle_timeout: int = 0
    execute_timeout: int = 0
    max_read_bytes: int = 0
    persist_containers: bool = False
    """Whether a stopped sandbox keeps its filesystem for the next attach."""
    sandbox_uid: int | None = None
    """Uid built runtimes run as, or `None` when sandboxes run as root."""
    workspace_ttl: int | None = None
    """Seconds an unused workspace is kept before it is swept, or `None`."""
    container_ttl: int | None = None
    """Seconds a stopped container is kept before its build is reclaimed."""
    tmpfs_size: str | None = None
    """Size of the in-memory `/tmp` each sandbox gets, or `None` when it has none."""
    prewarm: bool = False
    """Whether the allowlist is pulled and built at startup rather than on demand."""
    buildkit: bool = False
    """Whether image builds use BuildKit, and so keep package caches between them."""
    native_files: bool = False
    """Whether a session's file operations are served off the host, not by its sandbox.

    Defaults off, so a client talking to a service older than this falls back to
    the shell path rather than calling routes that are not there."""
    native_writes: bool = False
    """Whether writes are served that way too, and not only reads."""
    native_realpath: bool = False
    """Whether `realpath` is answered off the host for a path with no link in it.

    The console's path checks ask it before every read and write, so without it
    each of those cost a `docker exec` of its own."""

runtimes = Field(default_factory=list) class-attribute instance-attribute

Every allowed runtime, with the ceilings it actually runs under.

max_sessions = None class-attribute instance-attribute

Ceiling on resident sandboxes.

max_open_sessions = None class-attribute instance-attribute

Ceiling on sessions that exist, resident or hibernated.

evict_idle_after = None class-attribute instance-attribute

Seconds after which an idle session may be hibernated to free a slot.

memswap_limit = None class-attribute instance-attribute

Default memory-plus-swap ceiling, or None when swap is pinned to memory.

oci_runtime = None class-attribute instance-attribute

Default low-level runtime, or None for whatever the daemon defaults to.

persist_containers = False class-attribute instance-attribute

Whether a stopped sandbox keeps its filesystem for the next attach.

sandbox_uid = None class-attribute instance-attribute

Uid built runtimes run as, or None when sandboxes run as root.

workspace_ttl = None class-attribute instance-attribute

Seconds an unused workspace is kept before it is swept, or None.

container_ttl = None class-attribute instance-attribute

Seconds a stopped container is kept before its build is reclaimed.

tmpfs_size = None class-attribute instance-attribute

Size of the in-memory /tmp each sandbox gets, or None when it has none.

prewarm = False class-attribute instance-attribute

Whether the allowlist is pulled and built at startup rather than on demand.

buildkit = False class-attribute instance-attribute

Whether image builds use BuildKit, and so keep package caches between them.

native_files = False class-attribute instance-attribute

Whether a session's file operations are served off the host, not by its sandbox.

Defaults off, so a client talking to a service older than this falls back to the shell path rather than calling routes that are not there.

native_writes = False class-attribute instance-attribute

Whether writes are served that way too, and not only reads.

native_realpath = False class-attribute instance-attribute

Whether realpath is answered off the host for a path with no link in it.

The console's path checks ask it before every read and write, so without it each of those cost a docker exec of its own.

ServiceIndex

Bases: BaseModel

What this service is and where to find its endpoints.

Served at / so that opening the base URL says something useful instead of a bare 404. Unauthenticated, and deliberately free of any session detail.

Source code in src/pydantic_ai_backends/remote/wire.py
Python
class ServiceIndex(BaseModel):
    """What this service is and where to find its endpoints.

    Served at `/` so that opening the base URL says something useful instead of
    a bare 404. Unauthenticated, and deliberately free of any session detail.
    """

    service: str = "sandboxd"
    health: ServiceHealth
    docs_url: str = "/docs"
    openapi_url: str = "/openapi.json"
    ui_url: str | None = None
    """Where the dashboard lives, or `None` when it is not enabled."""
    endpoints: list[str] = Field(default_factory=list)
    """Routed paths, derived from the app so the list cannot go stale."""

ui_url = None class-attribute instance-attribute

Where the dashboard lives, or None when it is not enabled.

endpoints = Field(default_factory=list) class-attribute instance-attribute

Routed paths, derived from the app so the list cannot go stale.