botbox 0.0.2__tar.gz → 0.0.4__tar.gz

{botbox-0.0.2 → botbox-0.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: botbox
-Version: 0.0.2
+Version: 0.0.4
 Summary: Run a coding agent inside a locked-down Docker container.
 Project-URL: Repository, https://github.com/thekevinscott/botbox
 Author-email: Kevin Scott <me@thekevinscott.com>

botbox-0.0.4/src/botbox/Botbox.py

@@ -0,0 +1,93 @@
+import hashlib
+from collections.abc import Sequence
+from contextlib import suppress
+from pathlib import Path
+from tempfile import TemporaryDirectory
+
+from python_on_whales import docker
+from python_on_whales.exceptions import DockerException
+
+from botbox.agents.agent import Agent
+from botbox.bind_mounts import Mount, bind_mounts
+from botbox.collect import collect
+from botbox.lockdown import lockdown
+from botbox.RunResult import RunResult
+
+
+class Botbox:
+    """An agent, an optional image layer on top of it, and the extra hosts its proxy admits."""
+
+    def __init__(
+        self,
+        agent: Agent,
+        *,
+        dockerfile: str | Path | None = None,
+        allow: Sequence[str] = (),
+    ) -> None:
+        self.agent = agent
+        self.dockerfile = None if dockerfile is None else Path(dockerfile).resolve()
+        self.allow = tuple(allow)
+
+    def build(self) -> str:
+        """Build the agent's image, then `dockerfile` on top, and return the final tag.
+
+        Built on every call; Docker's layer cache keeps an unchanged build fast.
+        """
+        agent_dockerfile = self.agent.dockerfile
+        docker.build(
+            agent_dockerfile.parent, tags=self.agent.image, file=agent_dockerfile, progress=False
+        )
+        if self.dockerfile is None:
+            return self.agent.image
+        digest = hashlib.sha256(str(self.dockerfile).encode()).hexdigest()[:12]
+        tag = f"{self.agent.image.split(':')[0]}-{digest}:latest"
+        docker.build(self.dockerfile.parent, tags=tag, file=self.dockerfile, progress=False)
+        return tag
+
+    def run(
+        self,
+        command: str,
+        *,
+        mounts: Sequence[Mount] = (),
+        workdir: str | Path | None = None,
+    ) -> RunResult:
+        """Run `command` as `sh -c` in the locked-down container and return what it left.
+
+        Mounts and `workdir` are checked before anything is built. The agent's home is a fresh
+        host temp directory with the credentials staged in; the proxy logs into the same
+        directory. Both are read into the result once the container is gone, then deleted.
+        A non-zero exit is a normal result; so is the daemon dying mid-run, with `exit_code`
+        -1 and whatever output, transcript and proxy log made it to the host. Raises only when
+        setup fails or the run is interrupted, after tearing down what was started.
+        """
+        agent = self.agent
+        volumes = bind_mounts(mounts, workdir=workdir, home=agent.home)
+        image = self.build()
+        with TemporaryDirectory(prefix="botbox-") as scratch:
+            home = Path(scratch) / "home"
+            home.mkdir()
+            agent.stage_auth(home)
+            with lockdown((*agent.allow, *self.allow), Path(scratch)) as jail:
+                container = docker.run(
+                    image,
+                    ["sh", "-c", command],
+                    detach=True,
+                    envs=jail.envs,
+                    volumes=[(str(home), agent.home, "rw"), *volumes],
+                    workdir=agent.home if workdir is None else Path(workdir).as_posix(),
+                    networks=[jail.network],
+                    user="node",
+                    cap_drop=["ALL"],
+                    security_options=["no-new-privileges"],
+                )
+                try:
+                    stdout, stderr, exit_code = collect(container)
+                finally:
+                    with suppress(DockerException):
+                        docker.container.remove(container, force=True)
+            transcript = {
+                path.relative_to(home).as_posix(): path.read_text()
+                for path in sorted(home.glob(agent.transcripts))
+                if path.is_file()
+            }
+        return RunResult(stdout, stderr, exit_code, transcript, jail.log)

botbox-0.0.4/src/botbox/RunResult.py

@@ -0,0 +1,17 @@
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class RunResult:
+    """What a run left behind. Nothing parsed.
+
+    `exit_code` is -1 when no exit code came back: the Docker daemon went away mid-run.
+    `transcript` maps each transcript file's path, relative to the agent's home, to its text.
+    `proxy` is the proxy's log: every connection, admitted or refused.
+    """
+
+    stdout: str
+    stderr: str
+    exit_code: int
+    transcript: dict[str, str]
+    proxy: str

{botbox-0.0.2 → botbox-0.0.4}/src/botbox/__init__.py

@@ -2,5 +2,6 @@
 
 from botbox.agents import Agent, ClaudeAgent, PiAgent
 from botbox.Botbox import Botbox
+from botbox.RunResult import RunResult
 
-__all__ = ["Agent", "Botbox", "ClaudeAgent", "PiAgent"]
+__all__ = ["Agent", "Botbox", "ClaudeAgent", "PiAgent", "RunResult"]

{botbox-0.0.2 → botbox-0.0.4}/src/botbox/agents/ClaudeAgent.py

@@ -1,3 +1,4 @@
+import shlex
 import shutil
 from pathlib import Path
 
@@ -13,9 +14,27 @@ class ClaudeAgent:
     transcripts = ".claude/projects/**/*.jsonl"
     allow: tuple[str, ...] = ("api.anthropic.com",)
 
-    def __init__(self, *, host_home: Path | None = None) -> None:
+    def __init__(
+        self,
+        model: str | None = None,
+        effort: str | None = None,
+        *,
+        host_home: Path | None = None,
+    ) -> None:
+        self.model = model
+        self.effort = effort
         self.host_home = Path.home() / ".claude" if host_home is None else host_home
 
+    def command(self, prompt: str) -> str:
+        command = (
+            f"claude -p {shlex.quote(prompt)} --output-format json --dangerously-skip-permissions"
+        )
+        if self.model is not None:
+            command += f" --model {self.model}"
+        if self.effort is not None:
+            command += f" --effort {self.effort}"
+        return command
+
     def stage_auth(self, home: Path) -> None:
         destination = home / ".claude"
         destination.mkdir()

{botbox-0.0.2 → botbox-0.0.4}/src/botbox/agents/PiAgent.py

@@ -1,4 +1,5 @@
 import os
+import shlex
 import shutil
 from pathlib import Path
 
@@ -29,13 +30,22 @@ class PiAgent:
     home = "/home/node"
     transcripts = ".pi/agent/sessions/**/*.jsonl"
 
-    def __init__(self, provider: str, *, host_home: Path | None = None) -> None:
+    def __init__(
+        self, provider: str, model: str | None = None, *, host_home: Path | None = None
+    ) -> None:
         if provider not in PROVIDERS:
             raise ValueError(f"unknown provider {provider!r}: expected {', '.join(PROVIDERS)}")
         self.provider = provider
+        self.model = model
         self.allow = resolve_allow(provider)
         self.host_home = Path.home() / ".pi" / "agent" if host_home is None else host_home
 
+    def command(self, prompt: str) -> str:
+        command = f"pi -p {shlex.quote(prompt)} --mode json --provider {self.provider}"
+        if self.model is not None:
+            command += f" --model {self.model}"
+        return command
+
     def stage_auth(self, home: Path) -> None:
         destination = home / ".pi" / "agent"
         destination.mkdir(parents=True)

{botbox-0.0.2 → botbox-0.0.4}/src/botbox/agents/agent.py

@@ -17,3 +17,7 @@ class Agent(Protocol):
     def stage_auth(self, home: Path) -> None:
         """Copy the host's credentials into `home`, the per-run temp home."""
         ...
+
+    def command(self, prompt: str) -> str:
+        """The agent's CLI invocation for `prompt`, as a shell string for `run()`."""
+        ...

botbox-0.0.4/src/botbox/bind_mounts.py

@@ -0,0 +1,28 @@
+import posixpath
+from collections.abc import Sequence
+from pathlib import Path
+from typing import Literal
+
+Mount = tuple[str | Path, str | Path, Literal["ro", "rw"]]
+
+
+def bind_mounts(
+    mounts: Sequence[Mount], *, workdir: str | Path | None, home: str
+) -> list[tuple[str, str, str]]:
+    """Check `mounts` and `workdir` and return the mounts as docker volumes.
+
+    A missing host path raises: Docker would create it, root-owned. So would a `workdir`
+    outside every mount, the agent's home included, so that raises too.
+    """
+    volumes: list[tuple[str, str, str]] = []
+    for host, container, mode in mounts:
+        source = Path(host).resolve()
+        if not source.exists():
+            raise FileNotFoundError(f"mount source {host} does not exist")
+        volumes.append((str(source), Path(container).as_posix(), mode))
+    if workdir is not None:
+        start = posixpath.normpath(Path(workdir).as_posix())
+        targets = [home, *(posixpath.normpath(target) for _, target, _ in volumes)]
+        if not any(start == t or start.startswith(t.rstrip("/") + "/") for t in targets):
+            raise ValueError(f"workdir {workdir} is not a mounted path or inside one")
+    return volumes

botbox-0.0.4/src/botbox/collect.py

@@ -0,0 +1,26 @@
+from collections.abc import Iterable
+from typing import cast
+
+from python_on_whales import docker
+from python_on_whales.components.container.cli_wrapper import Container
+from python_on_whales.exceptions import DockerException
+
+
+def collect(container: Container | str) -> tuple[str, str, int]:
+    """Follow a container to its exit: its stdout, its stderr, and its exit code.
+
+    Output streams to the host as the container writes it. If the daemon goes away first,
+    what already arrived is kept and the exit code is -1.
+    """
+    output: dict[str, list[bytes]] = {"stdout": [], "stderr": []}
+    exit_code = -1
+    try:
+        # stream=True makes logs() yield (source, chunk) pairs instead of returning a str.
+        stream = cast(Iterable[tuple[str, bytes]], docker.logs(container, follow=True, stream=True))
+        for source, chunk in stream:
+            output[source].append(chunk)
+        exit_code = docker.wait(container)
+    except DockerException:
+        pass  # The daemon died mid-run: return what arrived rather than raise.
+    stdout, stderr = (b"".join(output[s]).decode(errors="replace") for s in ("stdout", "stderr"))
+    return stdout, stderr, exit_code

botbox-0.0.4/src/botbox/lockdown.py

@@ -0,0 +1,99 @@
+import re
+from collections.abc import Generator, Iterable
+from contextlib import contextmanager, suppress
+from pathlib import Path
+from uuid import uuid4
+
+from python_on_whales import docker
+from python_on_whales import utils as docker_utils
+from python_on_whales.exceptions import DockerException
+
+PROXY_DIR = Path(__file__).with_name("proxy")
+PROXY_IMAGE = "botbox-proxy:latest"
+PROXY_PORT = 8888
+PROXY_LOG_DIR = "/var/log/tinyproxy"
+
+
+class Lockdown:
+    """The network a locked-down container joins, the proxy env it runs under, and the proxy log."""
+
+    def __init__(self, network: str, envs: dict[str, str]) -> None:
+        self.network = network
+        self.envs = envs
+        self.log = ""
+
+
+@contextmanager
+def lockdown(allow: Iterable[str], scratch: Path) -> Generator[Lockdown]:
+    """Yield the network and proxy env a locked-down container runs under.
+
+    The container joins an `--internal` network: no gateway, no route out, no external DNS.
+    Its only way out is a CONNECT to the sidecar, which sits on a second network and refuses
+    anything outside `allow`. tinyproxy writes its log into `scratch` on the host as it runs,
+    so the log survives the daemon; it is read into `Lockdown.log` on the way out.
+    """
+    docker.build(PROXY_DIR, tags=PROXY_IMAGE, file=PROXY_DIR / "Dockerfile", progress=False)
+
+    run_id = uuid4().hex[:12]
+    proxy_name = f"botbox-proxy-{run_id}"
+    url = f"http://{proxy_name}:{PROXY_PORT}"
+    jail = Lockdown(
+        network=f"botbox-jail-{run_id}",
+        envs={
+            "HTTP_PROXY": url,
+            "HTTPS_PROXY": url,
+            "http_proxy": url,
+            "https_proxy": url,
+            "NO_PROXY": "localhost,127.0.0.1",
+        },
+    )
+    egress = f"botbox-egress-{run_id}"
+
+    allowlist = scratch / "filter"
+    allowlist.write_text("".join(f"^{re.escape(host)}$\n" for host in allow))
+    allowlist.chmod(0o644)
+    # The proxy runs as its own user with no capabilities: it needs the bits to write here.
+    log_dir = scratch / "proxy"
+    log_dir.mkdir()
+    log_dir.chmod(0o755)
+    log = log_dir / "tinyproxy.log"
+    log.touch()
+    log.chmod(0o666)
+
+    proxy = None
+    networks = []
+    try:
+        # python-on-whales' network.create wraps no --internal, and --internal is the point.
+        docker_utils.run(
+            [*docker.network.docker_cmd, "network", "create", "--internal", jail.network]
+        )
+        networks.append(jail.network)
+        docker.network.create(egress)
+        networks.append(egress)
+        proxy = docker.run(
+            PROXY_IMAGE,
+            detach=True,
+            name=proxy_name,
+            networks=[egress],
+            volumes=[
+                (str(allowlist), "/etc/tinyproxy/filter", "ro"),
+                (str(log_dir), PROXY_LOG_DIR, "rw"),
+            ],
+            cap_drop=["ALL"],
+            security_options=["no-new-privileges"],
+        )
+        docker.network.connect(jail.network, proxy)
+        yield jail
+    finally:
+        gone = False
+        if proxy is not None:
+            with suppress(DockerException):
+                docker.container.remove(proxy, force=True)
+                gone = True
+        for network in networks:
+            if proxy is not None and not gone:
+                with suppress(DockerException):
+                    docker.network.disconnect(network, proxy, force=True)
+            with suppress(DockerException):
+                docker.network.remove(network)
+        jail.log = log.read_text()

{botbox-0.0.2 → botbox-0.0.4}/src/botbox/proxy/tinyproxy.conf

@@ -7,6 +7,8 @@ MaxClients 100
 
 # Notice carries the refusals, which are the only evidence an allowlist entry is argued from.
 LogLevel Info
+# A bind-mounted host directory: the log survives the daemon.
+LogFile "/var/log/tinyproxy/tinyproxy.log"
 
 ConnectPort 443
 

botbox-0.0.2/src/botbox/Botbox.py

@@ -1,38 +0,0 @@
-import hashlib
-from collections.abc import Sequence
-from pathlib import Path
-
-from python_on_whales import docker
-
-from botbox.agents.agent import Agent
-
-
-class Botbox:
-    """An agent, an optional image layer on top of it, and the extra hosts its proxy admits."""
-
-    def __init__(
-        self,
-        agent: Agent,
-        *,
-        dockerfile: str | Path | None = None,
-        allow: Sequence[str] = (),
-    ) -> None:
-        self.agent = agent
-        self.dockerfile = None if dockerfile is None else Path(dockerfile).resolve()
-        self.allow = tuple(allow)
-
-    def build(self) -> str:
-        """Build the agent's image, then `dockerfile` on top, and return the final tag.
-
-        Built on every call; Docker's layer cache keeps an unchanged build fast.
-        """
-        agent_dockerfile = self.agent.dockerfile
-        docker.build(
-            agent_dockerfile.parent, tags=self.agent.image, file=agent_dockerfile, progress=False
-        )
-        if self.dockerfile is None:
-            return self.agent.image
-        digest = hashlib.sha256(str(self.dockerfile).encode()).hexdigest()[:12]
-        tag = f"{self.agent.image.split(':')[0]}-{digest}:latest"
-        docker.build(self.dockerfile.parent, tags=tag, file=self.dockerfile, progress=False)
-        return tag