feat(macos): spike rootless Docker inside bottles

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.

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/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_rootless_docker.py

@@ -0,0 +1,74 @@
+"""Unit coverage for the fail-closed macOS rootless-Docker spike."""
+
+from __future__ import annotations
+
+import unittest
+from pathlib import Path
+from types import SimpleNamespace
+from unittest.mock import patch
+
+from bot_bottle.backend.macos_container import rootless_docker
+
+
+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)
+
+
+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("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])
+
+
+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_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))