bug: `openshell doctor check` doesn't verify Docker Desktop prerequisites (Landlock kernel, host networking)

[tech4242]

User Story

I'm trying OpenShell on my Mac (Apple Silicon, Docker Desktop) because I'm looking at adding aquaman, a credential isolation proxy I maintain, as an external credential driver. openshell doctor check passed on every setup I tried, but openshell sandbox create failed on two of them, with errors that don't name the missing prerequisite.

Problem Statement

doctor check only verifies that Docker responds. It doesn't check the documented Docker Desktop prerequisites, a Landlock ABI 3+ kernel in the Docker VM and host networking enabled, so it reports "All checks passed" on setups where every sandbox fails.

Landlock example, Docker Desktop 4.55.0 (VM kernel 6.12.54-linuxkit, # CONFIG_SECURITY_LANDLOCK is not set):

Error:   × fully incompatible access-rights: BitFlags<AccessFs>(...)
Error:   × Landlock allow/deny probe
  ╰─▶ Landlock probe child exited with status exit status: 1

The error doesn't say that the kernel has Landlock disabled or point to the Kernel Requirements.

Host networking: on Docker Desktop 4.93.0 with host networking off, startup fails with failed to connect to OpenShell server, and enabling host networking fixes it. That case and its error message are covered in #3880, so I'm only listing it here as a second prerequisite doctor could check.

In all of these setups doctor check printed:

Docker ............. ok
DOCKER_HOST ........ (not set, using default socket)

All checks passed.

Impact / Why This Matters

macOS with Docker Desktop is the documented path for Mac users. Older Docker Desktop versions can never meet the Landlock requirement and host networking is off by default, so a new user gets a green doctor and then a startup error that takes kernel config or network debugging to explain. Docker Desktop's kernel can't be replaced on macOS, so updating Docker Desktop is the only fix for the Landlock case, and nothing tells the user that.

Acceptance Criteria

• doctor check fails with a clear message when the Docker VM kernel lacks Landlock ABI 3+.
• doctor check fails with a clear message when Docker Desktop host networking is off.
• The Landlock baseline startup error says the kernel has Landlock disabled or too old and links to the Kernel Requirements.
• The support matrix names a minimum Docker Desktop version for macOS (4.55.0 has no Landlock, 4.93.0 has it).

Reproduction Steps

1. macOS on Apple Silicon with Docker Desktop 4.55.0.
2. Start a gateway with the Docker compute driver.
3. Run openshell doctor check: all checks passed.
4. Run openshell sandbox create --name demo -- true: fails with the Landlock error above.

Suggested UX (if applicable)

openshell doctor check

  Docker ............. ok (version 29.1.3)
  DOCKER_HOST ........ (not set, using default socket)
  Landlock ........... FAILED (disabled in the Docker VM kernel 6.12.54-linuxkit; ABI 3+ required)
  Host networking .... ok

1 check failed. See https://docs.nvidia.com/openshell/latest/about/support-matrix#kernel-requirements

Environment

• OpenShell 0.1.2 (CLI and standalone gateway from the GitHub release), Docker compute driver
• macOS 26.4.1 (25E253), Apple Silicon
• Docker Desktop 4.55.0 (engine 29.1.3, kernel 6.12.54-linuxkit) and 4.93.0 (engine 29.8.1, kernel 7.0.14-linuxkit)

Logs

Error:   × sandbox entered error phase while provisioning:
  │ ControlSupervisorStartFailed: Docker sandbox exited before supervisor
  │ became ready; sandbox log tail: Error:   × fully incompatible access-
  │ rights: BitFlags<AccessFs>(0b111111111111111, ...)
  │ Error:   × Landlock allow/deny probe
  │   ╰─▶ Landlock probe child exited with status exit status: 1

[tech4242]

I'd like to work on this (vouch request: #4128). I'd start with the doctor checks and the Landlock startup error, and coordinate with #3880 / #3924 on the networking side.

[O96a]

doctor is probing the Mac, not the VM the sandbox actually runs in — on Docker Desktop for macOS every container runs inside a Linux VM with Docker's linuxkit kernel, so any check that reads the host kernel or host network stack is answering a question nobody asked. Both prerequisites need to be tested from inside the runtime:

# Landlock: is the LSM even in the VM kernel?
docker run --rm alpine sh -c 'ls /sys/kernel/security/landlock'

# host networking: what does the container actually see?
docker run --rm alpine sh -c 'ip addr; ip route'

Landlock is a Linux LSM, and Docker Desktop's kernel has historically shipped without CONFIG_SECURITY_LANDLOCK, so anything that sandboxes via Landlock fails inside the VM while the Mac host looks perfectly fine. --network host is the other half: on Docker Desktop for Mac the "host" is the VM, not macOS, so it's effectively a no-op and any prerequisite assuming real host networking can't be satisfied — you reach the Mac through host.docker.internal instead.

Practical workaround on Apple Silicon: run the sandbox on a Linux VM with a Landlock-enabled kernel (Colima/Lima on a recent kernel, or a cloud VM) rather than Docker Desktop, or use the VM's bridge network if OpenShell has a mode that doesn't need host networking. The doctor fix is to run its probes through docker run ... so it reports the VM's kernel and network mode rather than the Mac's.

[tech4242]

Thanks. Two clarifications from testing on 0.1.2:

• doctor check doesn't probe the host kernel either. It only runs docker info and prints DOCKER_HOST, so neither the Mac nor the VM is checked today.
• Both prerequisites can be met on current Docker Desktop. On 4.93.0 the VM kernel has Landlock (CONFIG_SECURITY_LANDLOCK=y, and the sandbox Landlock probe passes), and in my test sandboxes started after enabling host networking. On 4.55.0 the VM kernel has no Landlock, so no setting helps there.

So I think the fix is VM-side checks in doctor plus clearer errors for an old Docker Desktop or host networking off, rather than moving off Docker Desktop.

[gusraggio]

The same Landlock baseline error also shows up on a native Linux host, with no Docker Desktop VM involved. I hit it with the Podman and Kubernetes drivers on SUSE Linux Enterprise Server 15 SP7, so the fix probably needs to cover more than the Docker Desktop VM.

• SLES 15 SP7 ships kernel 6.4 (6.4.0-150700.53.81-default) built with # CONFIG_SECURITY_LANDLOCK is not set. A version check alone (>= 6.2) would pass on it. Adding landlock to lsm= does not help because the LSM isn't compiled in.
• On the same hardware, SLES 16.0 (kernel 6.12, Landlock ABI 6) runs sandboxes fine with both drivers.

What the user sees with OpenShell 0.1.2:

Driver	CLI result	Cause visible to the user?
Podman (RPM install, rootless)	sandbox entered error phase while provisioning: ContainerExited: Container exited with code 1, a few seconds after create	No. Only in podman logs of the workload container
Kubernetes (Helm chart on K3s)	ProvisioningTimedOut: Provisioning repair window expired after 300 seconds, although the workload pod failed after about 11 s	No. Only in kubectl logs of the workload pod

In both cases the container log has the same baseline error quoted in this issue (fully incompatible access-rights / Landlock allow/deny probe).

@tech4242, since you're picking this up, two suggestions from this setup:

• A Landlock check in doctor would be useful for the Podman driver on Linux too, probing the kernel the workload actually runs on (landlock_create_ruleset(NULL, 0, LANDLOCK_CREATE_RULESET_VERSION) returns ENOSYS here). It should not rely on the kernel version.
• For the acceptance criterion about the Landlock startup error, it would help if the message reached the CLI from every driver, not only Docker. I'm happy to test a patch on SLES 15 SP7 and SLES 16.

[tech4242]

Thanks @gusraggio!

I checked the SUSE kernel configs and they match: SLE15-SP7 has CONFIG_SECURITY_LANDLOCK unset, SL-16.0 has it set with landlock first in CONFIG_LSM.

Agreed on probing the runtime kernel rather than checking the version. For Docker and Podman, doctor can run the probe inside a short-lived container on the same runtime, so one check covers both.

k8s is harder, since the workload runs on cluster nodes that doctor can't see, so there the startup error reaching the CLI matters more. The 300 s ProvisioningTimedOut after an 11 s pod failure looks like a separate problem to me.

My plan would be to start with the doctor check for Docker and Podman and a clearer Landlock startup error, and keep cross-driver error propagation for a follow-up; happy to take the larger scope too if maintainers would rather keep it in 1 change.

I'll def. ping you for a test run on SLES 15 SP7 and 16 once there's a patch.

[tech4242]

Quick update while this waits for triage. I have a working version locally (not opening a PR before it's accepted). doctor check runs the sandbox image's own capability-probe in a short-lived container on each runtime that responds, with the same restrictions the drivers give a workload:

  Docker ............. ok (version 29.8.1)
  DOCKER_HOST ........ (not set, using default socket)
  Sandbox image ...... ok (ghcr.io/nvidia/openshell/sandbox:0.1.2)
  Sandbox runtime .... ok (Landlock ABI 8, seccomp killable)
  Podman ............. ok (version 6.1.3)
  Sandbox image ...... ok (ghcr.io/nvidia/openshell/sandbox:0.1.2)
  Sandbox runtime .... ok (Landlock ABI 9, seccomp killable)

Two things I found along the way:

• Podman-only users fail doctor check today even with a working setup, since it only runs docker info.
• The Podman machine on macOS (Fedora 44, kernel 7.1.10) has Landlock ABI 9, so it works where Docker Desktop 4.55 doesn't.

Proposed scope for the first PR: the doctor probe for Docker and Podman, plus a clearer Landlock startup error in the sandbox (built in vs. missing from lsm= vs. blocked by seccomp). Host networking, a minimum Docker Desktop version in the support matrix, and getting startup errors to the CLI for Podman and k8s would be follow-ups, so the PR would be "Part of #4133".

Three questions before I open it:

1. When the sandbox runtime image is missing, doctor pulls it (about 9 MB) into each runtime. Is that OK, or would you rather it skip that runtime with a warning? There's also a --sandbox-runtime-image flag (OPENSHELL_SANDBOX_RUNTIME_IMAGE) for mirrored or pinned images.
2. Should doctor check every runtime it finds, or only one picked with something like --runtime docker|podman? Right now a running Podman that can't get the image fails doctor for someone who only uses Docker.
3. Is the sandbox error change fine in the same PR, or do you want it separate?