Skip to content
Python

OpenShell 0.1.2 on a Mac: check Docker Desktop's host networking and say where to turn it on

Rohit C Prasad5258cfc82af2
diff --git a/coworker/sandbox/providers/openshell.py b/coworker/sandbox/providers/openshell.py
index 51dcc525..38b7e29c 100644
--- a/coworker/sandbox/providers/openshell.py
+++ b/coworker/sandbox/providers/openshell.py
@@ -370,6 +370,13 @@ class OpenShellProvider:
if docker_landlock() is False:
raise OpenShellUnavailable(f"{DOCKER_LANDLOCK_FIX}. Then start the session again.") from exc
+ if "failed to connect to OpenShell server" in str(exc) and sys.platform == "darwin":
+ # The sandbox's helper could not reach the gateway: on a Mac that is Docker
+ # Desktop's host networking being off, which can be asked.
+ from ..setup_cmd import DOCKER_HOST_NETWORK_FIX, docker_host_network
+
+ if docker_host_network() is False:
+ raise OpenShellUnavailable(f"{DOCKER_HOST_NETWORK_FIX}. Then start the session again.") from exc
raise
self._wait_ready()
self._denials = DenialLog(self.sandbox_name) # what it refuses, for the agent and the card
diff --git a/coworker/sandbox/setup_cmd.py b/coworker/sandbox/setup_cmd.py
index d094597f..77cb33e6 100644
--- a/coworker/sandbox/setup_cmd.py
+++ b/coworker/sandbox/setup_cmd.py
@@ -26,6 +26,7 @@ import ctypes
import getpass
import os
import shutil
+import socket
import subprocess
import sys
import threading
@@ -51,6 +52,15 @@ DOCKER_DESKTOP_URL = "https://docs.docker.com/desktop/setup/install/mac-install/
# What a Mac user is told when Docker Desktop's Linux kernel lacks Landlock (engine 28.0.4,
# kernel 6.10.14-linuxkit, seen 2026-09-28; engine 29.8.1, kernel 7.0.14, has it).
DOCKER_LANDLOCK_FIX = "Update Docker Desktop: this version's Linux kernel has no Landlock, which OpenShell needs"
+# OpenShell 0.1 starts each sandbox with a helper on Docker's host network, which reaches
+# the gateway on this Mac's own loopback address. Docker Desktop only lets a container do
+# that when this setting is on, and it is off until someone ticks it (seen 2026-10-04,
+# Docker Desktop 4.93: every sandbox failed with "failed to connect to OpenShell server").
+DOCKER_HOST_NETWORK_FIX = (
+ 'Turn on host networking in Docker Desktop: Settings > Resources > Network > "Enable host networking", '
+ "then Apply & restart. OpenShell's sandboxes reach its gateway that way"
+)
+DOCKER_HOST_NETWORK_URL = "https://docs.docker.com/engine/network/drivers/host/#docker-desktop"
# The gateway settings that let a sandbox be given the session's folders (OpenShell 0.1:
# config schema 2; driver config and bind mounts are both off until switched on, and a
# bind mount is refused while resource admission is on). All three, or `sandbox create`
@@ -78,6 +88,7 @@ ROWS = {
"grpcio": "the `grpcio` package is installed",
"landlock": "the kernel supports Landlock (OpenShell requires it)",
"docker_landlock": "Docker Desktop's Linux kernel supports Landlock (OpenShell requires it)",
+ "docker_host_network": "Docker Desktop's host networking is on (OpenShell's sandboxes reach the gateway that way)",
"config": "this machine is set to use OpenShell",
"disk": f"enough free disk space for the base image (about {IMAGE_FREE_GB} GB)",
"image": IMAGE_ROW,
@@ -183,6 +194,27 @@ def docker_landlock() -> Optional[bool]:
return None
+def docker_host_network() -> Optional[bool]:
+ """On a Mac: whether a container on Docker's host network reaches the gateway on this
+ Mac's loopback address, tried from a throwaway container of the base image. None when
+ it cannot be told: not a Mac, Docker not answering, the base image not downloaded yet,
+ or no gateway listening to be reached."""
+ if sys.platform != "darwin" or not shutil.which("docker"):
+ return None
+ try:
+ port = int(openshell._gateway()[0].rsplit(":", 1)[1])
+ with socket.create_connection(("127.0.0.1", port), timeout=3):
+ pass
+ except (OSError, ValueError, IndexError, KeyError):
+ return None
+ image = openshell.sandbox_image()
+ if _run(["docker", "image", "inspect", image], 30).returncode != 0:
+ return None
+ probe = f"import socket; socket.create_connection(('127.0.0.1', {port}), 4).close()"
+ done = _run(["docker", "run", "--rm", "--network", "host", "--entrypoint", openshell_policy.PYTHON, image, "-c", probe], 90)
+ return done.returncode == 0
+
+
def image_store_free_gb() -> Optional[float]:
"""Free space where the driver keeps images, in GB, or None when it cannot be told."""
try:
@@ -208,6 +240,9 @@ def steps() -> list[Step]:
kernel = docker_landlock()
if kernel is not None:
out.append(Step("docker_landlock", ROWS["docker_landlock"], kernel, "" if kernel else DOCKER_LANDLOCK_FIX, docs="" if kernel else DOCKER_DESKTOP_URL))
+ reaches = docker_host_network()
+ if reaches is not None:
+ out.append(Step("docker_host_network", ROWS["docker_host_network"], reaches, "" if reaches else DOCKER_HOST_NETWORK_FIX, docs="" if reaches else DOCKER_HOST_NETWORK_URL))
exe = shutil.which("openshell")
version = (_run([exe, "--version"], 15).stdout.split() or [""])[-1] if exe else ""
openshell_ok = version == PINNED_VERSION
diff --git a/tests/test_sandbox_openshell.py b/tests/test_sandbox_openshell.py
index eee10f88..1a54661f 100644
--- a/tests/test_sandbox_openshell.py
+++ b/tests/test_sandbox_openshell.py
@@ -563,6 +563,19 @@ def test_a_mac_whose_docker_kernel_lacks_landlock_is_told_to_update_docker_deskt
with pytest.raises(RuntimeError, match="ContainerExited"):
provider._create()
+ # OpenShell 0.1 on a Mac: the sandbox could not reach the gateway because Docker
+ # Desktop's host networking is off.
+ def unreachable(*args, **kwargs):
+ raise RuntimeError("`openshell sandbox create --name` failed: Startup configuration fetch failed after 5 attempts: failed to connect to OpenShell server")
+
+ monkeypatch.setattr(os_mod, "_cli", unreachable)
+ monkeypatch.setattr(setup_cmd, "docker_host_network", lambda: False)
+ with pytest.raises(os_mod.OpenShellUnavailable, match="Enable host networking"):
+ provider._create()
+ monkeypatch.setattr(setup_cmd, "docker_host_network", lambda: True)
+ with pytest.raises(RuntimeError, match="failed to connect to OpenShell server"):
+ provider._create()
+
def test_only_the_runner_is_mounted_into_a_sandbox(tmp_path, monkeypatch):
# The registry (every session's ids, coworkers and folders) sat beside the runner in
diff --git a/tests/test_sandbox_setup_job.py b/tests/test_sandbox_setup_job.py
index 865561c4..385286a6 100644
--- a/tests/test_sandbox_setup_job.py
+++ b/tests/test_sandbox_setup_job.py
@@ -332,3 +332,57 @@ def test_a_gateway_config_with_other_settings_is_not_rewritten(tmp_path, monkeyp
assert said and "by hand" in said and "allow_driver_config = true" in said
assert "compute_driver" in theirs.read_text() and "enable_bind_mounts" not in theirs.read_text()
+
+def test_a_mac_is_asked_whether_docker_desktops_host_networking_is_on(monkeypatch):
+ """OpenShell 0.1 reaches its gateway from a host-network container; Docker Desktop
+ has that off until it is ticked."""
+ from pathlib import Path
+ from types import SimpleNamespace
+
+ ran: list[list[str]] = []
+ answers = {"image": 0, "probe": 1}
+
+ def fake_run(argv, timeout=600):
+ ran.append(list(argv))
+ if argv[:3] == ["docker", "image", "inspect"]:
+ return SimpleNamespace(returncode=answers["image"], stdout="", stderr="")
+ if argv[:2] == ["docker", "run"]:
+ assert argv[argv.index("--network") + 1] == "host"
+ return SimpleNamespace(returncode=answers["probe"], stdout="", stderr="")
+ return SimpleNamespace(returncode=0, stdout="", stderr="")
+
+ class Listening:
+ def __enter__(self):
+ return self
+
+ def __exit__(self, *_a):
+ return False
+
+ monkeypatch.setattr(setup_cmd, "_run", fake_run)
+ monkeypatch.setattr(setup_cmd.sys, "platform", "darwin")
+ monkeypatch.setattr(setup_cmd.shutil, "which", lambda name: f"/usr/local/bin/{name}")
+ monkeypatch.setattr(setup_cmd.openshell, "_gateway", lambda: ("localhost:17670", Path("/nowhere")))
+ monkeypatch.setattr(setup_cmd.socket, "create_connection", lambda *_a, **_k: Listening())
+ assert setup_cmd.docker_host_network() is False # the container could not reach it
+ answers["probe"] = 0
+ assert setup_cmd.docker_host_network() is True
+ answers["image"] = 1 # no base image yet: cannot ask
+ assert setup_cmd.docker_host_network() is None
+
+ def refused(*_a, **_k):
+ raise OSError("connection refused")
+
+ answers["image"] = 0
+ monkeypatch.setattr(setup_cmd.socket, "create_connection", refused)
+ assert setup_cmd.docker_host_network() is None # no gateway to reach: that is another row
+ monkeypatch.setattr(setup_cmd.sys, "platform", "linux")
+ assert setup_cmd.docker_host_network() is None # Docker Engine on Linux has host networking
+
+ # In the checklist: its own row, with where the setting is.
+ monkeypatch.setattr(setup_cmd.sys, "platform", "darwin")
+ monkeypatch.setattr(setup_cmd, "docker_landlock", lambda: True)
+ monkeypatch.setattr(setup_cmd, "docker_host_network", lambda: False)
+ monkeypatch.setattr(setup_cmd, "openshell_problem", lambda fresh=False: "OpenShell is not installed")
+ row = {s.key: s for s in setup_cmd.steps()}["docker_host_network"]
+ assert not row.ok and not row.fixable and "Enable host networking" in row.hint and row.docs == setup_cmd.DOCKER_HOST_NETWORK_URL
+