feat(macos): run containers inside a bottle via guest-local podman

Adds the `nested_containers` bottle flag. On the macOS backend it starts
a rootless podman service inside the bottle and exposes its
Docker-compatible API socket, so the agent still runs `docker` and
`docker compose`. No host daemon socket is mounted and the guest gains
no capabilities; backends that cannot run a guest-local engine reject
the flag in the shared prepare template rather than ignoring it.

Podman rather than rootless Docker because Apple Container's capability
bounding set omits CAP_SYS_ADMIN, which the kernel requires to write a
multi-range uid_map via newuidmap. With no subordinate UID range podman
falls back to a single-UID self-mapping an unprivileged process may
write itself, so the image build strips /etc/subuid and /etc/subgid
entries rather than adding them.

That mapping is also why nested containers are not an isolation layer:
root inside one is the agent user outside it. They are a build/test
convenience; the bottle remains the boundary.

Ports the spike branch onto main, renaming docker_access — it implied
Docker and granted access to nothing on the host — and drops podman
from the derived layer now that every built-in image ships it (#451).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

bot_bottle/backend/__init__.py

@@ -302,6 +302,11 @@ class BottleBackend(ABC, Generic[PlanT, CleanupT]):
 
     name: str
 
+    # Whether this backend can run a container engine *inside* the bottle.
+    # Backends that cannot must reject `nested_containers: true` rather than
+    # reach for a host daemon socket (issue #392).
+    supports_nested_containers: bool = False
+
     def prepare(self, spec: BottleSpec, stage_dir: Path) -> PlanT:
         """Template method: run cross-backend host-side validation, then
         delegate to the subclass's `_resolve_plan` for the
@@ -315,12 +320,16 @@ class BottleBackend(ABC, Generic[PlanT, CleanupT]):
             prepare_egress,
             prepare_git_gate,
             prepare_supervise,
+            reject_nested_containers,
             resolve_manifest_dockerfile,
             write_launch_metadata,
         )
 
         manifest = self._validate(spec)
 
+        if not self.supports_nested_containers:
+            reject_nested_containers(self.name, manifest)
+
         self._preflight()
 
         from ..git_gate_host_key import preflight_host_keys

bot_bottle/backend/macos_container/backend.py

@@ -31,6 +31,7 @@ class MacosContainerBottleBackend(
     `--backend=macos-container`."""
 
     name = "macos-container"
+    supports_nested_containers = True
 
     @classmethod
     def is_available(cls) -> bool:

bot_bottle/backend/macos_container/bottle_plan.py

@@ -20,6 +20,9 @@ class MacosContainerBottlePlan(BottlePlan):
     # bottle is registered. See launch.py's stamp for why it lives here and not
     # only in the exec-time proxy env.
     identity_token: str = ""
+    # Guest-local container engine (issue #392). Gates the derived image, the
+    # device-mode relaxation, and the resident podman service.
+    nested_containers: bool = False
 
     @property
     def container_name(self) -> str:

bot_bottle/backend/macos_container/launch.py

@@ -66,6 +66,7 @@ from .gateway_hosts import (
     refresh_gateway_host,
     set_gateway_host,
 )
+from . import nested_containers as nested_containers_mod
 from .bottle_plan import MacosContainerBottlePlan
 from ...orchestrator.config_store import resolve_teardown_timeout
 from .consolidated_launch import (
@@ -82,10 +83,14 @@ _AGENT_SLEEP_SECONDS = "2147483647"
 def build_or_load_images(plan: MacosContainerBottlePlan) -> BottleImages:
     """Resolve the agent image ref for this plan. The gateway's own image is
     built by `ensure_gateway` — it belongs to the shared singleton."""
+    return BottleImages(agent=_layer_nested_containers(plan, _agent_image(plan)))
+
+
+def _agent_image(plan: MacosContainerBottlePlan) -> str:
     committed = read_committed_image(plan.slug)
     if committed and container_mod.image_exists(committed):
         info(f"using committed image {committed!r}")
-        return BottleImages(agent=committed)
+        return committed
     if plan.spec.image_policy == "cached":
         if not container_mod.image_exists(plan.image):
             die(
@@ -93,9 +98,31 @@ def build_or_load_images(plan: MacosContainerBottlePlan) -> BottleImages:
                 "run without --cached-images to build it"
             )
         info(f"using cached agent image {plan.image!r}")
-        return BottleImages(agent=plan.image)
+        return plan.image
     container_mod.build_image(plan.image, _REPO_DIR, dockerfile=plan.dockerfile_path)
-    return BottleImages(agent=plan.image)
+    return plan.image
+
+
+def _layer_nested_containers(
+    plan: MacosContainerBottlePlan, agent_image: str,
+) -> str:
+    """Add the guest-local container tooling on top of the agent image.
+
+    A separate derived tag, not the provider Dockerfile, so bottles that never
+    ask for nested containers carry none of its weight.
+    """
+    if not plan.nested_containers:
+        return agent_image
+    derived = f"{agent_image}{nested_containers_mod.IMAGE_SUFFIX}"
+    if plan.spec.image_policy == "cached":
+        if not container_mod.image_exists(derived):
+            die(
+                f"cached nested-container image {derived!r} not found; "
+                "run without --cached-images to build it"
+            )
+        info(f"using cached nested-container image {derived!r}")
+        return derived
+    return nested_containers_mod.build_image(agent_image, container_mod.build_image)
 
 
 @contextmanager
@@ -196,6 +223,10 @@ def launch(
         # token above, so — unlike the run-time env — the plan CAN carry it.
         plan = dataclasses.replace(plan, identity_token=ctx.identity_token)
 
+        exec_env = {
+            **_identity_proxy_env(endpoint, ctx.identity_token),
+            **nested_containers_mod.guest_env(plan.nested_containers),
+        }
         bottle = MacosContainerBottle(
             plan.container_name,
             teardown,
@@ -209,10 +240,16 @@ def launch(
             ),
             terminal_color=plan.spec.color,
             agent_workdir=plan.workspace_plan.workdir,
-            exec_env=_identity_proxy_env(endpoint, ctx.identity_token),
+            exec_env=exec_env,
         )
         bottle.prompt_path = provision(plan, bottle)
 
+        if plan.nested_containers:
+            nested_containers_mod.prepare_guest_devices(
+                plan.container_name, container_mod.exec_container_as_root,
+            )
+            nested_containers_mod.start(bottle)
+
         yield bottle
     finally:
         teardown()

bot_bottle/backend/macos_container/nested-containers-init.sh

@@ -0,0 +1,89 @@
+#!/bin/sh
+set -eu
+
+uid="$(id -u)"
+if [ "$uid" -eq 0 ]; then
+    echo "refusing to run the guest container engine as root" >&2
+    exit 1
+fi
+
+for command in podman docker fuse-overlayfs slirp4netns; do
+    command -v "$command" >/dev/null 2>&1 || {
+        echo "missing nested-container prerequisite: $command" >&2
+        exit 1
+    }
+done
+
+# The inverse of the rootless-Docker check, and the whole point of the podman
+# variant: a subordinate range would push podman onto newuidmap, which cannot
+# write a multi-range uid_map without CAP_SYS_ADMIN in this guest.  An empty
+# range keeps it on the single-UID self-mapping an unprivileged process may
+# write itself.
+if grep -q "^$(id -un):" /etc/subuid 2>/dev/null; then
+    echo "unexpected subordinate UID range for $(id -un): podman would" >&2
+    echo "require CAP_SYS_ADMIN via newuidmap in this guest" >&2
+    exit 1
+fi
+
+for device in /dev/fuse /dev/net/tun; do
+    [ -r "$device" ] && [ -w "$device" ] || {
+        echo "device $device is not readable/writable by $(id -un)" >&2
+        exit 1
+    }
+done
+
+export XDG_RUNTIME_DIR="${XDG_RUNTIME_DIR:-/tmp/bot-bottle-podman-run}"
+config="$HOME/.config/containers"
+mkdir -p "$XDG_RUNTIME_DIR" "$config"
+chmod 700 "$XDG_RUNTIME_DIR"
+
+# ignore_chown_errors is required, not incidental: with a single-UID mapping
+# there is no second UID for image layers to be chowned to, so layers that
+# record other owners would otherwise fail to extract.
+cat > "$config/storage.conf" <<'CONF'
+[storage]
+driver="overlay"
+[storage.options.overlay]
+mount_program="/usr/bin/fuse-overlayfs"
+ignore_chown_errors="true"
+CONF
+
+# No cgroup delegation reaches this guest, so asking podman to manage cgroups
+# fails; events_logger=file avoids the journald socket that is equally absent.
+cat > "$config/containers.conf" <<'CONF'
+[containers]
+cgroups="disabled"
+[engine]
+cgroup_manager="cgroupfs"
+events_logger="file"
+CONF
+
+# Registry pulls egress through the bottle's proxy like everything else. The
+# token-bearing proxy URL is already in the agent's environment; persisting it
+# inside this disposable VM does not broaden its authority.
+python3 - <<'PY'
+import json
+import os
+from pathlib import Path
+
+proxy = os.environ.get("HTTPS_PROXY") or os.environ.get("https_proxy", "")
+no_proxy = os.environ.get("NO_PROXY") or os.environ.get("no_proxy", "")
+config = {"proxies": {"default": {
+    "httpProxy": proxy,
+    "httpsProxy": proxy,
+    "noProxy": no_proxy,
+}}}
+path = Path.home() / ".docker" / "config.json"
+path.parent.mkdir(parents=True, exist_ok=True)
+path.write_text(json.dumps(config), encoding="utf-8")
+path.chmod(0o600)
+PY
+
+if docker info >/dev/null 2>&1; then
+    exit 0
+fi
+
+log=/tmp/bot-bottle-nested-containers.log
+nohup podman system service --time=0 \
+    "unix://$XDG_RUNTIME_DIR/podman.sock" \
+    >"$log" 2>&1 </dev/null &

bot_bottle/backend/macos_container/nested_containers.py

@@ -0,0 +1,143 @@
+"""Guest-local container engine for Apple-container bottles (issue #392).
+
+The service and every nested container remain inside the existing per-bottle
+VM.  This module refuses to compensate for missing prerequisites with outer
+capabilities, a privileged container, or a host Docker socket.
+
+Podman is used rather than rootless Docker for one specific reason: Apple
+Container's capability bounding set omits `CAP_SYS_ADMIN`, which the kernel
+requires to write a multi-range `uid_map` via `newuidmap`.  Rootless Docker
+has no path that avoids that write.  Podman does — with no subordinate UID
+range configured it falls back to a single-UID self-mapping, which an
+unprivileged process may write itself.  See
+`docs/research/rootless-docker-in-apple-container-spike.md`.
+
+That fallback is why `build_image` *removes* the agent user's `/etc/subuid`
+and `/etc/subgid` entries instead of adding them: their presence is precisely
+what would send podman down the `newuidmap` path that cannot work here.
+
+The agent still talks to `docker` and `docker compose`; those speak to
+podman's Docker-compatible API socket, so nothing in the agent's habits
+changes.
+
+Nested containers run *within* the bottle boundary, not inside a new one: the
+single-UID mapping means `root` in a nested container is the agent user
+outside it.  This is for build and test workloads, not for sandboxing
+untrusted code.
+"""
+
+from __future__ import annotations
+
+import shlex
+import shutil
+import tempfile
+import time
+from pathlib import Path
+from typing import Callable
+
+from ...log import die, info
+
+_INIT = "/usr/local/libexec/bot-bottle/nested-containers-init"
+_RUNTIME_DIR = "/tmp/bot-bottle-podman-run"
+_SOCKET = f"{_RUNTIME_DIR}/podman.sock"
+_LOG = "/tmp/bot-bottle-nested-containers.log"
+IMAGE_SUFFIX = "-nested-containers"
+READY_RETRIES = 30
+
+# Apple Container creates both device nodes 0600 root:root, so the agent user
+# cannot open them: /dev/fuse blocks the fuse-overlayfs storage driver and
+# /dev/net/tun blocks slirp4netns, which rootless podman uses for the default
+# bridge network that stock compose files expect.  Relaxing the modes needs no
+# capability the bottle does not already hold — unlike CAP_SYS_ADMIN, which is
+# what killed the rootless-Docker approach.
+_GUEST_DEVICES = ("/dev/fuse", "/dev/net/tun")
+
+
+def build_image(
+    base_image: str,
+    build: Callable[..., None],
+) -> str:
+    """Layer the nested-container tooling onto an already-built agent image.
+
+    Only what the flag is meant to gate lands here.  Podman itself is already
+    in every built-in agent image (issue #451); the storage/network helpers,
+    the Docker CLI, and the compose plugin are the ~100MB this flag buys.
+    """
+    image = f"{base_image}{IMAGE_SUFFIX}"
+    init_script = Path(__file__).with_name("nested-containers-init.sh")
+    with tempfile.TemporaryDirectory(prefix="bot-bottle-nested-containers.") as tmp:
+        context = Path(tmp)
+        shutil.copy2(init_script, context / "nested-containers-init.sh")
+        (context / "Dockerfile").write_text(
+            "FROM docker:28-cli AS docker_cli\n"
+            f"FROM {base_image}\n"
+            "USER root\n"
+            "COPY --from=docker_cli /usr/local/bin/docker /usr/local/bin/docker\n"
+            "COPY --from=docker_cli /usr/local/libexec/docker/cli-plugins/"
+            "docker-compose /usr/local/libexec/docker/cli-plugins/docker-compose\n"
+            "RUN apt-get update \\\n"
+            " && apt-get install -y --no-install-recommends "
+            "fuse-overlayfs slirp4netns uidmap \\\n"
+            " && rm -rf /var/lib/apt/lists/* \\\n"
+            # Deliberate: an empty subordinate range keeps podman on the
+            # single-UID mapping that needs no CAP_SYS_ADMIN.  Adding ranges
+            # here would reintroduce the newuidmap failure this design exists
+            # to route around.
+            " && sed -i '/^node:/d' /etc/subuid /etc/subgid\n"
+            "COPY nested-containers-init.sh "
+            "/usr/local/libexec/bot-bottle/nested-containers-init\n"
+            "RUN chmod 0755 /usr/local/libexec/bot-bottle/nested-containers-init\n"
+            "USER node\n",
+            encoding="utf-8",
+        )
+        build(image, str(context), dockerfile=str(context / "Dockerfile"))
+    return image
+
+
+def guest_env(enabled: bool) -> dict[str, str]:
+    """Environment consumed by the Docker CLI inside an enabled bottle."""
+    if not enabled:
+        return {}
+    return {
+        "DOCKER_HOST": f"unix://{_SOCKET}",
+        "XDG_RUNTIME_DIR": _RUNTIME_DIR,
+    }
+
+
+def prepare_guest_devices(container_name: str, exec_as_root: Callable[..., None]) -> None:
+    """Make /dev/fuse and /dev/net/tun openable by the agent user.
+
+    Runs as root inside the bottle because the agent must not be able to
+    re-mode device nodes itself.  No outer capability is involved.
+    """
+    exec_as_root(
+        container_name,
+        ["sh", "-c", f"chmod 0666 {' '.join(_GUEST_DEVICES)}"],
+    )
+
+
+def start(bottle: object) -> None:
+    """Start and verify the unprivileged service through the bottle exec API."""
+    info("starting guest-local container engine")
+    result = bottle.exec(shlex.quote(_INIT))  # type: ignore[attr-defined]
+    if result.returncode != 0:
+        detail = (result.stderr or result.stdout or "").strip()
+        die(f"nested-container bootstrap failed: {detail or '<no output>'}")
+
+    for _ in range(READY_RETRIES):
+        result = bottle.exec("docker info >/dev/null 2>&1")  # type: ignore[attr-defined]
+        if result.returncode == 0:
+            info("guest-local container engine is ready")
+            return
+        time.sleep(0.2)
+
+    logs = bottle.exec(  # type: ignore[attr-defined]
+        f"tail -n 80 {_LOG} 2>/dev/null || true"
+    )
+    die(
+        "guest-local container engine did not become ready without additional "
+        f"outer privileges:\n{(logs.stdout or logs.stderr or '<no log>').strip()}"
+    )
+
+
+__all__ = ["build_image", "guest_env", "prepare_guest_devices", "start"]

bot_bottle/backend/macos_container/resolve_plan.py

@@ -44,4 +44,5 @@ def resolve_plan(
         egress_plan=egress_plan,
         supervise_plan=supervise_plan,
         agent_provision=agent_provision_plan,
+        nested_containers=manifest.bottle.nested_containers,
     )

bot_bottle/backend/resolve_common.py

@@ -26,6 +26,7 @@ from ..bottle_state import (
 )
 from ..egress import Egress, EgressPlan
 from ..git_gate import GitGate, GitGatePlan
+from ..log import die
 from ..manifest import Manifest, ManifestBottle
 from ..supervise import Supervise, SupervisePlan
 from . import BottleSpec
@@ -112,6 +113,22 @@ def merge_provision_env_vars(provision: AgentProvisionPlan) -> AgentProvisionPla
     return replace(provision, guest_env=merged)
 
 
+def reject_nested_containers(backend: str, manifest: Manifest) -> None:
+    """Fail loudly when a backend cannot honor `nested_containers: true`.
+
+    Silently ignoring it would hand the agent a bottle where `docker` is not
+    there — and the only sound alternatives on these backends (a host daemon
+    socket, a privileged container) are exactly what issue #392 rules out.
+    """
+    if not manifest.bottle.nested_containers:
+        return
+    die(
+        f"nested_containers is not supported on the {backend} backend. "
+        "Only macos-container runs a guest-local container engine today; "
+        "mounting the host Docker socket is not an option bot-bottle offers."
+    )
+
+
 def resolve_manifest_dockerfile(path_value: str, spec: BottleSpec) -> str:
     """Resolve a manifest-supplied dockerfile path relative to user_cwd."""
     path = Path(os.path.expanduser(path_value))
@@ -122,6 +139,7 @@ def resolve_manifest_dockerfile(path_value: str, spec: BottleSpec) -> str:
 
 __all__ = [
     "merge_provision_env_vars",
+    "reject_nested_containers",
     "mint_slug",
     "prepare_agent_state_dir",
     "prepare_egress",