test(macos): cover rootless image launch wiring

Add an opt-in docker_access path that layers rootless Docker tooling onto the selected agent image, starts the daemon only after registration, and retains the existing outer network and capability boundary. Include fail-closed bootstrap checks plus a live-Mac Compose/security acceptance test.\n\nRefs #392.

Dockerfile.infra

@@ -1,22 +1,45 @@
-# Shared infra image: gateway data plane + orchestrator control plane.
+# Firecracker single infra-VM image (PRD 0070 Stage B).
 #
-# Used directly by the Docker backend (run as one `bot-bottle-infra`
-# container, replacing the prior two-container split). The Firecracker
-# backend extends this via Dockerfile.infra.fc, adding buildah/crun/
-# netavark for in-VM agent-image building.
-#
-# Dockerfile.orchestrator is the single definition of the orchestrator
-# content (the lean `bot_bottle` package on python:3.12-slim). Both this
-# image and Dockerfile.infra.fc pull it in via `COPY --from`.
+# The per-host infra VM runs the orchestrator control plane, the gateway
+# data plane, AND builds agent images (buildah) — all in one microVM (see
+# backend/firecracker/infra_vm.py). It composes:
+#   * FROM the gateway image (mitmproxy / git / gitleaks / supervise + the
+#     flat daemon modules) — now trixie-based, so buildah 1.39 is available;
+#   * `COPY --from` the orchestrator image's content (the single definition
+#     of the control-plane payload — see Dockerfile.orchestrator), so this
+#     VM and the docker backend share one orchestrator definition; and
+#   * buildah, installed HERE only (the docker orchestrator/gateway images
+#     never carry it).
 #
 # multi-`FROM` can't union two bases (that's multi-stage, not multiple
 # inheritance), so the orchestrator content is pulled in via `COPY --from`
 # rather than a second base. Both images share the trixie `python:3.12-slim`
 # base, so the copy is clean (same python; future installed deps copy too).
+#
+# The docker backend keeps orchestrator + gateway as separate images; this
+# combined image exists only for the Firecracker single-VM cut. Splitting a
+# service back into its own VM later is a routing change, not a repackaging
+# (PRD 0070's "secret concentration"; a disposable builder can boot from
+# this same image on its own TAP).
 FROM bot-bottle-gateway:latest
 
-# The orchestrator content, from its single definition. The gateway image
-# already has the flat daemon modules under /app; this adds the full
-# `bot_bottle` package so `python3 -m bot_bottle.orchestrator` resolves —
-# used by gateway_init when BOT_BOTTLE_GATEWAY_DAEMONS includes `orchestrator`.
+# --- in-VM agent-image builder (PRD 0069 Stage 3) -------------------
+# The Firecracker backend builds users' agent Dockerfiles *inside this VM*
+# with buildah (rootless, daemonless) instead of on the host — no host
+# Docker daemon, no root-equivalent `docker` group. `crun` is the OCI
+# runtime; `netavark` + `aardvark-dns` are the network backend for `FROM`
+# pulls + `RUN` egress. Requires the trixie base (buildah 1.39: bookworm's
+# 1.28 can't parse Dockerfile heredocs that agent images use).
+RUN apt-get update \
+ && apt-get install -y --no-install-recommends \
+      buildah crun netavark aardvark-dns \
+ && rm -rf /var/lib/apt/lists/*
+# vfs + chroot: buildah works as root in the bare microVM (no
+# fuse-overlayfs / overlay module / subuid maps). Matches image_builder.
+ENV STORAGE_DRIVER=vfs \
+    BUILDAH_ISOLATION=chroot
+
+# The orchestrator content, pulled from its single definition. The gateway
+# image already has the flat daemon modules under /app; this adds the full
+# `bot_bottle` package so `python3 -m bot_bottle.orchestrator` resolves.
 COPY --from=bot-bottle-orchestrator:latest /app/bot_bottle /app/bot_bottle

Dockerfile.infra.fc

@@ -1,23 +0,0 @@
-# Firecracker infra VM image (PRD 0070 Stage B).
-#
-# Extends the shared infra base (Dockerfile.infra: gateway + orchestrator
-# control plane) with the in-VM agent-image builder. The Firecracker backend
-# builds users' agent Dockerfiles *inside this VM* with buildah (rootless,
-# daemonless) instead of on the host — no host Docker daemon, no
-# root-equivalent `docker` group.
-#
-# Requires the trixie base from bot-bottle-gateway (buildah 1.39: bookworm's
-# 1.28 can't parse Dockerfile heredocs that agent images use).
-#
-# `crun` is the OCI runtime; `netavark` + `aardvark-dns` are the network
-# backend for `FROM` pulls + `RUN` egress. `vfs` + `chroot`: buildah works
-# as root in the bare microVM (no fuse-overlayfs / overlay module / subuid
-# maps). Matches image_builder.
-FROM bot-bottle-infra:latest
-
-RUN apt-get update \
- && apt-get install -y --no-install-recommends \
-      buildah crun netavark aardvark-dns \
- && rm -rf /var/lib/apt/lists/*
-ENV STORAGE_DRIVER=vfs \
-    BUILDAH_ISOLATION=chroot

README.md

@@ -75,6 +75,14 @@ On compatible macOS hosts, the default backend requires Apple's `container` CLI
 
 Use `BOT_BOTTLE_BACKEND=docker ./cli.py start <agent>` on hosts where neither Apple Container nor KVM is available and Docker is the desired backend.
 
+> **Experimental Docker-in-bottle spike (#392):** a bottle may set
+> `docker_access: true`. On the macOS backend this starts a guest-local,
+> rootless Docker daemon after the bottle is registered. It does not mount
+> Docker Desktop's socket or add outer VM capabilities. The spike currently
+> requires live-macOS validation before it is considered supported; startup
+> fails closed when the Apple guest kernel cannot satisfy rootless Docker's
+> user-namespace requirements.
+
 ### Firecracker on Linux
 
 On Linux, a KVM-capable host defaults to the Firecracker backend. It needs:

bot_bottle/agent_provider.py

@@ -45,10 +45,6 @@ PROVIDER_TEMPLATES = frozenset({PROVIDER_CLAUDE, PROVIDER_CODEX, PROVIDER_PI})
 # forward_host_credentials is enabled. Pipelock must pass these through
 # (no TLS MITM) or its header DLP blocks the injected JWT.
 CODEX_HOST_CREDENTIAL_HOSTS = ("api.openai.com", "chatgpt.com")
-
-# Host that egress injects the host Claude bearer on when Claude
-# forward_host_credentials is enabled.
-CLAUDE_HOST_CREDENTIAL_HOSTS = ("api.anthropic.com",)
 PromptMode = Literal[
     "append_file",
     "read_prompt_file",

bot_bottle/backend/consolidated_util.py

@@ -1,60 +0,0 @@
-"""Shared helpers for the consolidated launch sequence (PRD 0070).
-
-Logic that was duplicated across the docker, macos_container, and
-firecracker consolidated_launch modules — extracted so each backend
-imports it rather than re-implementing it.
-"""
-
-from __future__ import annotations
-
-from ..egress import EgressPlan
-from ..git_gate import GitGatePlan
-from ..orchestrator.client import OrchestratorClient
-from ..orchestrator.registration import registration_inputs
-from .docker.gateway_provision import GatewayTransport, deprovision_git_gate, provision_git_gate
-
-
-def provision_bottle(
-    client: OrchestratorClient,
-    source_ip: str,
-    egress_plan: EgressPlan,
-    git_gate_plan: GitGatePlan,
-    transport: GatewayTransport,
-    *,
-    image_ref: str = "",
-    tokens: dict[str, str] | None = None,
-):
-    """Register the bottle and provision its git-gate state. Rolls back the
-    registration if provisioning fails so no orphan is left. Returns the
-    `RegisteredBottle` from the orchestrator."""
-    inputs = registration_inputs(egress_plan)
-    reg = client.register_bottle(
-        source_ip, image_ref=image_ref, policy=inputs.policy,
-        metadata=inputs.metadata, tokens=tokens,
-    )
-    try:
-        provision_git_gate(transport, reg.bottle_id, git_gate_plan)
-    except Exception:
-        client.teardown_bottle(reg.bottle_id)
-        raise
-    return reg
-
-
-def teardown_consolidated(
-    bottle_id: str,
-    transport: GatewayTransport,
-    *,
-    orchestrator_url: str,
-    timeout: float | None = None,
-) -> None:
-    """Deregister the bottle and remove its git-gate state. Both steps are
-    idempotent so this is safe from a cleanup trap."""
-    from ..orchestrator.config_store import DEFAULT_TEARDOWN_TIMEOUT_SECONDS
-    OrchestratorClient(
-        orchestrator_url,
-        timeout=timeout if timeout is not None else DEFAULT_TEARDOWN_TIMEOUT_SECONDS,
-    ).teardown_bottle(bottle_id)
-    deprovision_git_gate(transport, bottle_id)
-
-
-__all__ = ["provision_bottle", "teardown_consolidated"]

bot_bottle/backend/docker/consolidated_launch.py

@@ -1,13 +1,19 @@
 """Consolidated bottle launch sequence for the docker backend (PRD 0070).
 
-Composes the orchestrator primitives into the register/teardown sequence:
+Composes the orchestrator primitives into the register/teardown sequence that
+replaces the per-bottle gateway:
 
-  1. ensure the single infra container (control plane + gateway) is up;
-  2. allocate the bottle a pinned source IP on the gateway network;
-  3. register it and provision its git-gate repos/creds into the gateway.
+  1. ensure the orchestrator control plane + shared gateway are up;
+  2. allocate the bottle a pinned source IP on the gateway network (the
+     attribution key), skipping the gateway's own address + live bottles;
+  3. register it (egress policy blob + slug metadata) → bottle id + identity
+     token;
+  4. provision its git-gate repos/creds into the running gateway.
 
-Returns a `LaunchContext` with everything the agent container needs to
-attach. The agent `docker run` itself is the backend's job; this owns the
+It returns a `LaunchContext` with everything the agent container needs to
+attach — network, pinned IP, the gateway's address (its proxy target), the
+orchestrator URL, and the identity token. The agent `docker run` itself is
+the backend's job (it owns provider provisioning); this owns the
 orchestrator-facing wiring so that sequence stays testable in isolation.
 """
 
@@ -19,12 +25,15 @@ from ...docker_cmd import run_docker
 from ...egress import EgressPlan
 from ...git_gate import GitGatePlan
 from ...orchestrator.client import OrchestratorClient
-from ...orchestrator.gateway import GATEWAY_NETWORK
-from ...orchestrator.lifecycle import INFRA_NAME, OrchestratorService
-from ..consolidated_util import provision_bottle
-from ..consolidated_util import teardown_consolidated as _teardown_util
-from .gateway_provision import DockerGatewayTransport
+from ...orchestrator.gateway import GATEWAY_NAME, GATEWAY_NETWORK
+from ...orchestrator.lifecycle import OrchestratorService
+from ...orchestrator.registration import registration_inputs
 from .gateway_net import next_free_ip
+from .gateway_provision import (
+    DockerGatewayTransport,
+    deprovision_git_gate,
+    provision_git_gate,
+)
 
 
 class ConsolidatedLaunchError(RuntimeError):
@@ -66,21 +75,24 @@ def _container_ip(name: str, network: str) -> str:
     ip = proc.stdout.strip()
     if proc.returncode != 0 or not ip:
         raise ConsolidatedLaunchError(
-            f"container {name} has no address on {network}: {proc.stderr.strip()}"
+            f"gateway {name} has no address on {network}: {proc.stderr.strip()}"
         )
     return ip
 
 
 def _network_container_ips(network: str) -> list[str]:
     """Every address currently assigned on the gateway network — the ground
-    truth for "in use": the infra container and every live agent. Read from
-    the network so a new bottle can't collide with anything actually attached."""
+    truth for "in use": the gateway + orchestrator infrastructure containers
+    and every live agent. Read from the network so a new bottle can't collide
+    with anything actually attached (a registry-only view would miss the
+    orchestrator/gateway containers)."""
     proc = run_docker([
         "docker", "network", "inspect", "--format",
         "{{range .Containers}}{{.IPv4Address}} {{end}}", network,
     ])
     ips: list[str] = []
     for entry in proc.stdout.split():
+        # entries look like "172.20.0.2/16" — keep the address.
         ips.append(entry.split("/", 1)[0])
     return ips
 
@@ -92,24 +104,33 @@ def launch_consolidated(
     image_ref: str = "",
     tokens: dict[str, str] | None = None,
     service: OrchestratorService | None = None,
-    infra_name: str = INFRA_NAME,
+    gateway_name: str = GATEWAY_NAME,
     network: str = GATEWAY_NETWORK,
 ) -> LaunchContext:
-    """Ensure the infra container is up, allocate + register the bottle, and
-    provision its git-gate state. Returns the agent's attach context."""
+    """Ensure the orchestrator + gateway are up, allocate + register the
+    bottle, and provision its git-gate state. Returns the agent's attach
+    context. Raises `ConsolidatedLaunchError` (or the primitives' own errors)
+    if any step fails — the caller tears down on failure."""
     service = service or OrchestratorService()
     url = service.ensure_running()
     client = OrchestratorClient(url)
 
     cidr = _network_cidr(network)
-    gateway_ip = _container_ip(infra_name, network)
+    gateway_ip = _container_ip(gateway_name, network)
     source_ip = next_free_ip(cidr, _network_container_ips(network))
 
-    transport = DockerGatewayTransport(infra_name)
-    reg = provision_bottle(
-        client, source_ip, egress_plan, git_gate_plan, transport,
-        image_ref=image_ref, tokens=tokens,
+    inputs = registration_inputs(egress_plan)
+    reg = client.register_bottle(
+        source_ip, image_ref=image_ref, policy=inputs.policy,
+        metadata=inputs.metadata, tokens=tokens,
     )
+    try:
+        provision_git_gate(
+            DockerGatewayTransport(gateway_name), reg.bottle_id, git_gate_plan)
+    except Exception:
+        # Roll the registration back so a provisioning failure leaves no orphan.
+        client.teardown_bottle(reg.bottle_id)
+        raise
     return LaunchContext(
         bottle_id=reg.bottle_id,
         identity_token=reg.identity_token,
@@ -121,12 +142,20 @@ def launch_consolidated(
 
 
 def teardown_consolidated(
-    bottle_id: str, *, orchestrator_url: str, infra_name: str = INFRA_NAME,
+    bottle_id: str,
+    *,
+    orchestrator_url: str,
+    gateway_name: str = GATEWAY_NAME,
     timeout: float | None = None,
 ) -> None:
-    """Deregister the bottle and remove its git-gate state. Idempotent."""
-    _teardown_util(bottle_id, DockerGatewayTransport(infra_name),
-                   orchestrator_url=orchestrator_url, timeout=timeout)
+    """Deregister the bottle and remove its git-gate state from the gateway.
+    Both steps are idempotent so this is safe from a cleanup trap."""
+    from ...orchestrator.config_store import DEFAULT_TEARDOWN_TIMEOUT_SECONDS
+    OrchestratorClient(
+        orchestrator_url,
+        timeout=timeout if timeout is not None else DEFAULT_TEARDOWN_TIMEOUT_SECONDS,
+    ).teardown_bottle(bottle_id)
+    deprovision_git_gate(DockerGatewayTransport(gateway_name), bottle_id)
 
 
 __all__ = [

bot_bottle/backend/firecracker/consolidated_launch.py

@@ -33,7 +33,8 @@ from ...orchestrator.client import OrchestratorClient
 from ...orchestrator.lifecycle import (
     OrchestratorStartError,  # re-exported so callers can catch it
 )
-from ..consolidated_util import provision_bottle, teardown_consolidated as _teardown_util
+from ...orchestrator.registration import registration_inputs
+from ..docker.gateway_provision import deprovision_git_gate, provision_git_gate
 from . import infra_vm
 
 
@@ -67,11 +68,18 @@ def launch_consolidated(
     url = infra.control_plane_url
     client = OrchestratorClient(url)
 
-    transport = infra_vm.gateway_transport()
-    reg = provision_bottle(
-        client, guest_ip, egress_plan, git_gate_plan, transport,
-        image_ref=image_ref, tokens=tokens,
+    inputs = registration_inputs(egress_plan)
+    reg = client.register_bottle(
+        guest_ip, image_ref=image_ref, policy=inputs.policy,
+        metadata=inputs.metadata, tokens=tokens,
     )
+    try:
+        provision_git_gate(
+            infra_vm.gateway_transport(), reg.bottle_id, git_gate_plan)
+    except Exception:
+        client.teardown_bottle(reg.bottle_id)
+        raise
+
     # The shared gateway CA every agent on this host trusts for TLS
     # interception — fetched from the infra VM over SSH.
     return LaunchContext(
@@ -90,8 +98,12 @@ def teardown_consolidated(
     VM. Both steps are idempotent so this is safe from a cleanup trap. Does
     NOT stop the infra VM — it's a persistent per-host singleton shared by
     every bottle."""
-    _teardown_util(bottle_id, infra_vm.gateway_transport(),
-                   orchestrator_url=orchestrator_url, timeout=timeout)
+    from ...orchestrator.config_store import DEFAULT_TEARDOWN_TIMEOUT_SECONDS
+    OrchestratorClient(
+        orchestrator_url,
+        timeout=timeout if timeout is not None else DEFAULT_TEARDOWN_TIMEOUT_SECONDS,
+    ).teardown_bottle(bottle_id)
+    deprovision_git_gate(infra_vm.gateway_transport(), bottle_id)
 
 
 __all__ = [

bot_bottle/backend/firecracker/infra_artifact.py

@@ -41,7 +41,7 @@ from . import util
 _ARTIFACT_FORMAT = "1"
 
 _REPO_ROOT = Path(__file__).resolve().parents[3]
-_DOCKERFILES = ("Dockerfile.orchestrator", "Dockerfile.gateway", "Dockerfile.infra", "Dockerfile.infra.fc")
+_DOCKERFILES = ("Dockerfile.orchestrator", "Dockerfile.gateway", "Dockerfile.infra")
 
 _DEFAULT_BASE = "https://gitea.dideric.is"
 _DEFAULT_OWNER = "didericis"

bot_bottle/backend/firecracker/infra_vm.py

@@ -33,7 +33,6 @@ from pathlib import Path
 from typing import Generator
 
 from ...log import die, info
-from .. import util as backend_util
 from ..docker import util as docker_mod
 from ..docker.gateway_provision import GatewayProvisionError
 from . import firecracker_vm, infra_artifact, netpool, util
@@ -94,18 +93,19 @@ class InfraVm:
         """The gateway's mitmproxy CA (PEM) that agents install to trust its
         TLS interception. Generated a moment after boot, so this polls over
         SSH until it appears (mirrors DockerGateway.ca_cert_pem)."""
-        def _fetch() -> str | None:
+        deadline = time.monotonic() + timeout
+        while True:
             proc = subprocess.run(
                 util.ssh_base_argv(self.private_key, self.guest_ip)
                 + [f"cat {_GATEWAY_CA_PATH}"],
                 capture_output=True, text=True, timeout=15, check=False,
             )
-            ok = proc.returncode == 0 and "BEGIN CERTIFICATE" in proc.stdout
-            return proc.stdout if ok else None
-        try:
-            return backend_util.poll_ca_cert(_fetch, timeout=timeout)
-        except TimeoutError as exc:
-            die(str(exc))
+            if proc.returncode == 0 and "BEGIN CERTIFICATE" in proc.stdout:
+                return proc.stdout
+            if time.monotonic() >= deadline:
+                die(f"gateway CA not available after {timeout:g}s: "
+                    f"{proc.stderr.strip() or 'empty'}")
+            time.sleep(_HEALTH_POLL_SECONDS)
 
 
 def ensure_built() -> None:
@@ -125,19 +125,16 @@ def ensure_built() -> None:
 
 
 def build_infra_images_with_docker() -> None:
-    """Build the four fixed images from source with host Docker: orchestrator,
-    gateway, the shared infra base (Dockerfile.infra), then the Firecracker
-    infra image (Dockerfile.infra.fc: FROM infra + buildah). The launch host
-    uses this only in `BOT_BOTTLE_INFRA_BUILD=local` mode; `publish_infra`
-    uses it off-host to produce the published artifact."""
+    """Build the three fixed images from source with host Docker: orchestrator,
+    gateway, then the combined infra image (`COPY --from` orchestrator, `FROM`
+    gateway). The launch host uses this only in `BOT_BOTTLE_INFRA_BUILD=local`
+    mode; `publish_infra` uses it off-host to produce the published artifact."""
     docker_mod.build_image(
         _ORCHESTRATOR_IMAGE, str(_REPO_ROOT), dockerfile="Dockerfile.orchestrator")
     docker_mod.build_image(
         _GATEWAY_IMAGE, str(_REPO_ROOT), dockerfile="Dockerfile.gateway")
     docker_mod.build_image(
-        "bot-bottle-infra:latest", str(_REPO_ROOT), dockerfile="Dockerfile.infra")
-    docker_mod.build_image(
-        _INFRA_IMAGE, str(_REPO_ROOT), dockerfile="Dockerfile.infra.fc")
+        _INFRA_IMAGE, str(_REPO_ROOT), dockerfile="Dockerfile.infra")
 
 
 def build_infra_rootfs_dir() -> Path:

bot_bottle/backend/macos_container/bottle_plan.py

@@ -20,6 +20,7 @@ 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 = ""
+    docker_access: bool = False
 
     @property
     def container_name(self) -> str:

bot_bottle/backend/macos_container/consolidated_launch.py

@@ -38,7 +38,8 @@ from ...egress import EgressPlan
 from ...git_gate import GitGatePlan
 from ...log import info
 from ...orchestrator.client import OrchestratorClient, OrchestratorClientError
-from ..consolidated_util import provision_bottle, teardown_consolidated as _teardown_util
+from ...orchestrator.registration import registration_inputs
+from ..docker.gateway_provision import deprovision_git_gate, provision_git_gate
 from . import util as container_mod
 from .enumerate import CONTAINER_NAME_PREFIX, EnumerationError, enumerate_active
 from .gateway import GATEWAY_NETWORK
@@ -141,10 +142,17 @@ def register_agent(
         client.reconcile(live_source_ips(endpoint.network))
     except (OrchestratorClientError, EnumerationError) as e:
         info(f"registry reconciliation skipped: {e}")
-    reg = provision_bottle(
-        client, source_ip, egress_plan, git_gate_plan, AppleGatewayTransport(),
-        image_ref=image_ref, tokens=tokens,
+    inputs = registration_inputs(egress_plan)
+    reg = client.register_bottle(
+        source_ip, image_ref=image_ref, policy=inputs.policy,
+        metadata=inputs.metadata, tokens=tokens,
     )
+    try:
+        provision_git_gate(AppleGatewayTransport(), reg.bottle_id, git_gate_plan)
+    except Exception:
+        # Roll the registration back so a provisioning failure leaves no orphan.
+        client.teardown_bottle(reg.bottle_id)
+        raise
     return LaunchContext(
         bottle_id=reg.bottle_id,
         identity_token=reg.identity_token,
@@ -161,8 +169,12 @@ def teardown_consolidated(
     """Deregister the bottle and remove its git-gate state from the gateway.
     Both steps are idempotent so this is safe from a cleanup trap. Does NOT
     stop the gateway — it's a persistent per-host singleton."""
-    _teardown_util(bottle_id, AppleGatewayTransport(),
-                   orchestrator_url=orchestrator_url, timeout=timeout)
+    from ...orchestrator.config_store import DEFAULT_TEARDOWN_TIMEOUT_SECONDS
+    OrchestratorClient(
+        orchestrator_url,
+        timeout=timeout if timeout is not None else DEFAULT_TEARDOWN_TIMEOUT_SECONDS,
+    ).teardown_bottle(bottle_id)
+    deprovision_git_gate(AppleGatewayTransport(), bottle_id)
 
 
 __all__ = [

bot_bottle/backend/macos_container/infra.py

@@ -53,7 +53,6 @@ from ...paths import (
     HOST_DB_FILENAME,
     host_control_plane_token,
 )
-from .. import util as backend_util
 from . import util as container_mod
 from .gateway import (
     DEFAULT_CA_TIMEOUT_SECONDS,
@@ -264,16 +263,18 @@ class MacosInfraService:
         interception. Read out of the container (the CA lives on a
         container-internal path, not a host mount); polls because mitmproxy
         writes it a beat after start."""
-        def _fetch() -> str | None:
+        deadline = time.monotonic() + timeout
+        while True:
             result = container_mod.run_container_argv(
                 ["container", "exec", self._name, "cat", GATEWAY_CA_CERT])
-            return result.stdout if result.returncode == 0 and result.stdout.strip() else None
-        try:
-            return backend_util.poll_ca_cert(_fetch, timeout=timeout)
-        except TimeoutError as exc:
-            raise GatewayError(
-                f"gateway CA not available in {self._name} after {timeout:g}s"
-            ) from exc
+            if result.returncode == 0 and result.stdout.strip():
+                return result.stdout
+            if time.monotonic() >= deadline:
+                raise GatewayError(
+                    f"gateway CA not available in {self._name} after {timeout:g}s: "
+                    f"{(result.stderr or '').strip() or 'empty'}"
+                )
+            time.sleep(_CA_POLL_SECONDS)
 
     def stop(self) -> None:
         """Remove the infra container (idempotent). The DB volume persists."""

bot_bottle/backend/macos_container/launch.py

@@ -64,6 +64,7 @@ from .gateway_hosts import (
     refresh_gateway_host,
     set_gateway_host,
 )
+from . import rootless_docker
 from .bottle_plan import MacosContainerBottlePlan
 from ...orchestrator.config_store import resolve_teardown_timeout
 from .consolidated_launch import (
@@ -171,6 +172,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),
+            **rootless_docker.guest_env(plan.docker_access),
+        }
         bottle = MacosContainerBottle(
             plan.container_name,
             teardown,
@@ -184,10 +189,13 @@ 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.docker_access:
+            rootless_docker.start(bottle)
+
         yield bottle
     finally:
         teardown()
@@ -199,15 +207,22 @@ def _build_images(plan: MacosContainerBottlePlan) -> MacosContainerBottlePlan:
     committed = read_committed_image(plan.slug)
     if committed and container_mod.image_exists(committed):
         info(f"using committed image {committed!r}")
-        return dataclasses.replace(
+        plan = dataclasses.replace(
             plan,
             agent_provision=dataclasses.replace(
                 plan.agent_provision, image=committed,
             ),
         )
-    container_mod.build_image(
-        plan.image, _REPO_DIR, dockerfile=plan.dockerfile_path,
-    )
+    else:
+        container_mod.build_image(
+            plan.image, _REPO_DIR, dockerfile=plan.dockerfile_path,
+        )
+    if plan.docker_access:
+        image = rootless_docker.build_image(plan.image, container_mod.build_image)
+        plan = dataclasses.replace(
+            plan,
+            agent_provision=dataclasses.replace(plan.agent_provision, image=image),
+        )
     return plan
 
 

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,
+        docker_access=manifest.bottle.docker_access,
     )

bot_bottle/backend/macos_container/rootless-docker-init.sh

@@ -0,0 +1,57 @@
+#!/bin/sh
+set -eu
+
+uid="$(id -u)"
+if [ "$uid" -eq 0 ]; then
+    echo "refusing to run rootless Docker as root" >&2
+    exit 1
+fi
+
+for command in dockerd-rootless.sh rootlesskit slirp4netns newuidmap newgidmap docker; do
+    command -v "$command" >/dev/null 2>&1 || {
+        echo "missing rootless Docker prerequisite: $command" >&2
+        exit 1
+    }
+done
+
+grep -q "^$(id -un):.*:65536$" /etc/subuid || {
+    echo "missing 65536-entry subordinate UID range for $(id -un)" >&2
+    exit 1
+}
+grep -q "^$(id -gn):.*:65536$" /etc/subgid || {
+    echo "missing 65536-entry subordinate GID range for $(id -gn)" >&2
+    exit 1
+}
+
+export XDG_RUNTIME_DIR="${XDG_RUNTIME_DIR:-/tmp/bot-bottle-docker-run}"
+mkdir -p "$XDG_RUNTIME_DIR" "$HOME/.docker"
+chmod 700 "$XDG_RUNTIME_DIR"
+
+# Docker uses this config for build and child-container proxy injection.  The
+# token-bearing proxy URL is already available to the agent; 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.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-rootless-docker.log
+nohup dockerd-rootless.sh \
+    --storage-driver=fuse-overlayfs \
+    >"$log" 2>&1 </dev/null &

bot_bottle/backend/macos_container/rootless_docker.py

@@ -0,0 +1,94 @@
+"""Experimental rootless Docker bootstrap for Apple-container bottles.
+
+The daemon and every child remain inside the existing per-bottle VM.  This
+module deliberately refuses to compensate for missing prerequisites with
+outer capabilities, a privileged container, or a host Docker socket.
+"""
+
+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/rootless-docker-init"
+_RUNTIME_DIR = "/tmp/bot-bottle-docker-run"
+_SOCKET = f"{_RUNTIME_DIR}/docker.sock"
+READY_RETRIES = 30
+
+
+def build_image(
+    base_image: str,
+    build: Callable[..., None],
+) -> str:
+    """Layer spike-only tooling on an already-built provider image."""
+    image = f"{base_image}-rootless-docker"
+    init_script = Path(__file__).with_name("rootless-docker-init.sh")
+    with tempfile.TemporaryDirectory(prefix="bot-bottle-rootless-docker.") as tmp:
+        context = Path(tmp)
+        shutil.copy2(init_script, context / "rootless-docker-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/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 docker.io uidmap "
+            "rootlesskit slirp4netns fuse-overlayfs \\\n"
+            " && rm -rf /var/lib/apt/lists/* \\\n"
+            " && sed -i '/^node:/d' /etc/subuid /etc/subgid \\\n"
+            " && printf 'node:100000:65536\\n' >> /etc/subuid \\\n"
+            " && printf 'node:100000:65536\\n' >> /etc/subgid \\\n"
+            " && ln -s /usr/share/docker.io/contrib/dockerd-rootless.sh "
+            "/usr/local/bin/dockerd-rootless.sh\n"
+            "COPY rootless-docker-init.sh "
+            "/usr/local/libexec/bot-bottle/rootless-docker-init\n"
+            "RUN chmod 0755 /usr/local/libexec/bot-bottle/rootless-docker-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 start(bottle: object) -> None:
+    """Start and verify the unprivileged daemon through the bottle exec API."""
+    info("starting experimental rootless Docker daemon")
+    result = bottle.exec(shlex.quote(_INIT))  # type: ignore[attr-defined]
+    if result.returncode != 0:
+        detail = (result.stderr or result.stdout or "").strip()
+        die(f"rootless Docker 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("rootless Docker daemon is ready")
+            return
+        time.sleep(0.2)
+
+    logs = bottle.exec(  # type: ignore[attr-defined]
+        "tail -n 80 /tmp/bot-bottle-rootless-docker.log 2>/dev/null || true"
+    )
+    die(
+        "rootless Docker did not become ready without additional outer "
+        f"privileges:\n{(logs.stdout or logs.stderr or '<no log>').strip()}"
+    )
+
+
+__all__ = ["build_image", "guest_env", "start"]

bot_bottle/backend/util.py

@@ -7,8 +7,6 @@ from __future__ import annotations
 import hashlib
 import os
 import ssl
-import time
-from collections.abc import Callable
 from pathlib import Path
 from typing import TYPE_CHECKING
 
@@ -17,24 +15,6 @@ from ..log import die, info
 if TYPE_CHECKING:
     from ..egress import EgressPlan
 
-_CA_POLL_INTERVAL = 0.5
-
-
-def poll_ca_cert(fetch: Callable[[], str | None], *, timeout: float) -> str:
-    """Poll `fetch` until it returns a non-empty PEM string or `timeout` expires.
-
-    `fetch` should return the PEM on success and `None` (or empty string) when
-    the cert is not yet available. Raises `TimeoutError` if the cert never
-    appears within `timeout` seconds."""
-    deadline = time.monotonic() + timeout
-    while True:
-        result = fetch()
-        if result:
-            return result
-        if time.monotonic() >= deadline:
-            raise TimeoutError(f"CA cert not available after {timeout:g}s")
-        time.sleep(_CA_POLL_INTERVAL)
-
 
 # Debian-family CA layout, shared by every backend (all guest images
 # are Debian-family). AGENT_CA_PATH is the source path that

bot_bottle/contrib/claude/agent_provider.py

@@ -23,9 +23,8 @@ from ...agent_provider import (
     provider_startup_args,
 )
 from ...backend.docker import util as docker_mod
-from ...egress import CLAUDE_HOST_CREDENTIAL_TOKEN_REF, EgressRoute
+from ...egress import EgressRoute
 from ...log import die, info, warn
-from .claude_auth import claude_host_access_token
 
 
 if TYPE_CHECKING:
@@ -119,6 +118,7 @@ class ClaudeAgentProvider(AgentProvider):
         color: str = "",
         provider_settings: dict[str, object] | None = None,
     ) -> AgentProvisionPlan:
+        del forward_host_credentials, host_env
         resolved_guest_env = dict(guest_env or {})
         startup_args = provider_startup_args(provider_settings)
         guest_home = self.guest_home
@@ -180,24 +180,13 @@ class ClaudeAgentProvider(AgentProvider):
                 claude_settings,
                 f"{guest_home}/.claude/settings.json",
             ))
-        provisioned_env: dict[str, str] = {}
-        if forward_host_credentials:
-            _host_env = host_env or dict(os.environ)
-            provisioned_env[CLAUDE_HOST_CREDENTIAL_TOKEN_REF] = (
-                claude_host_access_token(_host_env)
-            )
-
-        cred_token_ref = (
-            CLAUDE_HOST_CREDENTIAL_TOKEN_REF if forward_host_credentials
-            else auth_token
-        )
         egress_routes = (EgressRoute(
             host="api.anthropic.com",
-            auth_scheme="Bearer" if (auth_token or forward_host_credentials) else "",
-            token_ref=cred_token_ref,
+            auth_scheme="Bearer" if auth_token else "",
+            token_ref=auth_token,
         ),)
         hidden_env_names: frozenset[str] = frozenset()
-        if auth_token or forward_host_credentials:
+        if auth_token:
             env_vars["CLAUDE_CODE_OAUTH_TOKEN"] = "egress-placeholder"
             hidden_env_names = frozenset({"CLAUDE_CODE_OAUTH_TOKEN"})
 
@@ -219,7 +208,6 @@ class ClaudeAgentProvider(AgentProvider):
             files=tuple(files),
             egress_routes=egress_routes,
             hidden_env_names=hidden_env_names,
-            provisioned_env=provisioned_env,
         )
 
     def provision_skills(self, plan: "BottlePlan", bottle: "Bottle") -> None:

bot_bottle/contrib/claude/claude_auth.py

@@ -1,114 +0,0 @@
-"""Host Claude auth helpers.
-
-Reads the host's Claude Code credentials and returns only the access
-token needed by egress. Does not expose refresh tokens or raw payloads.
-
-Credential storage by platform:
-  Linux  — ~/.claude/.credentials.json
-  macOS  — macOS Keychain, service "Claude Code-credentials"
-            (file path is tried first; Keychain is the fallback)
-"""
-
-from __future__ import annotations
-
-import json
-import os
-import subprocess
-import sys
-from datetime import datetime, timezone
-from pathlib import Path
-
-from ...log import die
-
-
-_KEYCHAIN_SERVICE = "Claude Code-credentials"
-
-
-def claude_auth_path(host_env: dict[str, str] | None = None) -> Path:
-    env = os.environ if host_env is None else host_env
-    home = env.get("HOME")
-    if home:
-        return Path(home) / ".claude" / ".credentials.json"
-    return Path.home() / ".claude" / ".credentials.json"
-
-
-def _read_keychain() -> dict[str, object] | None:
-    """Try the macOS Keychain. Returns parsed JSON dict or None."""
-    if sys.platform != "darwin":
-        return None
-    try:
-        result = subprocess.run(
-            ["security", "find-generic-password", "-s", _KEYCHAIN_SERVICE, "-w"],
-            capture_output=True,
-            text=True,
-            timeout=10,
-        )
-    except (FileNotFoundError, subprocess.TimeoutExpired):
-        return None
-    if result.returncode != 0 or not result.stdout.strip():
-        return None
-    try:
-        raw = json.loads(result.stdout.strip())
-    except json.JSONDecodeError:
-        return None
-    return raw if isinstance(raw, dict) else None
-
-
-def claude_host_access_token(
-    host_env: dict[str, str] | None = None,
-    *,
-    now: datetime | None = None,
-) -> str:
-    path = claude_auth_path(host_env)
-    raw: dict[str, object] | None = None
-
-    if path.is_file():
-        try:
-            raw = json.loads(path.read_text())
-        except (OSError, json.JSONDecodeError) as e:
-            die(f"claude host credentials: could not read valid JSON at {path}: {e}")
-        if not isinstance(raw, dict):
-            die(f"claude host credentials: {path} must contain a JSON object")
-    else:
-        raw = _read_keychain()
-        if raw is None:
-            die(
-                f"claude host credentials: auth file missing at {path} and "
-                f"macOS Keychain lookup for '{_KEYCHAIN_SERVICE}' failed. "
-                "Run `claude login` on the host or disable "
-                "agent_provider.forward_host_credentials."
-            )
-
-    oauth = raw.get("claudeAiOauth")
-    if not isinstance(oauth, dict):
-        die(
-            "claude host credentials: claudeAiOauth is missing from credentials. "
-            "Run `claude login` on the host or disable "
-            "agent_provider.forward_host_credentials."
-        )
-
-    access_token = oauth.get("accessToken")
-    if not isinstance(access_token, str) or not access_token:
-        die(
-            "claude host credentials: claudeAiOauth.accessToken is missing or empty. "
-            "Run `claude login` on the host and restart the bottle."
-        )
-
-    # expiresAt is in milliseconds
-    expires_at = oauth.get("expiresAt")
-    if isinstance(expires_at, (int, float)):
-        check_now = now or datetime.now(timezone.utc)
-        exp_dt = datetime.fromtimestamp(float(expires_at) / 1000.0, timezone.utc)
-        if exp_dt <= check_now:
-            die(
-                "claude host credentials: host Claude access token is expired. "
-                "Run `claude login` on the host and restart the bottle."
-            )
-
-    return access_token
-
-
-__all__ = [
-    "claude_auth_path",
-    "claude_host_access_token",
-]

bot_bottle/egress.py

@@ -30,7 +30,6 @@ if TYPE_CHECKING:
     from .manifest import ManifestBottle
 
 CODEX_HOST_CREDENTIAL_TOKEN_REF = "BOT_BOTTLE_CODEX_HOST_ACCESS_TOKEN"
-CLAUDE_HOST_CREDENTIAL_TOKEN_REF = "BOT_BOTTLE_CLAUDE_HOST_ACCESS_TOKEN"
 
 EGRESS_HOSTNAME = "egress"
 
@@ -401,7 +400,6 @@ class Egress(ABC):
         )
 
 __all__ = [
-    "CLAUDE_HOST_CREDENTIAL_TOKEN_REF",
     "CODEX_HOST_CREDENTIAL_TOKEN_REF",
     "EGRESS_HOSTNAME",
     "EGRESS_ROUTES_FILENAME",

bot_bottle/gateway_init.py

@@ -61,11 +61,6 @@ class _DaemonSpec:
 _EGRESS_ONLY_ENV_PREFIXES: tuple[str, ...] = ("EGRESS_TOKEN_",)
 _READY_GATED_DAEMONS: tuple[str, ...] = ("git-gate", "git-http")
 
-# Daemons that must be requested explicitly via BOT_BOTTLE_GATEWAY_DAEMONS
-# and are NOT started in the default (env-var-unset) case. The orchestrator
-# only runs in the combined infra container, never in a standalone gateway.
-_OPT_IN_DAEMONS: frozenset[str] = frozenset({"orchestrator"})
-
 
 def _env_for_daemon(name: str, base_env: dict[str, str]) -> dict[str, str]:
     """Egress sees the full bundle env. Everyone else gets a copy
@@ -80,14 +75,7 @@ def _env_for_daemon(name: str, base_env: dict[str, str]) -> dict[str, str]:
     }
 
 
-# The orchestrator is listed first so it starts before the gateway daemons,
-# giving the control plane a head start to accept /resolve calls. The gateway
-# daemons tolerate early /resolve failures and retry per-request.
 _DAEMONS: tuple[_DaemonSpec, ...] = (
-    _DaemonSpec("orchestrator", (
-        "python3", "-m", "bot_bottle.orchestrator",
-        "--host", "0.0.0.0", "--port", "8099", "--broker", "stub",
-    )),
     _DaemonSpec("egress", ("/bin/sh", "/app/egress-entrypoint.sh")),
     _DaemonSpec("git-gate", ("/bin/sh", "/git-gate-entrypoint.sh")),
     _DaemonSpec("git-http", ("python3", "-m", "bot_bottle.git_http_backend")),
@@ -115,20 +103,18 @@ def _selected_daemons(
     env: dict[str, str],
     all_daemons: Sequence[_DaemonSpec] | None = None,
 ) -> tuple[_DaemonSpec, ...]:
-    """Filter the daemon set by the BOT_BOTTLE_GATEWAY_DAEMONS env var.
+    """Filter the daemon set by the BOT_BOTTLE_GATEWAY_DAEMONS env
+    var. Unknown names in the list are ignored — the caller is the
+    source of truth for which daemons are wired.
 
-    When the var is unset/empty, return all non-opt-in daemons (the
-    standard gateway subset). Opt-in daemons (e.g. `orchestrator`) only
-    run when explicitly named — they never start in a plain gateway
-    container that doesn't set the env var. Unknown names are ignored.
-
-    `all_daemons` defaults to `_DAEMONS` resolved at call time (not at
-    definition time), so tests can pass a custom list."""
+    `all_daemons` defaults to `_DAEMONS` resolved at call time (not
+    at definition time), so tests can monkey-patch the module-level
+    `_DAEMONS` and have the new value take effect."""
     if all_daemons is None:
         all_daemons = _DAEMONS
     raw = env.get("BOT_BOTTLE_GATEWAY_DAEMONS", "").strip()
     if not raw:
-        return tuple(d for d in all_daemons if d.name not in _OPT_IN_DAEMONS)
+        return tuple(all_daemons)
     wanted = {n.strip() for n in raw.split(",") if n.strip()}
     return tuple(d for d in all_daemons if d.name in wanted)
 
@@ -150,7 +136,7 @@ def _pump(name: str, stream: IO[bytes]) -> None:
 
 def _spawn(spec: _DaemonSpec) -> subprocess.Popen[bytes]:
     env = _env_for_daemon(spec.name, dict(os.environ))
-    proc = subprocess.Popen(  # pylint: disable=consider-using-with
+    proc = subprocess.Popen(
         _argv_for_daemon(spec.name, spec.argv, env),
         stdout=subprocess.PIPE,
         stderr=subprocess.STDOUT,
@@ -197,14 +183,6 @@ class _Supervisor:
                 except ProcessLookupError:
                     pass
 
-    def _sigkill_all(self) -> None:
-        for _, p in self.procs:
-            if p.poll() is None:
-                try:
-                    p.kill()
-                except ProcessLookupError:
-                    pass
-
     def request_restart(self, daemon_name: str) -> bool:
         """Queue a daemon restart for the main loop to process.
 
@@ -257,7 +235,12 @@ class _Supervisor:
                         f"grace ({_GRACE_SECONDS:.0f}s) elapsed; SIGKILL on "
                         f"{', '.join(still_running)}"
                     )
-                    self._sigkill_all()
+                    for _, p in self.procs:
+                        if p.poll() is None:
+                            try:
+                                p.kill()
+                            except ProcessLookupError:
+                                pass
 
         done = all(p.poll() is not None for _, p in self.procs)
         if done:
@@ -378,10 +361,7 @@ def main(argv: Sequence[str] | None = None) -> int:
     # --signal HUP <bundle>` after writing routes.yaml. The kernel
     # delivers SIGHUP to PID 1 (this supervisor); forward it to
     # mitmdump so it reloads its addon.
-    signal.signal(
-        signal.SIGHUP,
-        lambda *_: sup.forward_signal(signal.SIGHUP, "egress"),  # type: ignore[misc]
-    )
+    signal.signal(signal.SIGHUP, lambda *_: sup.forward_signal(signal.SIGHUP, "egress"))  # type: ignore
 
     while not sup.tick():
         time.sleep(_POLL_INTERVAL)

bot_bottle/manifest_agent.py

@@ -25,9 +25,8 @@ class ManifestAgentProvider:
     header, and sets a placeholder CLAUDE_CODE_OAUTH_TOKEN in the agent
     so the Claude Code CLI starts.
 
-    `forward_host_credentials` forwards the host provider auth token into
-    the egress sidecar (Codex and Claude). For Codex this reads
-    `~/.codex/auth.json`; for Claude it reads `~/.claude/.credentials.json`.
+    `forward_host_credentials` forwards the host Codex auth token into
+    the egress daemon (Codex only).
     """
 
     template: str = "claude"
@@ -93,15 +92,10 @@ class ManifestAgentProvider:
                 f"is only supported for built-in templates "
                 f"({', '.join(sorted(PROVIDER_TEMPLATES))})"
             )
-        if forward_host_credentials and template not in {"codex", "claude"}:
+        if forward_host_credentials and template != "codex":
             raise ManifestError(
                 f"bottle '{bottle_name}' agent_provider.forward_host_credentials "
-                "is only supported for templates 'codex' and 'claude'"
-            )
-        if forward_host_credentials and auth_token:
-            raise ManifestError(
-                f"bottle '{bottle_name}' agent_provider.forward_host_credentials "
-                "and auth_token both set; use one or the other"
+                "is currently only supported for template 'codex'"
             )
         settings = _parse_provider_settings(bottle_name, template, d.get("settings"))
         return cls(

bot_bottle/manifest_bottle.py

@@ -44,6 +44,9 @@ class ManifestBottle:
     # daemon that exposes egress MCP tools to the agent. Set
     # `supervise: false` to skip the gateway.
     supervise: bool = True
+    # Experimental guest-local container engine (issue #392). Backends must
+    # implement this without granting access to a host/shared daemon.
+    docker_access: bool = False
 
     @classmethod
     def from_dict(cls, name: str, raw: object) -> "ManifestBottle":
@@ -123,7 +126,15 @@ class ManifestBottle:
                 f"(was {type(supervise_raw).__name__})"
             )
 
+        docker_access_raw = d.get("docker_access", False)
+        if not isinstance(docker_access_raw, bool):
+            raise ManifestError(
+                f"bottle '{name}' docker_access must be a boolean "
+                f"(was {type(docker_access_raw).__name__})"
+            )
+
         return cls(
             env=env, agent_provider=agent_provider, git=git,
             git_user=git_user, egress=egress, supervise=supervise_raw,
+            docker_access=docker_access_raw,
         )

bot_bottle/manifest_extends.py

@@ -54,6 +54,7 @@ def _merge_two_bottles_runtime(base: "ManifestBottle", override: "ManifestBottle
         git_user=merged_git_user,
         egress=merged_egress,
         supervise=override.supervise,
+        docker_access=override.docker_access,
     )
 
 
@@ -206,6 +207,7 @@ def _fold_two_bottles(
         git_user=merged_git_user,
         egress=merged_egress,
         supervise=later.supervise,
+        docker_access=later.docker_access,
     ), merged_repos_raw
 
 
@@ -266,6 +268,11 @@ def _merge_bottles(
     merged_supervise = (
         child.supervise if "supervise" in child_raw else parent.supervise
     )
+    merged_docker_access = (
+        child.docker_access
+        if "docker_access" in child_raw
+        else parent.docker_access
+    )
     validate_egress_routes(name, merged_egress.routes)
 
     return ManifestBottle(
@@ -275,6 +282,7 @@ def _merge_bottles(
         git_user=merged_git_user,
         egress=merged_egress,
         supervise=merged_supervise,
+        docker_access=merged_docker_access,
     )
 
 

bot_bottle/manifest_schema.py

@@ -16,7 +16,10 @@ _FILENAME_RX = re.compile(r"^[a-z][a-z0-9-]*$")
 # sets dies with a "did you mean" pointer: typos should not silently
 # ghost into an empty config.
 BOTTLE_KEYS = frozenset(
-    {"env", "extends", "agent_provider", "git-gate", "egress", "supervise"}
+    {
+        "env", "extends", "agent_provider", "git-gate", "egress", "supervise",
+        "docker_access",
+    }
 )
 AGENT_KEYS_REQUIRED: frozenset[str] = frozenset()
 AGENT_KEYS_OPTIONAL = frozenset({"bottle", "skills", "git-gate"})

bot_bottle/orchestrator/lifecycle.py

@@ -1,15 +1,17 @@
 """Orchestrator + gateway lifecycle (PRD 0070, docker slice).
 
-Runs both the orchestrator control plane and the gateway data plane inside
-a single `bot-bottle-infra` container on the shared gateway network —
-matching the structure already used by the macOS and Firecracker backends.
-`gateway_init` is PID 1 and supervises both; the infra container is an
-idempotent per-host singleton.
+Runs the orchestrator control plane **as a container** on the shared gateway
+network, alongside the gateway container. This is the PRD's "virtualize the
+orchestrator": container↔container between the gateway and the orchestrator
+avoids the host firewall (which drops container→host traffic), and the gateway
+reaches the control plane by container name over docker DNS. The host CLI
+reaches it via a published loopback port.
 
-The combined container replaces the prior two-container split
-(bot-bottle-orchestrator + bot-bottle-orch-gateway). The host CLI reaches
-the control plane via a published loopback port; gateway daemons reach it
-over 127.0.0.1 (same container).
+The orchestrator runs with the **register-only broker** — the *backend*
+launches agent containers (compose), so the orchestrator needs no docker
+socket. That keeps this control-plane container unprivileged; the host manages
+both containers. `ensure_running` is an idempotent singleton (fixed container
+names + the published port).
 """
 
 from __future__ import annotations
@@ -24,70 +26,49 @@ from pathlib import Path
 from .. import log
 from ..docker_cmd import run_docker
 from ..paths import CONTROL_PLANE_TOKEN_ENV, bot_bottle_root, host_control_plane_token
-from ..supervise import DB_PATH_IN_CONTAINER
-from .gateway import (
-    GATEWAY_CA_VOLUME,
-    GATEWAY_DOCKERFILE,
-    GATEWAY_IMAGE,
-    GATEWAY_NETWORK,
-    GatewayError,
-    MITMPROXY_HOME,
-    _host_db_dir,
-)
+from .gateway import GATEWAY_IMAGE, GATEWAY_NAME, GATEWAY_NETWORK, DockerGateway, GatewayError
 
 DEFAULT_PORT = 8099
-DEFAULT_STARTUP_TIMEOUT_SECONDS = 45.0
-
-INFRA_NAME = "bot-bottle-infra"
-INFRA_LABEL = "bot-bottle-infra=1"
-# The combined infra image: gateway data plane + orchestrator content.
-# Built from Dockerfile.infra (FROM gateway + COPY --from orchestrator).
-INFRA_IMAGE = os.environ.get("BOT_BOTTLE_INFRA_IMAGE", "bot-bottle-infra:latest")
-INFRA_DOCKERFILE = "Dockerfile.infra"
-# Baked as a container label so `ensure_running` can detect whether the
-# running container is executing the current bind-mounted source.
-INFRA_SOURCE_HASH_LABEL = "bot-bottle-infra-source-hash"
-
-# Orchestrator image: the single canonical definition of the control-plane
-# content (lean: python:3.12-slim + bot_bottle package, no mitmproxy/git).
-# Used as a build intermediate: `Dockerfile.infra` COPY --from this image.
+ORCHESTRATOR_NAME = "bot-bottle-orchestrator"
+ORCHESTRATOR_LABEL = "bot-bottle-orchestrator=1"
+# The control-plane's own runtime image — lean (python + the stdlib-only
+# `bot_bottle` package, bind-mounted at run time), distinct from the heavy
+# gateway data-plane image it used to borrow (#384). Env override for
+# operators pinning a published build.
 ORCHESTRATOR_IMAGE = os.environ.get(
     "BOT_BOTTLE_ORCHESTRATOR_IMAGE", "bot-bottle-orchestrator:latest"
 )
 ORCHESTRATOR_DOCKERFILE = "Dockerfile.orchestrator"
+# Baked onto the container as a label so `ensure_running` can tell whether the
+# running process is executing the *current* bind-mounted source — see
+# `source_hash`.
+ORCHESTRATOR_SOURCE_HASH_LABEL = "bot-bottle-orchestrator-source-hash"
 
-# The gateway daemons + orchestrator the infra container runs.
-# BOT_BOTTLE_GATEWAY_DAEMONS listing `orchestrator` opts it in to
-# gateway_init's supervise tree (see gateway_init._OPT_IN_DAEMONS).
-_INFRA_DAEMONS = "egress,git-http,supervise,orchestrator"
-
-# The bind-mount path for the live control-plane source inside the
-# container. Separate from /app so the gateway's baked scripts
-# (egress_addon.py, egress-entrypoint.sh) are not overlaid.
-_SRC_IN_CONTAINER = "/bot-bottle-src"
-# Bot-bottle host-root bind-mount inside the container (DB + state).
+# The repo root is bind-mounted into the control-plane container so
+# `python -m bot_bottle.orchestrator` resolves the package (the orchestrator
+# is stdlib-only, so the lean orchestrator image's python is enough).
+_REPO_ROOT = Path(__file__).resolve().parents[2]
+_APP_DIR = "/app"
 _ROOT_IN_CONTAINER = "/bot-bottle-root"
 
-# The supervise daemon writes proposals into the host DB directory.
-_SUPERVISE_DB_DIR_IN_CONTAINER = os.path.dirname(DB_PATH_IN_CONTAINER)
-
 _HEALTH_POLL_SECONDS = 0.25
+DEFAULT_STARTUP_TIMEOUT_SECONDS = 45.0
 _HEALTH_REQUEST_TIMEOUT_SECONDS = 1.0
 
-_REPO_ROOT = Path(__file__).resolve().parents[2]
-
 
 class OrchestratorStartError(RuntimeError):
-    """The infra container did not become healthy within the timeout."""
+    """The orchestrator container did not become healthy within the timeout."""
 
 
 def source_hash(repo_root: Path) -> str:
     """Content hash of the orchestrator's bind-mounted Python source (the
-    `bot_bottle` package the control-plane process imports). Changes only
-    when the code that would actually run changes — `ensure_running`
-    recreates the container on a mismatch so a code change takes effect,
-    but leaves a healthy up-to-date container alone to preserve in-memory
-    egress tokens."""
+    `bot_bottle` package the control-plane process imports). This only
+    changes when the code that would actually run inside the container
+    changes — `ensure_running` recreates the container on a mismatch and
+    otherwise leaves a healthy one alone, so a bottle launch that isn't
+    accompanied by a code change doesn't restart the process and drop every
+    *other* active bottle's in-memory egress tokens (`Orchestrator._tokens`
+    in `service.py`, never persisted to disk by design)."""
     h = hashlib.sha256()
     for path in sorted((repo_root / "bot_bottle").rglob("*.py")):
         h.update(str(path.relative_to(repo_root)).encode())
@@ -96,37 +77,57 @@ def source_hash(repo_root: Path) -> str:
 
 
 class OrchestratorService:
-    """Manages the single per-host infra container (control plane + gateway).
+    """Manages the orchestrator control-plane container + the shared gateway.
     Callers only need `ensure_running()` + `url`.
 
-    `infra_name` / `infra_label` let backends run independent infra containers
-    on the same host without name collisions (e.g. isolated integration tests
-    that can't share the production INFRA_NAME singleton)."""
+    `orchestrator_name` / `orchestrator_label` let backends run independent
+    orchestrators on the same host without name collisions (e.g. the
+    Firecracker backend uses `bot-bottle-fc-orchestrator` alongside the Docker
+    backend's `bot-bottle-orchestrator`); `gateway_name` gives the paired
+    gateway container the same treatment (e.g. isolated integration tests
+    that can't share the production `GATEWAY_NAME` singleton). Subclass and
+    override `_gateway()` for anything `_gateway_image`/`gateway_name` can't
+    express (a genuinely backend-specific gateway variant)."""
 
     def __init__(
         self,
         *,
         port: int = DEFAULT_PORT,
         network: str = GATEWAY_NETWORK,
-        image: str = INFRA_IMAGE,
+        image: str = ORCHESTRATOR_IMAGE,
+        gateway_image: str = GATEWAY_IMAGE,
+        gateway_name: str = GATEWAY_NAME,
         repo_root: Path = _REPO_ROOT,
         host_root: Path | None = None,
-        infra_name: str = INFRA_NAME,
-        infra_label: str = INFRA_LABEL,
+        orchestrator_name: str = ORCHESTRATOR_NAME,
+        orchestrator_label: str = ORCHESTRATOR_LABEL,
     ) -> None:
         self.port = port
         self.network = network
+        # Two distinct images (#384): `image` is the lean control-plane
+        # runtime this container runs; `_gateway_image` is the heavy egress /
+        # git-gate / supervise data plane the gateway container runs. They
+        # were one conflated image before the split.
         self.image = image
+        self._gateway_image = gateway_image
+        self._gateway_name = gateway_name
         self._repo_root = repo_root
         self._host_root = host_root or bot_bottle_root()
-        self._infra_name = infra_name
-        self._infra_label = infra_label
+        self._orchestrator_name = orchestrator_name
+        self._orchestrator_label = orchestrator_label
 
     @property
     def url(self) -> str:
         """Host-side control-plane URL (published loopback port)."""
         return f"http://127.0.0.1:{self.port}"
 
+    @property
+    def internal_url(self) -> str:
+        """Control-plane URL as the gateway container reaches it — by name over
+        docker DNS on the shared network. This is the gateway's
+        BOT_BOTTLE_ORCHESTRATOR_URL."""
+        return f"http://{self._orchestrator_name}:{self.port}"
+
     def is_healthy(self, *, timeout: float = _HEALTH_REQUEST_TIMEOUT_SECONDS) -> bool:
         try:
             with urllib.request.urlopen(f"{self.url}/health", timeout=timeout) as resp:
@@ -138,129 +139,139 @@ class OrchestratorService:
         proc = run_docker(["docker", "ps", "--filter", f"name=^/{name}$", "--format", "{{.Names}}"])
         return name in proc.stdout.split()
 
-    def _infra_source_current(self, current_hash: str) -> bool:
-        """True iff the running infra container was started from the current
-        bind-mounted source. Mirrors the macOS backend's `_source_current`."""
-        if not self._container_running(self._infra_name):
-            return False
-        proc = run_docker([
-            "docker", "inspect", "--format",
-            "{{ index .Config.Labels \"" + INFRA_SOURCE_HASH_LABEL + "\" }}",
-            self._infra_name,
-        ])
-        if proc.returncode != 0:
-            return True  # can't compare → don't churn a working container
-        return proc.stdout.strip() == current_hash
-
-    def _ensure_network(self) -> None:
-        if run_docker(["docker", "network", "inspect", self.network]).returncode == 0:
-            return
-        proc = run_docker(["docker", "network", "create", self.network])
-        if proc.returncode != 0 and "already exists" not in proc.stderr:
-            raise GatewayError(
-                f"gateway network {self.network} failed to create: {proc.stderr.strip()}"
-            )
-
-    def _build_images(self) -> None:
-        """Build the gateway base, the orchestrator intermediate, then the
-        infra image. All are cache-aware: a no-op when nothing changed."""
-        for tag, dockerfile in (
-            (GATEWAY_IMAGE, GATEWAY_DOCKERFILE),
-            (ORCHESTRATOR_IMAGE, ORCHESTRATOR_DOCKERFILE),
-            (self.image, INFRA_DOCKERFILE),
-        ):
-            argv = ["docker", "build", "-t", tag,
-                    "-f", str(self._repo_root / dockerfile),
-                    str(self._repo_root)]
-            if os.environ.get("BOT_BOTTLE_NO_CACHE"):
-                argv.insert(2, "--no-cache")
-            proc = run_docker(argv)
-            if proc.returncode != 0:
-                raise GatewayError(f"{dockerfile} build failed: {proc.stderr.strip()}")
-
-    def _run_infra_container(self, current_hash: str) -> None:
-        """Start the combined infra container (idempotent: clears a stale
-        fixed-name container first). Labels the container with `current_hash`
-        so a later `ensure_running` can detect a real code change."""
-        self._ensure_network()
-        run_docker(["docker", "rm", "--force", self._infra_name])
+    def _run_orchestrator_container(self, current_hash: str) -> None:
+        """Start the control-plane container (idempotent: clears a stale
+        fixed-name container first). Register-only broker → no docker socket.
+        Labels the container with `current_hash` so a later `ensure_running`
+        can detect a real code change (see `source_hash`)."""
+        run_docker(["docker", "rm", "--force", self._orchestrator_name])
         proc = run_docker([
             "docker", "run", "--detach",
-            "--name", self._infra_name,
-            "--label", self._infra_label,
-            "--label", f"{INFRA_SOURCE_HASH_LABEL}={current_hash}",
+            "--name", self._orchestrator_name,
+            "--label", self._orchestrator_label,
+            "--label", f"{ORCHESTRATOR_SOURCE_HASH_LABEL}={current_hash}",
             "--network", self.network,
-            # Host CLI reaches the control plane here (loopback only).
-            # gateway_init always starts the orchestrator on DEFAULT_PORT (8099)
-            # inside the container; self.port is the host-side published port.
-            "--publish", f"127.0.0.1:{self.port}:{DEFAULT_PORT}",
-            # Persist the mitmproxy CA so it survives container recreation.
-            "--volume", f"{GATEWAY_CA_VOLUME}:{MITMPROXY_HOME}",
-            # Shared supervise DB (same file the operator reads over HTTP).
-            "--volume", f"{_host_db_dir()}:{_SUPERVISE_DB_DIR_IN_CONTAINER}",
-            "--env", f"SUPERVISE_DB_PATH={DB_PATH_IN_CONTAINER}",
-            # Live control-plane source, mounted to a path that does not
-            # overlay the gateway's baked /app scripts.
-            "--volume", f"{self._repo_root}:{_SRC_IN_CONTAINER}:ro",
-            # PYTHONPATH lets the orchestrator (and other Python daemons)
-            # import the live source ahead of the installed package.
-            "--env", f"PYTHONPATH={_SRC_IN_CONTAINER}",
-            # Orchestrator registry DB on the host (sole writer: control plane).
+            # Host CLI reaches the control plane here; bound to loopback so it
+            # is not exposed on the host's external interfaces. NOTE: the
+            # container is still on `self.network` (the shared gateway network),
+            # so agents can reach it by container IP — which is exactly why the
+            # control plane requires the secret below rather than trusting the
+            # network boundary.
+            "--publish", f"127.0.0.1:{self.port}:{self.port}",
+            "--volume", f"{self._repo_root}:{_APP_DIR}:ro",
+            "--workdir", _APP_DIR,
+            # Persist the registry DB on the host (sole-owner: only the
+            # orchestrator opens bot-bottle.db).
             "--volume", f"{self._host_root}:{_ROOT_IN_CONTAINER}",
             "--env", f"BOT_BOTTLE_ROOT={_ROOT_IN_CONTAINER}",
-            # Control-plane secret: required by the orchestrator (to enforce)
-            # and by the gateway daemons (to present on /resolve calls).
+            # The control-plane secret it requires on every route but /health.
+            # Bare `--env NAME` → docker inherits the value from the run env
+            # below, so the secret never lands on argv / `docker inspect`.
             "--env", CONTROL_PLANE_TOKEN_ENV,
-            # Gateway daemons reach the orchestrator over loopback at its
-            # fixed internal port (DEFAULT_PORT), independent of self.port.
-            "--env", f"BOT_BOTTLE_ORCHESTRATOR_URL=http://127.0.0.1:{DEFAULT_PORT}",
-            # Opt the orchestrator into gateway_init's supervise tree.
-            "--env", f"BOT_BOTTLE_GATEWAY_DAEMONS={_INFRA_DAEMONS}",
+            "--entrypoint", "python3",
             self.image,
+            "-m", "bot_bottle.orchestrator",
+            "--host", "0.0.0.0", "--port", str(self.port), "--broker", "stub",
         ], env={**os.environ, CONTROL_PLANE_TOKEN_ENV: host_control_plane_token()})
         if proc.returncode != 0:
             raise OrchestratorStartError(
-                f"infra container failed to start: {proc.stderr.strip()}"
+                f"orchestrator container failed to start: {proc.stderr.strip()}"
             )
 
+    def _gateway(self) -> DockerGateway:
+        return DockerGateway(
+            self._gateway_image,
+            name=self._gateway_name,
+            network=self.network,
+            orchestrator_url=self.internal_url,
+        )
+
+    def _ensure_orchestrator_image(self) -> None:
+        """Build the lean control-plane image from `Dockerfile.orchestrator`
+        when it's missing (#384). Cheap — a `FROM python:*-slim` base with no
+        deps to install, so the layer cache makes rebuilds a no-op. Unlike the
+        gateway image this is build-if-missing, not build-every-time: the
+        control plane bind-mounts its source, so a code change is caught by the
+        source-hash recreate (below), not by an image rebuild."""
+        if run_docker(["docker", "image", "inspect", self.image]).returncode == 0:
+            return
+        argv = ["docker", "build", "-t", self.image,
+                "-f", str(self._repo_root / ORCHESTRATOR_DOCKERFILE),
+                str(self._repo_root)]
+        if os.environ.get("BOT_BOTTLE_NO_CACHE"):
+            argv.insert(2, "--no-cache")
+        proc = run_docker(argv)
+        if proc.returncode != 0:
+            raise GatewayError(
+                f"orchestrator image build failed: {proc.stderr.strip()}"
+            )
+
+    def _orchestrator_source_current(self, current_hash: str) -> bool:
+        """True iff the running orchestrator container was created from the
+        *current* bind-mounted source. Mirrors `DockerGateway`'s
+        image-staleness check, but by content hash rather than image id since
+        the orchestrator runs bind-mounted source, not a built image."""
+        if not self._container_running(self._orchestrator_name):
+            return False
+        proc = run_docker([
+            "docker", "inspect", "--format",
+            "{{ index .Config.Labels \"" + ORCHESTRATOR_SOURCE_HASH_LABEL + "\" }}",
+            self._orchestrator_name,
+        ])
+        if proc.returncode != 0:
+            return True  # can't compare -> don't churn a working container
+        return proc.stdout.strip() == current_hash
+
     def ensure_running(
         self, *, startup_timeout: float = DEFAULT_STARTUP_TIMEOUT_SECONDS,
     ) -> str:
-        """Ensure the infra container (control plane + gateway) is up; return
-        the host control-plane URL. Idempotent — a healthy container on current
-        source is left untouched. Raises `OrchestratorStartError` on timeout."""
-        self._build_images()
+        """Ensure the control plane + shared gateway are up; return the host
+        control-plane URL. Idempotent — a healthy control plane running
+        current code and a running gateway are left untouched. Raises
+        `OrchestratorStartError` on timeout."""
+        gateway = self._gateway()
+        gateway.ensure_built()  # rebuild the bundle image on a source change
+        gateway.ensure_running()  # creates the shared network + (re)starts gateway
 
+        # Recreate the orchestrator container only when its bind-mounted
+        # source has actually changed since it started — its Python process
+        # loaded that code at startup and won't reload, so a stale container
+        # would keep running OLD control-plane code. Recreating on *every*
+        # launch (the prior behaviour) would drop every other active
+        # bottle's in-memory egress tokens each time a new bottle starts,
+        # since the orchestrator process holds them only in memory (#381).
         current_hash = source_hash(self._repo_root)
-        if self.is_healthy() and self._infra_source_current(current_hash):
+        if self.is_healthy() and self._orchestrator_source_current(current_hash):
             return self.url
 
-        log.info("starting infra container", context={"name": self._infra_name})
-        self._run_infra_container(current_hash)
+        self._ensure_orchestrator_image()
+        log.info(
+            "starting orchestrator container",
+            context={"name": self._orchestrator_name},
+        )
+        self._run_orchestrator_container(current_hash)
 
         deadline = time.monotonic() + startup_timeout
         while time.monotonic() < deadline:
             if self.is_healthy():
-                log.info("infra container healthy", context={"url": self.url})
+                log.info("orchestrator healthy", context={"url": self.url})
                 return self.url
             time.sleep(_HEALTH_POLL_SECONDS)
         raise OrchestratorStartError(
-            f"infra container at {self.url} did not become healthy within {startup_timeout:g}s"
+            f"orchestrator at {self.url} did not become healthy within {startup_timeout:g}s"
         )
 
     def stop(self) -> None:
-        """Remove the infra container (idempotent)."""
-        run_docker(["docker", "rm", "--force", self._infra_name])
+        """Remove the orchestrator + gateway containers (idempotent)."""
+        run_docker(["docker", "rm", "--force", self._orchestrator_name])
+        self._gateway().stop()
 
 
 __all__ = [
     "OrchestratorService",
     "OrchestratorStartError",
-    "INFRA_NAME",
-    "INFRA_IMAGE",
-    "INFRA_SOURCE_HASH_LABEL",
+    "ORCHESTRATOR_NAME",
     "ORCHESTRATOR_IMAGE",
     "DEFAULT_PORT",
     "DEFAULT_STARTUP_TIMEOUT_SECONDS",
-    "source_hash",
 ]

docs/prds/prd-new-claude-forward-host-credentials.md

@@ -1,146 +0,0 @@
-# PRD prd-new: Claude forward_host_credentials
-
-- **Status:** Draft
-- **Author:** claude
-- **Created:** 2026-07-01
-- **Issue:** #325
-
-## Summary
-
-Add `agent_provider.forward_host_credentials: true` support for the
-`claude` template, mirroring the existing Codex flow. When enabled,
-bot-bottle reads the host's Claude OAuth session key from
-`~/.claude/.credentials.json` at launch, forwards it only to the egress sidecar,
-and injects a placeholder `CLAUDE_CODE_OAUTH_TOKEN` into the agent so
-Claude Code starts without ever seeing the real credential.
-
-## Problem
-
-Running a Claude agent in a container today requires the operator to
-manually extract a long-lived OAuth token (`claude setup-token`), export
-it as `BOT_BOTTLE_CLAUDE_OAUTH_TOKEN`, and reference it explicitly in
-the manifest with `agent_provider.auth_token:
-"BOT_BOTTLE_CLAUDE_OAUTH_TOKEN"`. This is a two-step manual ceremony
-that is easy to skip or do incorrectly.
-
-The host already stores a valid Claude session in `~/.claude/.credentials.json`
-after `claude login`. Codex already automates an
-equivalent extraction from `~/.codex/auth.json`. There is no reason
-Claude bottles cannot do the same.
-
-## Goals / Success Criteria
-
-- A Claude bottle with `forward_host_credentials: true` in the manifest
-  uses the host's `~/.claude/.credentials.json` session key at launch with no
-  additional operator steps.
-- The agent container receives only `CLAUDE_CODE_OAUTH_TOKEN=egress-placeholder`
-  — never the real token.
-- The real session key lives only in the egress sidecar's environment.
-- Missing, malformed, or expired host Claude auth fails launch with a
-  clear operator-facing message.
-- Existing `auth_token` behavior is unchanged.
-- `forward_host_credentials: true` is rejected in the manifest when both
-  `auth_token` and `forward_host_credentials` are set, since they serve
-  the same purpose.
-
-## Non-goals
-
-- Refreshing Claude OAuth tokens in the sidecar.
-- Writing a dummy `~/.claude.json` auth state to the agent (unlike the
-  Codex flow, Claude Code reads its credential from `CLAUDE_CODE_OAUTH_TOKEN`
-  in env, not from an auth file — no guest-side auth marker is needed).
-- Supporting `forward_host_credentials` for providers other than `codex`
-  and `claude`.
-
-## Design
-
-### Manifest schema
-
-```yaml
-agent_provider:
-  template: claude
-  forward_host_credentials: true
-```
-
-Rejects in manifest validation when:
-- Template is not `codex` or `claude`.
-- Both `auth_token` and `forward_host_credentials` are set.
-
-### Host auth extraction (`contrib/claude/claude_auth.py`)
-
-Claude Code credential storage varies by platform:
-
-- **Linux**: `~/.claude/.credentials.json`
-- **macOS**: macOS Keychain, service `"Claude Code-credentials"`
-  (the file path is tried first; Keychain is the fallback when the file
-  is absent)
-
-`~/.claude.json` contains only UI state and profile metadata — no token.
-
-The credentials JSON schema (same whether from file or Keychain):
-
-```json
-{
-  "claudeAiOauth": {
-    "accessToken": "<access-token>",
-    "refreshToken": "<refresh-token>",
-    "expiresAt": 1748276587173,
-    "scopes": ["user:inference", "user:profile"]
-  }
-}
-```
-
-`expiresAt` is in **milliseconds** (not seconds).
-
-At prepare/launch time, when `forward_host_credentials: true`:
-
-1. Try `~/.claude/.credentials.json`; on macOS, if absent, run
-   `security find-generic-password -s "Claude Code-credentials" -w`
-   and parse its stdout as JSON.
-2. Require a `claudeAiOauth` dict.
-3. Require a non-empty `claudeAiOauth.accessToken` string.
-4. If `claudeAiOauth.expiresAt` is present, divide by 1000 and require
-   the result to be in the future.
-5. Return only the access token to the launch path.
-
-Errors name the missing or invalid condition and point the operator at
-`claude login`, without printing token values.
-
-### Egress route
-
-When `forward_host_credentials: true`:
-
-- Provision the session key in `provisioned_env` under
-  `BOT_BOTTLE_CLAUDE_HOST_ACCESS_TOKEN` (new constant in `egress.py`).
-- Set up the `api.anthropic.com` egress route with `auth_scheme: Bearer`
-  and `token_ref: BOT_BOTTLE_CLAUDE_HOST_ACCESS_TOKEN`.
-- Set `CLAUDE_CODE_OAUTH_TOKEN=egress-placeholder` in the agent env and
-  add it to `hidden_env_names`.
-
-No dummy auth file and no `verify` step are needed — Claude Code reads
-the credential from the env var, not from a file.
-
-### Constants
-
-- `CLAUDE_HOST_CREDENTIAL_TOKEN_REF = "BOT_BOTTLE_CLAUDE_HOST_ACCESS_TOKEN"`
-  in `egress.py` (alongside the existing `CODEX_HOST_CREDENTIAL_TOKEN_REF`).
-- `CLAUDE_HOST_CREDENTIAL_HOSTS = ("api.anthropic.com",)` in
-  `agent_provider.py` (alongside the existing `CODEX_HOST_CREDENTIAL_HOSTS`).
-
-### Data flow
-
-```
-Host ~/.claude/.credentials.json  →  bot-bottle launch
-                            │
-                            ├──► egress sidecar env (real token only)
-                            │
-                            └──► agent env: CLAUDE_CODE_OAUTH_TOKEN=egress-placeholder
-
-Agent  →  HTTPS to api.anthropic.com (via egress)
-Egress →  injects Authorization: Bearer <real token>
-Egress →  forwards to api.anthropic.com
-```
-
-## Open questions
-
-None — the Codex precedent makes the design clear.

docs/prds/prd-new-consolidate-docker-infra-backend.md

@@ -1,156 +0,0 @@
-# PRD prd-new: Consolidate infra backend for Docker
-
-- **Status:** Active
-- **Author:** Claude
-- **Created:** 2026-07-20
-- **Issue:** #431
-
-## Summary
-
-The Docker backend runs two containers — `bot-bottle-orch-gateway` (gateway
-data plane) and `bot-bottle-orchestrator` (control plane) — where the
-macOS and Firecracker backends already run a single combined infra
-unit. This PRD collapses Docker to the same model: one `bot-bottle-infra`
-container running both processes under the `gateway_init` supervise tree, a
-restructured `Dockerfile.infra` as the shared gateway+orchestrator base,
-and a handful of extracted shared utilities (CA cert polling, teardown
-sequence, launch skeleton) that are currently duplicated across all three
-`consolidated_launch.py` files.
-
-## Goals / success criteria
-
-- Docker backend starts exactly one infra container instead of two.
-- `Dockerfile.infra` is the shared base image (gateway + orchestrator, no
-  buildah); the Firecracker image layers buildah on top of it.
-- The orchestrator process runs under the `gateway_init` supervise tree
-  inside the combined container (one PID-1, one restart/health surface).
-- CA cert polling, the teardown sequence, and the shared launch skeleton
-  (ensure-infra → register → provision → return context) live in a single
-  shared module; all three backends import from it.
-- No functional change to macOS or Firecracker launch paths.
-
-## Non-goals
-
-- Changing per-bottle isolation — agents stay one-VM/container-each.
-- Consolidating transport implementations (`DockerGatewayTransport`,
-  `AppleGatewayTransport`, `SshGatewayTransport`) — these are already the
-  right abstraction boundary.
-- macOS DHCP-inversion of registration order — irreducible backend
-  difference, stays as-is.
-- Any changes to the orchestrator RPC protocol or the attribution model.
-
-## Design
-
-### Dockerfile restructuring
-
-**Current shape:**
-
-- `Dockerfile.gateway` — data plane (mitmproxy, gitleaks, git, openssh,
-  supervise daemons)
-- `Dockerfile.orchestrator` — control plane (python:3.12-slim + bot_bottle
-  package; stdlib-only, no third-party deps)
-- `Dockerfile.infra` — Firecracker only: `FROM bot-bottle-gateway` +
-  buildah + `COPY --from bot-bottle-orchestrator`
-
-**New shape:**
-
-- `Dockerfile.gateway` — unchanged
-- `Dockerfile.orchestrator` — unchanged (single definition of orchestrator
-  content; both Docker infra and Firecracker infra `COPY --from` it)
-- `Dockerfile.infra` — **shared base**: `FROM bot-bottle-gateway` + `COPY
-  --from bot-bottle-orchestrator` (no buildah — Docker infra image)
-- `Dockerfile.infra.fc` — Firecracker only: `FROM bot-bottle-infra` +
-  buildah/crun/netavark/aardvark-dns (layered on the shared base, same net
-  result as today)
-
-The comment in `Dockerfile.infra` that says "the docker backend keeps
-orchestrator + gateway as separate images; this combined image exists only
-for the Firecracker single-VM cut" is removed.
-
-### Orchestrator in the supervise tree
-
-`gateway_init` already supervises the data-plane daemons (egress, git-http,
-supervise-MCP). The orchestrator control plane is added as another supervised
-process: `python3 -m bot_bottle.orchestrator --host 0.0.0.0 --port <port>
---broker stub`.
-
-The orchestrator source is bind-mounted (`/app` → repo root, as today) so
-dev live-reload still works. `source_hash`-based container recreation in
-`OrchestratorService.ensure_running` continues to apply — a code change
-recreates the combined infra container, which bounces both gateway and
-orchestrator. This is acceptable: the docker backend is a dev/legacy target
-where in-flight egress connections across a code deploy are not a hard
-requirement.
-
-### `OrchestratorService` changes
-
-`OrchestratorService` currently starts two containers in sequence: gateway
-first (`DockerGateway.ensure_running`), then orchestrator. After this PRD:
-
-- Single `docker run` of `bot-bottle-infra:latest`
-- Container name: `bot-bottle-infra` (replaces `bot-bottle-orch-gateway` +
-  `bot-bottle-orchestrator`)
-- Published ports: `127.0.0.1:{host_port}:8099` for the control plane
-  (`gateway_init` listens on a fixed internal port 8099; the caller-chosen
-  host port maps to it)
-- Bind mounts: repo root + host root (same as today)
-- `DockerGateway` becomes an implementation detail of `OrchestratorService`
-  rather than a separately started container; the gateway image name
-  (`GATEWAY_IMAGE`) is no longer referenced at runtime, only at build time
-  for the `Dockerfile.infra` base
-
-The `_gateway()` / `ensure_running` two-step in `OrchestratorService` is
-replaced by a single `_run_infra_container()`.
-
-### Shared backend utilities
-
-Three items are duplicated across
-`backend/docker/consolidated_launch.py`,
-`backend/macos_container/consolidated_launch.py`, and
-`backend/firecracker/consolidated_launch.py`:
-
-1. **CA cert polling loop** — `deadline = time.monotonic() + timeout; while
-   ...: try fetch CA; sleep` — extracted to
-   `backend/consolidated_util.py:poll_ca_cert(transport, *, timeout)`.
-
-2. **Teardown sequence** — `OrchestratorClient(url).teardown_bottle(id)` +
-   `deprovision_git_gate(transport, id)` — extracted to
-   `backend/consolidated_util.py:teardown_consolidated(url, transport,
-   bottle_id)`.
-
-3. **Launch skeleton** — all three follow: ensure-infra → allocate/register
-   → provision git-gate → fetch CA cert → return launch context. The macOS
-   inversion (agent starts before registration, source IP from DHCP) is the
-   only deviation. Extract a shared `_provision_bottle(transport, bottle_id,
-   plan, orchestrator_url)` helper covering the register → provision →
-   return-token steps; the backends keep their own `launch_consolidated`
-   wrappers for the before/after (infra-ensure + agent-start + IP
-   allocation), calling the shared helper.
-
-The new `backend/consolidated_util.py` module holds only backend-neutral,
-transport-agnostic logic. All three backends import from it.
-
-## Implementation chunks
-
-1. **(this PR)** Dockerfile restructuring: rename current `Dockerfile.infra`
-   content to `Dockerfile.infra.fc`; write new `Dockerfile.infra` as
-   gateway+orchestrator base. Update Firecracker image-build references from
-   `Dockerfile.infra` → `Dockerfile.infra.fc`.
-
-2. Add orchestrator process to `gateway_init` supervise tree.
-
-3. Collapse `OrchestratorService` to a single-container start; rename
-   container from `bot-bottle-orch-gateway`/`bot-bottle-orchestrator` →
-   `bot-bottle-infra`; update image name constant.
-
-4. Extract `backend/consolidated_util.py` with `poll_ca_cert`,
-   `teardown_consolidated`, and `_provision_bottle`; update all three
-   `consolidated_launch.py` files to import from it.
-
-5. Update tests that reference the old container names or two-container
-   startup sequence.
-
-## Open questions
-
-None — the supervise-tree approach and shared Dockerfile layering were
-confirmed in issue #431.

tests/integration/test_macos_rootless_docker_spike.py

@@ -0,0 +1,103 @@
+"""Live-Mac acceptance spike for guest-local rootless Docker (issue #392).
+
+Run explicitly on an Apple Silicon/macOS 26 host:
+
+    BOT_BOTTLE_ROOTLESS_DOCKER_SPIKE=1 \
+      python3 -m unittest tests.integration.test_macos_rootless_docker_spike -v
+
+The opt-in is deliberate: ordinary Linux CI cannot execute Apple Container.
+"""
+
+from __future__ import annotations
+
+import os
+import platform
+import shutil
+import tempfile
+import unittest
+from pathlib import Path
+
+from bot_bottle.backend import BottleSpec, get_bottle_backend
+from bot_bottle.manifest import ManifestIndex
+
+
+@unittest.skipUnless(
+    platform.system() == "Darwin"
+    and os.environ.get("BOT_BOTTLE_ROOTLESS_DOCKER_SPIKE") == "1",
+    "requires an explicit live-Mac rootless-Docker spike run",
+)
+class TestMacosRootlessDockerSpike(unittest.TestCase):
+    def test_compose_stays_inside_registered_bottle(self) -> None:
+        workspace = Path(tempfile.mkdtemp(prefix="rootless-docker-spike."))
+        stage = Path(tempfile.mkdtemp(prefix="rootless-docker-stage."))
+        try:
+            (workspace / "index.html").write_text("bottle-compose-ok\n")
+            (workspace / "compose.yaml").write_text(
+                "services:\n"
+                "  web:\n"
+                "    image: python:3.12-alpine\n"
+                "    working_dir: /workspace\n"
+                "    command: python -m http.server 8000\n"
+                "    volumes: ['.:/workspace']\n"
+                "    ports: ['18080:8000']\n",
+                encoding="utf-8",
+            )
+            manifest = ManifestIndex.from_json_obj({
+                "bottles": {"dev": {
+                    "docker_access": True,
+                    "egress": {"routes": [
+                        {"host": "auth.docker.io"},
+                        {"host": "registry-1.docker.io"},
+                        {"host": "production.cloudflare.docker.com"},
+                    ]},
+                }},
+                "agents": {"spike": {
+                    "bottle": "dev", "skills": [], "prompt": "",
+                }},
+            })
+            spec = BottleSpec(
+                manifest=manifest,
+                agent_name="spike",
+                copy_cwd=True,
+                user_cwd=str(workspace),
+            )
+            backend = get_bottle_backend("macos-container")
+            plan = backend.prepare(spec, stage_dir=stage)
+            with backend.launch(plan) as bottle:
+                workdir = plan.workspace_plan.workdir
+                checks = (
+                    "docker info >/dev/null && docker compose version && "
+                    f"cd {workdir} && docker compose up -d --wait && "
+                    "curl --fail --silent http://127.0.0.1:18080/ | "
+                    "grep -q bottle-compose-ok"
+                )
+                result = bottle.exec(checks)
+                self.assertEqual(
+                    0, result.returncode,
+                    f"stdout={result.stdout!r}\nstderr={result.stderr!r}",
+                )
+                inspect = bottle.exec(
+                    "docker info --format '{{json .SecurityOptions}}'"
+                )
+                self.assertIn("rootless", inspect.stdout.lower())
+                self.assertNotEqual(
+                    0,
+                    bottle.exec("test -S /var/run/docker.sock").returncode,
+                    "spike must never expose a host/rootful Docker socket",
+                )
+                direct = bottle.exec(
+                    "docker run --rm --env HTTP_PROXY= --env HTTPS_PROXY= "
+                    "--env http_proxy= --env https_proxy= python:3.12-alpine "
+                    "wget -T 4 -qO- https://evil.example.com/"
+                )
+                self.assertNotEqual(
+                    0, direct.returncode,
+                    "an inner container obtained direct, unproxied egress",
+                )
+        finally:
+            shutil.rmtree(workspace, ignore_errors=True)
+            shutil.rmtree(stage, ignore_errors=True)
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/integration/test_orchestrator_docker_control_plane_auth.py

@@ -34,7 +34,6 @@ from tests._docker import skip_unless_docker
 # image instead of leaking a new dangling tag on every invocation.
 _TEST_ORCHESTRATOR_IMAGE = "bot-bottle-orchestrator:itest"
 _TEST_GATEWAY_IMAGE = "bot-bottle-gateway:itest"
-_TEST_INFRA_IMAGE = "bot-bottle-infra:itest"
 
 
 @skip_unless_docker()
@@ -70,17 +69,20 @@ class TestDockerControlPlaneAuthIntegration(unittest.TestCase):
         os.environ["BOT_BOTTLE_ROOT"] = cls._tmp.name
         cls.addClassCleanup(_restore_root)
 
-        infra_name = f"bot-bottle-infra-itest-{suffix}"
+        orchestrator_name = f"bot-bottle-orch-itest-{suffix}"
+        gateway_name = f"bot-bottle-gw-itest-{suffix}"
         network = f"bot-bottle-net-itest-{suffix}"
         host_root = Path(cls._tmp.name)
         cls.addClassCleanup(
-            cls._teardown_docker, infra_name, network, host_root
+            cls._teardown_docker, orchestrator_name, gateway_name, network, host_root
         )
 
         cls.svc = OrchestratorService(
-            infra_name=infra_name,
+            orchestrator_name=orchestrator_name,
+            gateway_name=gateway_name,
             network=network,
-            image=_TEST_INFRA_IMAGE,
+            image=_TEST_ORCHESTRATOR_IMAGE,
+            gateway_image=_TEST_GATEWAY_IMAGE,
             port=20000 + secrets.randbelow(10000),
             host_root=host_root,
         )
@@ -89,23 +91,23 @@ class TestDockerControlPlaneAuthIntegration(unittest.TestCase):
 
     @staticmethod
     def _teardown_docker(
-        infra_name: str, network: str, host_root: Path
+        orchestrator_name: str, gateway_name: str, network: str, host_root: Path
     ) -> None:
         subprocess.run(
-            ["docker", "rm", "--force", infra_name],
+            ["docker", "rm", "--force", orchestrator_name, gateway_name],
             stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, check=False,
         )
         subprocess.run(
             ["docker", "network", "rm", network],
             stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, check=False,
         )
-        # The infra container (no USER directive) wrote the registry
+        # The orchestrator container (no USER directive) wrote the registry
         # DB as root into the throwaway host_root; chown it back so the
         # (non-root) tempdir cleanup can remove it. Same workaround
         # test_multitenant_isolation.py uses for the identical bind mount.
         subprocess.run(
             ["docker", "run", "--rm", "-v", f"{host_root}:/r",
-             "--entrypoint", "chown", _TEST_INFRA_IMAGE, "-R",
+             "--entrypoint", "chown", _TEST_GATEWAY_IMAGE, "-R",
              f"{os.getuid()}:{os.getgid()}", "/r"],
             stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, check=False,
         )

tests/unit/test_agent_provider.py

@@ -9,15 +9,11 @@ import unittest
 from pathlib import Path
 
 from bot_bottle.agent_provider import (
-    CLAUDE_HOST_CREDENTIAL_HOSTS,
     CODEX_HOST_CREDENTIAL_HOSTS,
     build_agent_provision_plan,
     prompt_args,
 )
-from bot_bottle.egress import (
-    CLAUDE_HOST_CREDENTIAL_TOKEN_REF,
-    CODEX_HOST_CREDENTIAL_TOKEN_REF,
-)
+from bot_bottle.egress import CODEX_HOST_CREDENTIAL_TOKEN_REF
 
 
 def _jwt(exp: int) -> str:
@@ -296,67 +292,6 @@ class TestAgentProviderRuntime(unittest.TestCase):
             )
         self.assertEqual({}, plan.provisioned_env)
 
-    def test_claude_forward_host_credentials_populates_egress_route(self):
-        access_token = "sk-ant-oat01-test-key"  # gitleaks:allow
-        with tempfile.TemporaryDirectory(prefix="bb-provider.") as tmp:
-            home = Path(tmp) / "host-claude"
-            cred_dir = home / ".claude"
-            cred_dir.mkdir(parents=True)
-            (cred_dir / ".credentials.json").write_text(json.dumps({
-                "claudeAiOauth": {"accessToken": access_token},
-            }))
-            plan = build_agent_provision_plan(
-                template="claude",
-                dockerfile="",
-                state_dir=Path(tmp),
-                instance_name="bot-bottle-test",
-                prompt_file=Path(tmp) / "prompt.txt",
-                forward_host_credentials=True,
-                host_env={"HOME": str(home)},
-            )
-        self.assertEqual(1, len(plan.egress_routes))
-        route = plan.egress_routes[0]
-        self.assertIn(route.host, CLAUDE_HOST_CREDENTIAL_HOSTS)
-        self.assertEqual("Bearer", route.auth_scheme)
-        self.assertEqual(CLAUDE_HOST_CREDENTIAL_TOKEN_REF, route.token_ref)
-        self.assertEqual("egress-placeholder", plan.env_vars["CLAUDE_CODE_OAUTH_TOKEN"])
-        self.assertEqual(frozenset({"CLAUDE_CODE_OAUTH_TOKEN"}), plan.hidden_env_names)
-
-    def test_claude_forward_host_credentials_populates_provisioned_env(self):
-        access_token = "sk-ant-oat01-test-key"  # gitleaks:allow
-        with tempfile.TemporaryDirectory(prefix="bb-provider.") as tmp:
-            home = Path(tmp) / "host-claude"
-            cred_dir = home / ".claude"
-            cred_dir.mkdir(parents=True)
-            (cred_dir / ".credentials.json").write_text(json.dumps({
-                "claudeAiOauth": {"accessToken": access_token},
-            }))
-            plan = build_agent_provision_plan(
-                template="claude",
-                dockerfile="",
-                state_dir=Path(tmp),
-                instance_name="bot-bottle-test",
-                prompt_file=Path(tmp) / "prompt.txt",
-                forward_host_credentials=True,
-                host_env={"HOME": str(home)},
-            )
-        self.assertEqual(
-            {CLAUDE_HOST_CREDENTIAL_TOKEN_REF: access_token},
-            plan.provisioned_env,
-        )
-
-    def test_claude_without_forward_host_credentials_has_empty_provisioned_env(self):
-        with tempfile.TemporaryDirectory(prefix="bb-provider.") as tmp:
-            plan = build_agent_provision_plan(
-                template="claude",
-                dockerfile="",
-                state_dir=Path(tmp),
-                instance_name="bot-bottle-test",
-                prompt_file=Path(tmp) / "prompt.txt",
-                forward_host_credentials=False,
-            )
-        self.assertEqual({}, plan.provisioned_env)
-
     def test_pi_plan_writes_default_ollama_models(self):
         with tempfile.TemporaryDirectory(prefix="bb-provider.") as tmp:
             plan = build_agent_provision_plan(

tests/unit/test_backend_util.py

@@ -1,29 +0,0 @@
-"""Unit: shared cross-backend helpers in backend/util.py."""
-
-from __future__ import annotations
-
-import unittest
-from unittest.mock import patch
-
-from bot_bottle.backend import util as backend_util
-
-
-class TestPollCaCert(unittest.TestCase):
-    def test_returns_pem_on_first_success(self) -> None:
-        result = backend_util.poll_ca_cert(lambda: "PEM", timeout=1.0)
-        self.assertEqual("PEM", result)
-
-    def test_raises_timeout_error_when_cert_never_appears(self) -> None:
-        with self.assertRaises(TimeoutError):
-            backend_util.poll_ca_cert(lambda: None, timeout=0.0)
-
-    def test_polls_until_cert_appears(self) -> None:
-        responses = iter([None, None, "-----BEGIN CERTIFICATE-----\n"])
-        with patch("bot_bottle.backend.util.time.sleep") as mock_sleep:
-            result = backend_util.poll_ca_cert(lambda: next(responses), timeout=5.0)
-        self.assertTrue(result.startswith("-----BEGIN CERTIFICATE-----"))
-        self.assertEqual(2, mock_sleep.call_count)
-
-
-if __name__ == "__main__":
-    unittest.main()

tests/unit/test_consolidated_launch.py

@@ -15,7 +15,6 @@ from bot_bottle.git_gate import GitGatePlan
 from bot_bottle.orchestrator.client import RegisteredBottle
 
 _MOD = "bot_bottle.backend.docker.consolidated_launch"
-_UTIL = "bot_bottle.backend.consolidated_util"
 
 
 def _egress_plan() -> EgressPlan:
@@ -50,7 +49,7 @@ class TestLaunchConsolidated(unittest.TestCase):
                 patch(f"{_MOD}._container_ip", return_value="172.18.0.2"), \
                 patch(f"{_MOD}._network_container_ips", return_value=list(on_network)), \
                 patch(f"{_MOD}.OrchestratorClient", return_value=client), \
-                patch(f"{_UTIL}.provision_git_gate", provision or Mock()):
+                patch(f"{_MOD}.provision_git_gate", provision or Mock()):
             return launch_consolidated(_egress_plan(), _git_plan(), service=service)
 
     def test_allocates_ip_registers_and_provisions(self) -> None:
@@ -85,8 +84,8 @@ class TestLaunchConsolidated(unittest.TestCase):
 class TestTeardownConsolidated(unittest.TestCase):
     def test_deregisters_and_deprovisions(self) -> None:
         client = Mock()
-        with patch(f"{_UTIL}.OrchestratorClient", return_value=client), \
-                patch(f"{_UTIL}.deprovision_git_gate") as deprov:
+        with patch(f"{_MOD}.OrchestratorClient", return_value=client), \
+                patch(f"{_MOD}.deprovision_git_gate") as deprov:
             teardown_consolidated("b1", orchestrator_url="http://orch:8080")
         client.teardown_bottle.assert_called_once_with("b1")
         deprov.assert_called_once()

tests/unit/test_contrib_claude_auth.py

@@ -1,186 +0,0 @@
-"""Unit: host Claude auth extraction."""
-
-from __future__ import annotations
-
-import json
-import tempfile
-import unittest
-from datetime import datetime, timezone
-from pathlib import Path
-from unittest.mock import MagicMock, patch
-
-from bot_bottle.contrib.claude.claude_auth import (
-    claude_auth_path,
-    claude_host_access_token,
-)
-from bot_bottle.log import Die
-
-
-def _cred_json(access_token: str, **extra: object) -> str:
-    payload: dict[str, object] = {"claudeAiOauth": {"accessToken": access_token, **extra}}
-    return json.dumps(payload)
-
-
-class TestClaudeHostAccessToken(unittest.TestCase):
-    def setUp(self):
-        self.tmp = tempfile.TemporaryDirectory(prefix="bb-claude-auth.")
-        self.home = Path(self.tmp.name)
-        self.cred_dir = self.home / ".claude"
-        self.cred_dir.mkdir()
-        self.auth_path = self.cred_dir / ".credentials.json"
-
-    def tearDown(self):
-        self.tmp.cleanup()
-
-    def _write(self, payload: dict) -> None:  # type: ignore[no-untyped-def]
-        self.auth_path.write_text(json.dumps(payload))
-
-    def test_auth_path_uses_home_env(self):
-        self.assertEqual(
-            self.auth_path,
-            claude_auth_path({"HOME": str(self.home)}),
-        )
-
-    # --- file-based (Linux) ---
-
-    def test_file_returns_access_token(self):
-        key = "sk-ant-oat01-real-key"  # gitleaks:allow
-        self._write({"claudeAiOauth": {"accessToken": key}})
-        out = claude_host_access_token({"HOME": str(self.home)})
-        self.assertEqual(key, out)
-
-    def test_file_missing_claude_ai_oauth_dies(self):
-        self._write({"hasCompletedOnboarding": True})
-        with self.assertRaises(Die):
-            claude_host_access_token({"HOME": str(self.home)})
-
-    def test_file_missing_access_token_dies(self):
-        self._write({"claudeAiOauth": {"expiresAt": 2000000000000}})
-        with self.assertRaises(Die):
-            claude_host_access_token({"HOME": str(self.home)})
-
-    def test_file_empty_access_token_dies(self):
-        self._write({"claudeAiOauth": {"accessToken": ""}})
-        with self.assertRaises(Die):
-            claude_host_access_token({"HOME": str(self.home)})
-
-    def test_file_expired_token_dies(self):
-        # expiresAt is milliseconds; 1_000_000 ms is year 1970
-        self._write({
-            "claudeAiOauth": {"accessToken": "sk-ant-oat01-x", "expiresAt": 1_000_000},  # gitleaks:allow
-        })
-        with self.assertRaises(Die):
-            claude_host_access_token(
-                {"HOME": str(self.home)},
-                now=datetime(2026, 1, 1, tzinfo=timezone.utc),
-            )
-
-    def test_file_future_expiry_is_accepted(self):
-        key = "sk-ant-oat01-y"  # gitleaks:allow
-        # 2_000_000_000_000 ms ≈ year 2033
-        self._write({
-            "claudeAiOauth": {"accessToken": key, "expiresAt": 2_000_000_000_000},
-        })
-        out = claude_host_access_token(
-            {"HOME": str(self.home)},
-            now=datetime(2026, 1, 1, tzinfo=timezone.utc),
-        )
-        self.assertEqual(key, out)
-
-    def test_file_absent_expiry_is_accepted(self):
-        key = "sk-ant-oat01-z"  # gitleaks:allow
-        self._write({"claudeAiOauth": {"accessToken": key}})
-        out = claude_host_access_token({"HOME": str(self.home)})
-        self.assertEqual(key, out)
-
-    def test_file_non_json_dies(self):
-        self.auth_path.write_text("not json {{{")
-        with self.assertRaises(Die):
-            claude_host_access_token({"HOME": str(self.home)})
-
-    def test_file_json_array_root_dies(self):
-        self.auth_path.write_text("[]")
-        with self.assertRaises(Die):
-            claude_host_access_token({"HOME": str(self.home)})
-
-    def test_file_extra_fields_are_ignored(self):
-        key = "sk-ant-oat01-real"  # gitleaks:allow
-        self._write({
-            "claudeAiOauth": {
-                "accessToken": key,
-                "refreshToken": "sk-ant-ort01-secret",  # gitleaks:allow
-                "scopes": ["user:inference"],
-                "expiresAt": 2_000_000_000_000,
-            },
-        })
-        out = claude_host_access_token({"HOME": str(self.home)})
-        self.assertEqual(key, out)
-
-    # --- macOS Keychain fallback ---
-
-    def _home_without_creds(self) -> Path:
-        """A home dir that has .claude/ but no .credentials.json."""
-        empty = self.home / "no-creds"
-        (empty / ".claude").mkdir(parents=True)
-        return empty
-
-    def _mock_keychain(self, stdout: str, returncode: int = 0) -> MagicMock:
-        mock = MagicMock()
-        mock.returncode = returncode
-        mock.stdout = stdout
-        return mock
-
-    def test_keychain_used_when_file_absent(self):
-        key = "sk-ant-oat01-keychain"  # gitleaks:allow
-        home = self._home_without_creds()
-        with patch(
-            "bot_bottle.contrib.claude.claude_auth.subprocess.run",
-            return_value=self._mock_keychain(_cred_json(key)),
-        ), patch(
-            "bot_bottle.contrib.claude.claude_auth.sys.platform", "darwin",
-        ):
-            out = claude_host_access_token({"HOME": str(home)})
-        self.assertEqual(key, out)
-
-    def test_keychain_failure_when_file_absent_dies(self):
-        home = self._home_without_creds()
-        with patch(
-            "bot_bottle.contrib.claude.claude_auth.subprocess.run",
-            return_value=self._mock_keychain("", returncode=44),
-        ), patch(
-            "bot_bottle.contrib.claude.claude_auth.sys.platform", "darwin",
-        ):
-            with self.assertRaises(Die):
-                claude_host_access_token({"HOME": str(home)})
-
-    def test_no_file_no_keychain_on_linux_dies(self):
-        home = self._home_without_creds()
-        with patch("bot_bottle.contrib.claude.claude_auth.sys.platform", "linux"):
-            with self.assertRaises(Die):
-                claude_host_access_token({"HOME": str(home)})
-
-    def test_keychain_non_json_dies(self):
-        home = self._home_without_creds()
-        with patch(
-            "bot_bottle.contrib.claude.claude_auth.subprocess.run",
-            return_value=self._mock_keychain("not-json"),
-        ), patch(
-            "bot_bottle.contrib.claude.claude_auth.sys.platform", "darwin",
-        ):
-            with self.assertRaises(Die):
-                claude_host_access_token({"HOME": str(home)})
-
-    def test_keychain_security_not_found_dies(self):
-        home = self._home_without_creds()
-        with patch(
-            "bot_bottle.contrib.claude.claude_auth.subprocess.run",
-            side_effect=FileNotFoundError,
-        ), patch(
-            "bot_bottle.contrib.claude.claude_auth.sys.platform", "darwin",
-        ):
-            with self.assertRaises(Die):
-                claude_host_access_token({"HOME": str(home)})
-
-
-if __name__ == "__main__":
-    unittest.main()

tests/unit/test_firecracker_infra_vm.py

@@ -71,16 +71,6 @@ class TestSshGatewayTransport(unittest.TestCase):
             t.exec(["mkdir", "-p", "/git-gate"])
 
 
-class TestGatewayCaPem(unittest.TestCase):
-    def test_dies_when_cert_never_appears(self) -> None:
-        from subprocess import CompletedProcess
-        infra = infra_vm.InfraVm(vm=None, guest_ip="10.0.0.1", private_key=Path("/k"))
-        with patch.object(infra_vm.subprocess, "run",
-                          return_value=CompletedProcess([], 1, stdout="", stderr="")), \
-             self.assertRaises(SystemExit):
-            infra.gateway_ca_pem(timeout=0)
-
-
 class TestRegistryVolume(unittest.TestCase):
     def test_reuses_existing_volume(self):
         import tempfile

tests/unit/test_infra_artifact.py

@@ -96,7 +96,7 @@ class TestVersionInputs(unittest.TestCase):
         (pkg / "app.py").write_text("print('hi')\n")
         (pkg / "egress_entrypoint.sh").write_text("#!/bin/sh\nexec mitmdump\n")
         (pkg / "netpool.defaults.env").write_text("FOO=1\n")
-        for name in ("Dockerfile.orchestrator", "Dockerfile.gateway", "Dockerfile.infra", "Dockerfile.infra.fc"):
+        for name in ("Dockerfile.orchestrator", "Dockerfile.gateway", "Dockerfile.infra"):
             (root / name).write_text(f"FROM scratch  # {name}\n")
         (root / "pyproject.toml").write_text("[project]\nname = 'bot-bottle'\n")
 

tests/unit/test_macos_consolidated_launch.py

@@ -17,7 +17,6 @@ from bot_bottle.git_gate import GitGatePlan
 from bot_bottle.orchestrator.client import RegisteredBottle
 
 _MOD = "bot_bottle.backend.macos_container.consolidated_launch"
-_UTIL = "bot_bottle.backend.consolidated_util"
 
 
 def _egress_plan() -> EgressPlan:
@@ -88,7 +87,7 @@ class TestRegisterAgent(unittest.TestCase):
         *, source_ip: str = "192.168.128.9",
     ):
         with patch(f"{_MOD}.OrchestratorClient", return_value=client), \
-                patch(f"{_UTIL}.provision_git_gate", provision or Mock()), \
+                patch(f"{_MOD}.provision_git_gate", provision or Mock()), \
                 patch(f"{_MOD}.live_source_ips", return_value=[]):
             return register_agent(
                 _egress_plan(), _git_plan(),
@@ -127,8 +126,8 @@ class TestTeardown(unittest.TestCase):
     def test_deregisters_and_deprovisions(self) -> None:
         client = Mock()
         deprovision = Mock()
-        with patch(f"{_UTIL}.OrchestratorClient", return_value=client), \
-                patch(f"{_UTIL}.deprovision_git_gate", deprovision):
+        with patch(f"{_MOD}.OrchestratorClient", return_value=client), \
+                patch(f"{_MOD}.deprovision_git_gate", deprovision):
             teardown_consolidated("b1", orchestrator_url="http://o:8099")
         client.teardown_bottle.assert_called_once_with("b1")
         self.assertEqual("b1", deprovision.call_args.args[1])
@@ -191,7 +190,7 @@ class TestRegisterAgentReconciles(unittest.TestCase):
 
     def _register(self, client: Mock) -> None:
         with patch(f"{_MOD}.OrchestratorClient", return_value=client), \
-                patch(f"{_UTIL}.provision_git_gate"), \
+                patch(f"{_MOD}.provision_git_gate"), \
                 patch(f"{_MOD}.live_source_ips", return_value=["10.0.0.7"]):
             register_agent(
                 _egress_plan(), _git_plan(),
@@ -229,7 +228,7 @@ class TestRegisterAgentReconciles(unittest.TestCase):
         from bot_bottle.backend.macos_container.enumerate import EnumerationError
         client = _client()
         with patch(f"{_MOD}.OrchestratorClient", return_value=client), \
-                patch(f"{_UTIL}.provision_git_gate"), \
+                patch(f"{_MOD}.provision_git_gate"), \
                 patch(f"{_MOD}.live_source_ips",
                       side_effect=EnumerationError("container list failed")):
             register_agent(

tests/unit/test_macos_container_launch_wiring.py

@@ -22,6 +22,7 @@ from bot_bottle.backend.macos_container.launch import (
     _agent_run_argv,
     _identity_proxy_env,
 )
+from bot_bottle.backend.macos_container.rootless_docker import guest_env
 from bot_bottle.manifest import ManifestIndex
 
 _BOTTLE = "bot_bottle.backend.macos_container.bottle"
@@ -76,6 +77,7 @@ def _plan(
         ),
         agent_git_gate_url=agent_git_gate_url,
         agent_supervise_url=agent_supervise_url,
+        docker_access=False,
     ))
 
 
@@ -178,6 +180,18 @@ class TestIdentityTokenDelivery(unittest.TestCase):
         self.assertNotIn("--env", argv)
 
 
+class TestRootlessDockerEnvironment(unittest.TestCase):
+    def test_disabled_bottle_gets_no_docker_environment(self) -> None:
+        self.assertEqual({}, guest_env(False))
+
+    def test_enabled_bottle_uses_only_guest_local_socket(self) -> None:
+        env = guest_env(True)
+        self.assertEqual(
+            "unix:///tmp/bot-bottle-docker-run/docker.sock", env["DOCKER_HOST"],
+        )
+        self.assertNotIn("/var/run/docker.sock", " ".join(env.values()))
+
+
 class TestPlanIdentityToken(unittest.TestCase):
     """git-gate's gitconfig extraHeader and the supervise MCP --header read
     `getattr(plan, "identity_token", "")` at provision time and both bypass the

tests/unit/test_macos_infra.py

@@ -153,14 +153,6 @@ class TestCaCertPem(unittest.TestCase):
         argv = mod.run_container_argv.call_args.args[0]
         self.assertEqual(["container", "exec", "bot-bottle-mac-infra", "cat"], argv[:4])
 
-    def test_raises_gateway_error_when_cert_never_appears(self) -> None:
-        from bot_bottle.backend.macos_container.gateway import GatewayError
-        svc = MacosInfraService(repo_root=Path("/r"))
-        with patch(f"{_INFRA}.container_mod") as mod:
-            mod.run_container_argv.return_value = _fail()
-            with self.assertRaises(GatewayError):
-                svc.ca_cert_pem(timeout=0)
-
 
 class TestProbeControlPlane(unittest.TestCase):
     def test_returns_url_when_running(self) -> None:

tests/unit/test_macos_rootless_docker.py

@@ -0,0 +1,119 @@
+"""Unit coverage for the fail-closed macOS rootless-Docker spike."""
+
+from __future__ import annotations
+
+import unittest
+from dataclasses import dataclass
+from pathlib import Path
+from types import SimpleNamespace
+from typing import cast
+from unittest.mock import patch
+
+from bot_bottle.backend.macos_container import rootless_docker
+from bot_bottle.backend.macos_container import launch as launch_mod
+from bot_bottle.backend.macos_container.bottle_plan import MacosContainerBottlePlan
+
+
+class _Bottle:
+    def __init__(self, results: list[SimpleNamespace]) -> None:
+        self.results = results
+        self.commands: list[str] = []
+
+    def exec(self, command: str) -> SimpleNamespace:
+        self.commands.append(command)
+        return self.results.pop(0)
+
+
+def _result(returncode: int, *, stdout: str = "", stderr: str = "") -> SimpleNamespace:
+    return SimpleNamespace(returncode=returncode, stdout=stdout, stderr=stderr)
+
+
+@dataclass(frozen=True)
+class _AgentProvision:
+    image: str
+
+
+@dataclass(frozen=True)
+class _Plan:
+    slug: str
+    image: str
+    dockerfile_path: str
+    docker_access: bool
+    agent_provision: _AgentProvision
+
+
+class TestRootlessDockerStart(unittest.TestCase):
+    def test_bootstraps_then_waits_for_guest_local_daemon(self) -> None:
+        bottle = _Bottle([_result(0), _result(1), _result(0)])
+        with patch.object(rootless_docker.time, "sleep"):
+            rootless_docker.start(bottle)
+        self.assertIn("rootless-docker-init", bottle.commands[0])
+        self.assertEqual(2, bottle.commands.count("docker info >/dev/null 2>&1"))
+
+    def test_bootstrap_failure_is_fatal_without_privilege_fallback(self) -> None:
+        bottle = _Bottle([_result(1, stderr="newuidmap missing")])
+        with patch.object(rootless_docker, "die", side_effect=RuntimeError) as die:
+            with self.assertRaises(RuntimeError):
+                rootless_docker.start(bottle)
+        self.assertIn("newuidmap missing", die.call_args.args[0])
+        self.assertEqual(1, len(bottle.commands))
+
+    def test_timeout_reports_guest_log(self) -> None:
+        bottle = _Bottle(
+            [_result(0)]
+            + [_result(1) for _ in range(rootless_docker.READY_RETRIES)]
+            + [_result(0, stdout="operation not permitted")]
+        )
+        with patch.object(rootless_docker.time, "sleep"), \
+             patch.object(rootless_docker, "die", side_effect=RuntimeError) as die:
+            with self.assertRaises(RuntimeError):
+                rootless_docker.start(bottle)
+        self.assertIn("operation not permitted", die.call_args.args[0])
+
+
+class TestRootlessDockerImage(unittest.TestCase):
+    def test_layers_tooling_without_changing_base_image(self) -> None:
+        calls: list[tuple[str, str, str]] = []
+
+        def build(image: str, context: str, *, dockerfile: str) -> None:
+            calls.append((image, context, dockerfile))
+            text = Path(dockerfile).read_text(encoding="utf-8")
+            self.assertIn("FROM agent:base", text)
+            self.assertIn("docker.io uidmap rootlesskit slirp4netns", text)
+            self.assertIn("sed -i '/^node:/d' /etc/subuid /etc/subgid", text)
+            self.assertEqual(1, text.count("node:100000:65536\\n' >> /etc/subuid"))
+            self.assertEqual(1, text.count("node:100000:65536\\n' >> /etc/subgid"))
+            self.assertIn("USER node", text)
+            self.assertTrue((Path(context) / "rootless-docker-init.sh").is_file())
+
+        image = rootless_docker.build_image("agent:base", build)
+        self.assertEqual("agent:base-rootless-docker", image)
+        self.assertEqual("agent:base-rootless-docker", calls[0][0])
+
+    def test_launch_builds_base_then_rootless_variant(self) -> None:
+        plan = cast(MacosContainerBottlePlan, cast(object, _Plan(
+            slug="dev-abc",
+            image="agent:base",
+            dockerfile_path="/repo/Dockerfile",
+            docker_access=True,
+            agent_provision=_AgentProvision(image="agent:base"),
+        )))
+        with patch.object(launch_mod, "read_committed_image", return_value=None), \
+             patch.object(launch_mod.container_mod, "build_image") as build, \
+             patch.object(
+                 launch_mod.rootless_docker,
+                 "build_image",
+                 return_value="agent:base-rootless-docker",
+             ) as build_rootless:
+            result = launch_mod._build_images(plan)  # pylint: disable=protected-access
+
+        build.assert_called_once_with(
+            "agent:base", launch_mod._REPO_DIR,  # pylint: disable=protected-access
+            dockerfile="/repo/Dockerfile",
+        )
+        build_rootless.assert_called_once_with("agent:base", build)
+        self.assertEqual("agent:base-rootless-docker", result.agent_provision.image)
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/unit/test_manifest_bottle_merge.py

@@ -56,6 +56,12 @@ class TestMergeBottlesRuntime(unittest.TestCase):
         result = merge_bottles_runtime([base, override])
         self.assertFalse(result.supervise)
 
+    def test_docker_access_later_wins(self):
+        result = merge_bottles_runtime([
+            _bottle(docker_access=False), _bottle(docker_access=True),
+        ])
+        self.assertTrue(result.docker_access)
+
     def test_three_bottles_merged_left_to_right(self):
         b1 = _bottle(env={"A": "1", "B": "1", "C": "1"})
         b2 = _bottle(env={"B": "2", "C": "2"})

tests/unit/test_manifest_egress.py

@@ -80,19 +80,11 @@ class TestAgentProviderHostCredentials(unittest.TestCase):
                 "forward_host_credentials": "yes",
             })
 
-    def test_forward_host_credentials_allowed_for_claude(self):
-        b = _provider_config_bottle({
-            "template": "claude",
-            "forward_host_credentials": True,
-        })
-        self.assertTrue(b.agent_provider.forward_host_credentials)
-
-    def test_forward_host_credentials_and_auth_token_rejected_together(self):
+    def test_forward_host_credentials_rejected_for_claude(self):
         with self.assertRaises(ManifestError):
             _provider_config_bottle({
                 "template": "claude",
                 "forward_host_credentials": True,
-                "auth_token": "SOME_TOKEN",
             })
 
     def test_auth_token_defaults_empty(self):

tests/unit/test_manifest_validation.py

@@ -44,13 +44,20 @@ class TestBottleValidation(unittest.TestCase):
         with self.assertRaises(ManifestError):
             ManifestBottle.from_dict("b", {"supervise": "yes"})
 
+    def test_docker_access_not_bool(self) -> None:
+        with self.assertRaises(ManifestError):
+            ManifestBottle.from_dict("b", {"docker_access": "yes"})
+
     def test_removed_runtime_field(self) -> None:
         with self.assertRaises(ManifestError):
             ManifestBottle.from_dict("b", {"runtime": "runsc"})
 
     def test_valid_minimal(self) -> None:
-        b = ManifestBottle.from_dict("b", {"supervise": False, "env": {"X": "1"}})
+        b = ManifestBottle.from_dict(
+            "b", {"supervise": False, "docker_access": True, "env": {"X": "1"}},
+        )
         self.assertFalse(b.supervise)
+        self.assertTrue(b.docker_access)
         self.assertEqual({"X": "1"}, dict(b.env))
 
 
@@ -86,22 +93,10 @@ class TestAgentProviderValidation(unittest.TestCase):
                 "b", {"forward_host_credentials": True, "template": "weird"}
             )
 
-    def test_forward_creds_pi_template_rejected(self) -> None:
+    def test_forward_creds_non_codex_template(self) -> None:
         with self.assertRaises(ManifestError):
             ManifestAgentProvider.from_dict(
-                "b", {"forward_host_credentials": True, "template": "pi"}
-            )
-
-    def test_forward_creds_claude_allowed(self) -> None:
-        p = ManifestAgentProvider.from_dict(
-            "b", {"forward_host_credentials": True, "template": "claude"}
-        )
-        self.assertTrue(p.forward_host_credentials)
-
-    def test_forward_creds_and_auth_token_rejected(self) -> None:
-        with self.assertRaises(ManifestError):
-            ManifestAgentProvider.from_dict(
-                "b", {"forward_host_credentials": True, "auth_token": "T", "template": "claude"}
+                "b", {"forward_host_credentials": True, "template": "claude"}
             )
 
     def test_valid_claude_auth_token(self) -> None:

tests/unit/test_orchestrator_lifecycle.py

@@ -1,4 +1,4 @@
-"""Unit: infra container lifecycle — idempotent singleton (PRD 0070)."""
+"""Unit: orchestrator+gateway container lifecycle — idempotent singleton (PRD 0070)."""
 
 from __future__ import annotations
 
@@ -8,10 +8,10 @@ import urllib.error
 from pathlib import Path
 from unittest.mock import MagicMock, Mock, patch
 
-from bot_bottle.orchestrator.gateway import GatewayError
 from bot_bottle.orchestrator.lifecycle import (
-    INFRA_NAME,
-    INFRA_SOURCE_HASH_LABEL,
+    ORCHESTRATOR_IMAGE,
+    ORCHESTRATOR_NAME,
+    ORCHESTRATOR_SOURCE_HASH_LABEL,
     OrchestratorService,
     OrchestratorStartError,
     source_hash,
@@ -20,6 +20,7 @@ from tests.unit import use_bottle_root
 
 _URLOPEN = "bot_bottle.orchestrator.lifecycle.urllib.request.urlopen"
 _RUN = "bot_bottle.orchestrator.lifecycle.run_docker"
+_GATEWAY = "bot_bottle.orchestrator.lifecycle.DockerGateway"
 _SLEEP = "bot_bottle.orchestrator.lifecycle.time.sleep"
 _MONOTONIC = "bot_bottle.orchestrator.lifecycle.time.monotonic"
 
@@ -41,8 +42,10 @@ class TestOrchestratorService(unittest.TestCase):
         self.addCleanup(use_bottle_root(Path(self._tmp.name)))
         self.svc = OrchestratorService(port=8099)
 
-    def test_url(self) -> None:
+    def test_urls(self) -> None:
         self.assertEqual("http://127.0.0.1:8099", self.svc.url)
+        # The gateway reaches the control plane by container name over docker DNS.
+        self.assertEqual(f"http://{ORCHESTRATOR_NAME}:8099", self.svc.internal_url)
 
     def test_is_healthy(self) -> None:
         with patch(_URLOPEN, return_value=_health(200)):
@@ -51,169 +54,126 @@ class TestOrchestratorService(unittest.TestCase):
             self.assertFalse(self.svc.is_healthy())
 
     def test_ensure_running_noop_when_healthy_and_source_unchanged(self) -> None:
-        # A healthy container on current source is left alone — recreating it
-        # on every launch drops in-memory egress tokens (#381).
+        # A healthy control plane already running the *current* bind-mounted
+        # source is left alone — recreating it on every launch would drop
+        # every other active bottle's in-memory egress tokens (#381).
         current = source_hash(self.svc._repo_root)
         calls: list[list[str]] = []
 
         def fake(argv: list[str], **_kw: object) -> Mock:
             calls.append(argv)
             if argv[:2] == ["docker", "ps"]:
-                return _proc(stdout=INFRA_NAME)
+                return _proc(stdout=ORCHESTRATOR_NAME)
             if argv[:2] == ["docker", "inspect"]:
                 return _proc(stdout=current)
             return _proc()
 
         with patch(_URLOPEN, return_value=_health(200)), \
-                patch(_RUN, side_effect=fake), patch(_SLEEP):
+                patch(_GATEWAY) as gw_cls, patch(_RUN, side_effect=fake), patch(_SLEEP):
             self.assertEqual(self.svc.url, self.svc.ensure_running())
+        gw_cls.return_value.ensure_running.assert_called()   # gateway kept up
         runs = [c for c in calls if c[:2] == ["docker", "run"]]
-        rms = [c for c in calls if c[:3] == ["docker", "rm", "--force"] and INFRA_NAME in c]
-        self.assertEqual([], runs)
+        rms = [c for c in calls if c[:3] == ["docker", "rm", "--force"] and ORCHESTRATOR_NAME in c]
+        self.assertEqual([], runs)   # not recreated
         self.assertEqual([], rms)
 
     def test_ensure_running_recreates_when_source_changed(self) -> None:
+        # Healthy, but the running container's label doesn't match the
+        # current source hash (a real code change) — recreate so it takes
+        # effect, same as the gateway's image-staleness check.
         calls: list[list[str]] = []
 
         def fake(argv: list[str], **_kw: object) -> Mock:
             calls.append(argv)
             if argv[:2] == ["docker", "ps"]:
-                return _proc(stdout=INFRA_NAME)
+                return _proc(stdout=ORCHESTRATOR_NAME)
             if argv[:2] == ["docker", "inspect"]:
                 return _proc(stdout="stale-hash")
             return _proc()
 
         with patch(_URLOPEN, return_value=_health(200)), \
-                patch(_RUN, side_effect=fake), patch(_SLEEP):
+                patch(_GATEWAY), patch(_RUN, side_effect=fake), patch(_SLEEP):
             self.assertEqual(self.svc.url, self.svc.ensure_running())
         runs = [c for c in calls if c[:2] == ["docker", "run"]]
         self.assertEqual(1, len(runs))
-        self.assertIn(INFRA_NAME, runs[0])
+        self.assertIn(ORCHESTRATOR_NAME, runs[0])
+        # the fresh container is labeled with the current hash, not the stale one
         current = source_hash(self.svc._repo_root)
-        self.assertIn(f"{INFRA_SOURCE_HASH_LABEL}={current}", runs[0])
+        self.assertIn(f"{ORCHESTRATOR_SOURCE_HASH_LABEL}={current}", runs[0])
 
-    def test_ensure_running_starts_infra_container_when_absent(self) -> None:
+    def test_ensure_running_starts_orchestrator_container_when_absent(self) -> None:
         calls: list[list[str]] = []
 
         def fake(argv: list[str], **_kw: object) -> Mock:
             calls.append(argv)
             if argv[:2] == ["docker", "ps"]:
-                return _proc(stdout="")
+                return _proc(stdout="")   # not running
             return _proc()
 
         with patch(_URLOPEN, side_effect=[urllib.error.URLError("down"), _health(200)]), \
-                patch(_RUN, side_effect=fake), patch(_SLEEP):
+                patch(_GATEWAY), patch(_RUN, side_effect=fake), patch(_SLEEP):
             self.assertEqual(self.svc.url, self.svc.ensure_running())
         runs = [c for c in calls if c[:2] == ["docker", "run"]]
         self.assertEqual(1, len(runs))
         argv = runs[0]
-        self.assertIn(INFRA_NAME, argv)
-        # Published on loopback — not exposed on external interfaces.
+        self.assertIn(ORCHESTRATOR_NAME, argv)
+        self.assertIn("--broker", argv)
+        self.assertEqual("stub", argv[argv.index("--broker") + 1])  # register-only, no socket
+        self.assertIn("bot_bottle.orchestrator", argv)
         self.assertEqual("127.0.0.1:8099:8099", argv[argv.index("--publish") + 1])
-        # Both processes in one container — no separate entrypoint override.
-        self.assertNotIn("--entrypoint", argv)
-        # Gateway daemons + orchestrator explicitly opted in.
-        daemons_flag = "BOT_BOTTLE_GATEWAY_DAEMONS=egress,git-http,supervise,orchestrator"
-        self.assertIn("orchestrator", argv[argv.index(daemons_flag)])
 
-    def test_ensure_running_builds_all_images(self) -> None:
+    def test_ensure_running_builds_lean_orchestrator_image_when_missing(self) -> None:
+        # The control plane runs its own lean image (#384), distinct from the
+        # gateway data plane — built from Dockerfile.orchestrator when absent.
         calls: list[list[str]] = []
 
         def fake(argv: list[str], **_kw: object) -> Mock:
             calls.append(argv)
             if argv[:2] == ["docker", "ps"]:
-                return _proc(stdout="")
+                return _proc(stdout="")                 # orchestrator not running
+            if argv[:3] == ["docker", "image", "inspect"]:
+                return _proc(returncode=1)               # image absent -> build
             return _proc()
 
         with patch(_URLOPEN, side_effect=[urllib.error.URLError("down"), _health(200)]), \
-                patch(_RUN, side_effect=fake), patch(_SLEEP):
+                patch(_GATEWAY), patch(_RUN, side_effect=fake), patch(_SLEEP):
             self.svc.ensure_running()
         builds = [c for c in calls if c[:2] == ["docker", "build"]]
-        # Gateway base + orchestrator intermediate + infra image — all three built.
-        self.assertEqual(3, len(builds))
-        dockerfiles = [next(a for a in b if "Dockerfile" in a) for b in builds]
-        self.assertIn("Dockerfile.gateway", dockerfiles[0])
-        self.assertIn("Dockerfile.orchestrator", dockerfiles[1])
-        self.assertIn("Dockerfile.infra", dockerfiles[2])
-        # All three images are distinct.
-        tags = [b[b.index("-t") + 1] for b in builds]
-        self.assertEqual(3, len(set(tags)))
+        self.assertEqual(1, len(builds))
+        self.assertIn(ORCHESTRATOR_IMAGE, builds[0])
+        self.assertTrue(any(a.endswith("Dockerfile.orchestrator") for a in builds[0]))
+        # It is NOT the gateway image/dockerfile — the split is the point.
+        self.assertFalse(any("Dockerfile.gateway" in a for a in builds[0]))
 
-    def test_publish_maps_host_port_to_fixed_internal_port(self) -> None:
-        """A non-default self.port is published to the fixed internal port 8099,
-        not to self.port:self.port — the orchestrator always listens on 8099."""
+    def test_ensure_running_skips_orchestrator_image_build_when_present(self) -> None:
         calls: list[list[str]] = []
 
         def fake(argv: list[str], **_kw: object) -> Mock:
             calls.append(argv)
             if argv[:2] == ["docker", "ps"]:
                 return _proc(stdout="")
+            if argv[:3] == ["docker", "image", "inspect"]:
+                return _proc(returncode=0)               # image present -> no build
             return _proc()
 
-        svc = OrchestratorService(port=20001)
         with patch(_URLOPEN, side_effect=[urllib.error.URLError("down"), _health(200)]), \
-                patch(_RUN, side_effect=fake), patch(_SLEEP):
-            svc.ensure_running()
-        runs = [c for c in calls if c[:2] == ["docker", "run"]]
-        argv = runs[0]
-        self.assertEqual("127.0.0.1:20001:8099", argv[argv.index("--publish") + 1])
-        orch_url = next(a for a in argv if "BOT_BOTTLE_ORCHESTRATOR_URL" in a)
-        self.assertIn(":8099", orch_url)
+                patch(_GATEWAY), patch(_RUN, side_effect=fake), patch(_SLEEP):
+            self.svc.ensure_running()
+        self.assertEqual([], [c for c in calls if c[:2] == ["docker", "build"]])
 
     def test_ensure_running_raises_on_timeout(self) -> None:
         with patch(_URLOPEN, side_effect=urllib.error.URLError("down")), \
-                patch(_RUN, return_value=Mock(returncode=0, stdout="", stderr="")), \
+                patch(_GATEWAY), patch(_RUN, return_value=Mock(returncode=0, stderr="")), \
                 patch(_SLEEP), patch(_MONOTONIC, side_effect=[0.0, 0.5, 2.0]):
             with self.assertRaises(OrchestratorStartError):
                 self.svc.ensure_running(startup_timeout=1.0)
 
-    def test_noop_when_healthy_and_inspect_fails(self) -> None:
-        """If docker inspect fails (e.g. docker daemon hiccup), leave the
-        working container alone rather than churning it."""
-        def fake(argv: list[str], **_kw: object) -> Mock:
-            if argv[:2] == ["docker", "ps"]:
-                return _proc(stdout=INFRA_NAME)
-            if argv[:2] == ["docker", "inspect"]:
-                return _proc(returncode=1, stderr="daemon error")
-            return _proc()
-
-        with patch(_URLOPEN, return_value=_health(200)), \
-                patch(_RUN, side_effect=fake), patch(_SLEEP):
-            self.svc.ensure_running()
-        # no docker run — the working container was left alone
-
-    def test_build_failure_raises(self) -> None:
-        with patch(_URLOPEN, side_effect=urllib.error.URLError("down")), \
-                patch(_RUN, return_value=_proc(returncode=1, stderr="no space left on device")):
-            with self.assertRaises(GatewayError):
-                self.svc.ensure_running()
-
-    def test_ensure_network_creates_if_missing(self) -> None:
-        """If the gateway network doesn't exist yet, create it."""
-        calls: list[list[str]] = []
-
-        def fake(argv: list[str], **_kw: object) -> Mock:
-            calls.append(argv)
-            if argv[:3] == ["docker", "network", "inspect"]:
-                return _proc(returncode=1, stderr="not found")
-            if argv[:2] == ["docker", "ps"]:
-                return _proc(stdout="")
-            return _proc()
-
-        with patch(_URLOPEN, side_effect=[urllib.error.URLError("down"), _health(200)]), \
-                patch(_RUN, side_effect=fake), patch(_SLEEP):
-            self.svc.ensure_running()
-        creates = [c for c in calls if c[:3] == ["docker", "network", "create"]]
-        self.assertEqual(1, len(creates))
-
-    def test_stop_removes_infra_container(self) -> None:
-        with patch(_RUN) as run:
+    def test_stop_removes_orchestrator_and_gateway(self) -> None:
+        with patch(_RUN) as run, patch(_GATEWAY) as gw_cls:
             self.svc.stop()
-        rms = [
-            c.args[0] for c in run.call_args_list
-            if c.args[0][:3] == ["docker", "rm", "--force"]
-        ]
-        self.assertTrue(any(INFRA_NAME in a for a in rms))
+        rms = [c.args[0] for c in run.call_args_list if c.args[0][:3] == ["docker", "rm", "--force"]]
+        self.assertTrue(any(ORCHESTRATOR_NAME in a for a in rms))
+        gw_cls.return_value.stop.assert_called_once()
 
 
 if __name__ == "__main__":