Python
OpenShell setup on a Mac: check Docker Desktop's kernel for Landlock
Rohit C Prasad12f757f30bd2
diff --git a/coworker/sandbox/providers/openshell.py b/coworker/sandbox/providers/openshell.pyindex 6c8e9938..93d76df7 100644--- a/coworker/sandbox/providers/openshell.py+++ b/coworker/sandbox/providers/openshell.py@@ -292,6 +292,13 @@ class OpenShellProvider:log.warning("sandbox create failed for %s: %s", self.sandbox_name, exc)if "bind" in str(exc).lower() and "enable" in str(exc).lower():raise OpenShellUnavailable("The OpenShell gateway does not allow bind mounts, so it cannot give a sandbox your folders. Set `enable_bind_mounts = true` under `[openshell.drivers.docker]` in the gateway config (`openworker machine sandbox setup` does this).") from exc+ if "ContainerExited" in str(exc) and sys.platform == "darwin":+ # The container's own log says why; the CLI does not. The usual reason on a+ # Mac is a Docker Desktop kernel without Landlock, which can be asked.+ from ..setup_cmd import DOCKER_LANDLOCK_FIX, docker_landlock++ if docker_landlock() is False:+ raise OpenShellUnavailable(f"{DOCKER_LANDLOCK_FIX}. Then start the session again.") from excraiseself._wait_ready()# Spike finding K: the first exec after a sandbox turns Ready hangs until it timesdiff --git a/coworker/sandbox/setup_cmd.py b/coworker/sandbox/setup_cmd.pyindex a756bee2..82e6eb12 100644--- a/coworker/sandbox/setup_cmd.py+++ b/coworker/sandbox/setup_cmd.py@@ -34,7 +34,7 @@ from pathlib import Pathfrom typing import Any, Callable, Optionalfrom .. import config as app_config-from .providers import openshell+from .providers import openshell, openshell_policyfrom .providers.openshell import PINNED_VERSIONfrom .selection import openshell_problem, select@@ -42,6 +42,10 @@ _INSTALLER = "https://raw.githubusercontent.com/NVIDIA/OpenShell/main/install.sh# Where the page's "Guide" links point: how OpenShell fits, what a machine needs, setup.GUIDE_URL = "https://github.com/andrewyng/openworker/blob/main/docs/openshell.md"DOCKER_INSTALL_URL = "https://docs.docker.com/engine/install/"+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"_BIND_MOUNTS = "[openshell.drivers.docker]\nenable_bind_mounts = true\n"# The base image is pulled by the first `sandbox create` otherwise, which on a slow link# outlives the create's timeout and hangs the first session (OPE-205). So it is a check of@@ -60,6 +64,7 @@ ROWS = {"gateway": "the gateway is running","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)","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,@@ -142,6 +147,29 @@ def landlock_available() -> Optional[bool]:return None+_LANDLOCK_PROBE = "import ctypes; print(ctypes.CDLL(None, use_errno=True).syscall(444, None, 0, 1))"+++def docker_landlock() -> Optional[bool]:+ """On a Mac: whether Docker Desktop's Linux VM has Landlock, asked from a throwaway+ container of the base image (no network), the same call as `landlock_available`.+ None when it cannot be asked: not a Mac, Docker not answering, or the base image not+ downloaded yet (it is checked again after the download)."""+ if sys.platform != "darwin" or not shutil.which("docker"):+ return None+ image = openshell.sandbox_image()+ if _run(["docker", "image", "inspect", image], 30).returncode != 0:+ return None+ done = _run(+ ["docker", "run", "--rm", "--network", "none", "--security-opt", "seccomp=unconfined", "--entrypoint", openshell_policy.PYTHON, image, "-c", _LANDLOCK_PROBE],+ 90,+ ) # fmt: skip+ try:+ return int((done.stdout.split() or [""])[-1]) >= 0+ except ValueError:+ return None++def image_store_free_gb() -> Optional[float]:"""Free space where the driver keeps images, in GB, or None when it cannot be told."""try:@@ -163,6 +191,10 @@ def steps() -> list[Step]:docker = shutil.which("docker")docker_ok = bool(docker) and _run(["docker", "info", "--format", "{{.ServerVersion}}"], 30).returncode == 0out.append(Step("docker", ROWS["docker"], docker_ok, "" if docker_ok else "install Docker, then add this user to the `docker` group and log in again", docs="" if docker_ok else DOCKER_INSTALL_URL))+ if docker_ok:+ 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))exe = shutil.which("openshell")version = (_run([exe, "--version"], 15).stdout.split() or [""])[-1] if exe else ""openshell_ok = version == PINNED_VERSIONdiff --git a/docs/openshell.md b/docs/openshell.mdindex 2323deea..dbdd08ca 100644--- a/docs/openshell.md+++ b/docs/openshell.md@@ -187,6 +187,10 @@ enabled = truecannot be used right now. Run `openworker machine sandbox status` for the reason; theusual ones are the gateway not running, bind mounts not allowed, or the base image notdownloaded yet.+- **"Update Docker Desktop: this version's Linux kernel has no Landlock"** (a Mac) — OpenShell+ requires Landlock, and older Docker Desktop kernels are built without it (engine 28.0.4,+ kernel 6.10 had none; engine 29.8, kernel 7.0 has it). Update Docker Desktop, then check+ again. Setup asks Docker's kernel directly once the base image is downloaded.- **"The sandbox base image is not downloaded yet"** — the one-time 5 GB download hasnot happened. Run `openworker machine sandbox setup` and accept the download, or run the`docker pull` command from the message; then start the session again.diff --git a/surfaces/gui/src/components/SandboxSection.tsx b/surfaces/gui/src/components/SandboxSection.tsxindex 4e1c8eb6..751e670d 100644--- a/surfaces/gui/src/components/SandboxSection.tsx+++ b/surfaces/gui/src/components/SandboxSection.tsx@@ -1043,10 +1043,12 @@ function OpenShellDialog({const byKey = (key: string) => rows.find((r) => r.key === key);const good = (r?: Row) => Boolean(r) && (r!.state ? r!.state === "ok" || r!.state === "fixed" : r!.ok);const docker = byKey("docker");+ const kernel = byKey("docker_landlock"); // a Mac: does Docker Desktop's Linux kernel have Landlockconst openshell = byKey("openshell");- const rest = rows.filter((r) => r.key !== "docker" && r.key !== "openshell");+ const rest = rows.filter((r) => r.key !== "docker" && r.key !== "docker_landlock" && r.key !== "openshell");const blocked = rest.find((r) => r.state === "needs_you" || r.state === "failed");- const checksOk = good(docker) && good(openshell);+ const dockerOk = good(docker) && (!kernel || good(kernel));+ const checksOk = dockerOk && good(openshell);const allOk = rows.length > 0 && rows.every((r) => good(r));const done = job?.status === "done" || (!job && ready && allOk);const mark = (r?: Row): RowState => (!r ? "wait" : good(r) ? "ok" : "bad");@@ -1105,9 +1107,17 @@ function OpenShellDialog({<ul className="rounded-lg border border-line divide-y divide-line" data-testid="sandbox-readiness">{line("docker",- mark(docker),+ !docker ? "wait" : dockerOk ? "ok" : "bad",t(mac ? "settingsx.sandbox.os_row_docker_mac" : "settingsx.sandbox.os_row_docker"),- docker && !good(docker) ? (+ docker && good(docker) && kernel && !good(kernel) ? (+ <span className="block text-meta text-muted mt-0.5" data-testid="sandbox-setup-landlock">+ <span className="block">+ {t("settingsx.sandbox.os_docker_update")}{" "}+ {link(kernel.docs || "https://docs.docker.com/desktop/setup/install/mac-install/", t("settingsx.sandbox.get_docker_mac"), "sandbox-setup-docs-landlock")}+ </span>+ <span className="block">{t("settingsx.sandbox.os_docker_update_why")}</span>+ </span>+ ) : docker && !good(docker) ? (<span className="block text-meta text-muted mt-0.5">{t(mac ? "settingsx.sandbox.os_docker_fix_mac" : "settingsx.sandbox.os_docker_fix")}{" "}{docker.docs ? link(docker.docs, t(mac ? "settingsx.sandbox.get_docker_mac" : "settingsx.sandbox.get_docker"), "sandbox-setup-docs-docker") : null}diff --git a/surfaces/gui/src/components/SettingsView.sandbox.test.tsx b/surfaces/gui/src/components/SettingsView.sandbox.test.tsxindex 4363f4c2..33c0112c 100644--- a/surfaces/gui/src/components/SettingsView.sandbox.test.tsx+++ b/surfaces/gui/src/components/SettingsView.sandbox.test.tsx@@ -162,6 +162,34 @@ describe("Settings ▸ Sandbox", () => {expect(screen.queryByTestId("sandbox-openshell-dialog")).toBeNull();});+ it("OpenShell on a Mac whose Docker Desktop kernel lacks Landlock: update Docker Desktop, then the reason", async () => {+ snapshot = { ...base, platform: "darwin", providers: [{ name: "direct", usable: true, why: "" }, { name: "seatbelt", usable: true, why: "" }, { name: "openshell", usable: false, why: "", state: "unavailable" }] };+ readinessNow = {+ ...readiness,+ steps: [+ { ...readiness.steps[0], ok: true },+ { key: "docker_landlock", what: "Docker Desktop's Linux kernel supports Landlock", ok: false, hint: "Update Docker Desktop", fixable: false, command: "", docs: "https://docs.docker.com/desktop/setup/install/mac-install/" },+ { ...readiness.steps[1], ok: true },+ { ...readiness.steps[2], ok: true },+ readiness.steps[3],+ ],+ };+ render(<SettingsView initialTab="sandbox" />);+ await screen.findByTestId("sandbox-section");+ fireEvent.click(masterSwitch());+ fireEvent.click(screen.getByTestId("sandbox-setup-openshell"));+ await screen.findByTestId("sandbox-setup-landlock");+ const dialog = screen.getByTestId("sandbox-openshell-dialog");+ expect(dialog.querySelectorAll("li").length).toBe(3); // still three rows: the kernel folds into Docker's+ expect(screen.getByTestId("sandbox-setup-row-docker").getAttribute("data-state")).toBe("bad");+ const lines = screen.getByTestId("sandbox-setup-landlock").children;+ expect(lines[0].textContent).toBe("Update Docker Desktop, then check again. Get Docker Desktop");+ expect(lines[1].textContent).toBe("This version's Linux kernel has no Landlock, which OpenShell needs.");+ expect((screen.getByTestId("sandbox-setup-docs-landlock") as HTMLAnchorElement).href).toBe("https://docs.docker.com/desktop/setup/install/mac-install/");+ expect(screen.queryByTestId("sandbox-setup-start")).toBeNull(); // Check again, not Set up+ expect(screen.getByTestId("sandbox-setup-check")).toBeTruthy();+ });+it("OpenShell: both checks pass, Set up runs; the rows stay and the third shows the download", async () => {snapshot = { ...base, platform: "darwin", providers: [{ name: "direct", usable: true, why: "" }, { name: "seatbelt", usable: true, why: "" }, { name: "openshell", usable: false, why: "", state: "needs_download" }] };readinessNow = { ...readiness, steps: [{ ...readiness.steps[0], ok: true }, { ...readiness.steps[1], ok: true }, { ...readiness.steps[2], ok: true }, readiness.steps[3]] };diff --git a/surfaces/gui/src/locales/en.json b/surfaces/gui/src/locales/en.jsonindex cee5e13d..367678f3 100644--- a/surfaces/gui/src/locales/en.json+++ b/surfaces/gui/src/locales/en.json@@ -2453,7 +2453,9 @@"sites_placeholder": "A site, for example api.example.com","sites_sum": "{{list}}.","sites_title": "Allowed sites",- "sites_total": "{{count}} allowed"+ "sites_total": "{{count}} allowed",+ "os_docker_update": "Update Docker Desktop, then check again.",+ "os_docker_update_why": "This version's Linux kernel has no Landlock, which OpenShell needs."}},"misc": {diff --git a/surfaces/gui/src/locales/zh.json b/surfaces/gui/src/locales/zh.jsonindex d86df862..dc3b6532 100644--- a/surfaces/gui/src/locales/zh.json+++ b/surfaces/gui/src/locales/zh.json@@ -2413,7 +2413,9 @@"sites_placeholder": "网站,例如 api.example.com","sites_sum": "{{list}}。","sites_title": "允许的网站",- "sites_total": "已允许 {{count}} 个"+ "sites_total": "已允许 {{count}} 个",+ "os_docker_update": "请更新 Docker Desktop,然后重新检查。",+ "os_docker_update_why": "此版本的 Linux 内核没有 Landlock,而 OpenShell 需要它。"}},"misc": {diff --git a/tests/test_sandbox_openshell.py b/tests/test_sandbox_openshell.pyindex 78228d6a..b1f85096 100644--- a/tests/test_sandbox_openshell.py+++ b/tests/test_sandbox_openshell.py@@ -426,3 +426,24 @@ def test_credential_grants_are_copied_into_a_real_sandbox(folder):finally:ws.close()assert not Path(copy).exists() # the copies died with the sandbox+++def test_a_mac_whose_docker_kernel_lacks_landlock_is_told_to_update_docker_desktop(tmp_path, monkeypatch):+ """The CLI only says ContainerExited; the reason is in the container's log. On a Mac the+ usual one is Docker Desktop's kernel without Landlock, which the probe can confirm."""+ from coworker.sandbox import setup_cmd+ from coworker.sandbox.providers import openshell as os_mod++ def fail(*args, **kwargs):+ raise RuntimeError("`openshell sandbox create --name` failed: Error: sandbox entered error phase while provisioning: ContainerExited: Container exited")++ monkeypatch.setattr(os_mod, "preflight", lambda: {"version": os_mod.PINNED_VERSION})+ monkeypatch.setattr(os_mod, "_cli", fail)+ monkeypatch.setattr(os_mod.sys, "platform", "darwin")+ monkeypatch.setattr(setup_cmd, "docker_landlock", lambda: False)+ provider = os_mod.OpenShellProvider(roots=[{"path": str(tmp_path), "writable": True}], cwd=str(tmp_path))+ with pytest.raises(os_mod.OpenShellUnavailable, match="Update Docker Desktop"):+ provider._create()+ monkeypatch.setattr(setup_cmd, "docker_landlock", lambda: True) # another reason: the CLI's own words+ with pytest.raises(RuntimeError, match="ContainerExited"):+ provider._create()diff --git a/tests/test_sandbox_setup_job.py b/tests/test_sandbox_setup_job.pyindex 261cbf90..ea0687e7 100644--- a/tests/test_sandbox_setup_job.py+++ b/tests/test_sandbox_setup_job.py@@ -269,3 +269,38 @@ def test_the_folder_step_restarts_the_gateway_and_the_check_reads_the_config_in_monkeypatch.setattr(setup_cmd.sys, "platform", "linux")ran.clear()assert setup_cmd.restart_gateway() is None and ran == [["systemctl", "--user", "restart", "openshell-gateway"]]+++def test_on_a_mac_the_docker_kernel_is_asked_for_landlock(monkeypatch):+ """Docker Desktop 28.0.4 (kernel 6.10.14-linuxkit) has no Landlock and every OpenShell+ sandbox exited at start (2026-09-28); 29.8.1 (7.0.14) has it."""+ from types import SimpleNamespace++ answers = {"probe": "-1\n", "image": 0}++ def fake_run(argv, timeout=600):+ if argv[:3] == ["docker", "image", "inspect"]:+ return SimpleNamespace(returncode=answers["image"], stdout="", stderr="")+ if argv[:2] == ["docker", "run"]:+ assert "--network" in argv and "none" in argv # a throwaway probe, no network+ return SimpleNamespace(returncode=0, stdout=answers["probe"], stderr="")+ return SimpleNamespace(returncode=0, stdout="", stderr="")++ 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}")+ assert setup_cmd.docker_landlock() is False+ answers["probe"] = "8\n"+ assert setup_cmd.docker_landlock() is True+ answers["image"] = 1 # the base image is not here yet: cannot ask, no row+ assert setup_cmd.docker_landlock() is None+ monkeypatch.setattr(setup_cmd.sys, "platform", "linux")+ assert setup_cmd.docker_landlock() is None # Linux asks its own kernel (the `landlock` row)+ # In the checklist: a row right after Docker, with what to do.+ monkeypatch.setattr(setup_cmd.sys, "platform", "darwin")+ monkeypatch.setattr(setup_cmd, "docker_landlock", lambda: False)+ monkeypatch.setattr(setup_cmd, "openshell_problem", lambda fresh=False: "OpenShell is not installed")+ keys = [s.key for s in setup_cmd.steps()]+ row = {s.key: s for s in setup_cmd.steps()}["docker_landlock"]+ assert keys[:2] == ["docker", "docker_landlock"] and not row.ok and not row.fixable+ assert row.hint.startswith("Update Docker Desktop") and row.docs == setup_cmd.DOCKER_DESKTOP_URL