Skip to content
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.py
index 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 exc
raise
self._wait_ready()
# Spike finding K: the first exec after a sandbox turns Ready hangs until it times
diff --git a/coworker/sandbox/setup_cmd.py b/coworker/sandbox/setup_cmd.py
index a756bee2..82e6eb12 100644
--- a/coworker/sandbox/setup_cmd.py
+++ b/coworker/sandbox/setup_cmd.py
@@ -34,7 +34,7 @@ from pathlib import Path
from typing import Any, Callable, Optional
from .. import config as app_config
-from .providers import openshell
+from .providers import openshell, openshell_policy
from .providers.openshell import PINNED_VERSION
from .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 == 0
out.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_VERSION
diff --git a/docs/openshell.md b/docs/openshell.md
index 2323deea..dbdd08ca 100644
--- a/docs/openshell.md
+++ b/docs/openshell.md
@@ -187,6 +187,10 @@ enabled = true
cannot be used right now. Run `openworker machine sandbox status` for the reason; the
usual ones are the gateway not running, bind mounts not allowed, or the base image not
downloaded 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 has
not 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.tsx
index 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 Landlock
const 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.tsx
index 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.json
index 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.json
index 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.py
index 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.py
index 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