feat(bootstrap): add Podman socket fallback for macOS

[craigamcw]

Implemented feature with help from Claude Code.

Add additive Podman support on macOS without changing any Linux paths, K3s logic, policy engine, or inference routing.

Socket discovery fallback chain:

1. $DOCKER_HOST
2. $CONTAINER_HOST
3. /var/run/docker.sock (bollard default)
4. Podman socket via podman machine inspect (macOS only)

Container runtime adaptations when Podman is detected:

• security_opt: unmask /sys/fs/cgroup and /dev/kmsg
• kubelet feature gate: KubeletInUserNamespace=true
• kubelet arg: cgroups-per-qos=false, enforce-node-allocatable=

Image push reliability:

• Extended timeout (120s → 600s) for Unix socket connections
• Fallback from bollard put_archive API to docker cp CLI for large image transfers that fail over the Podman API socket

Also adds documentation for Podman setup in quickstart, support matrix, and a new troubleshooting page.

Summary

Adds Podman as a supported container runtime on macOS. OpenShell now auto-discovers the Podman machine socket, configures k3s kubelet flags for rootful Podman compatibility, and falls back to docker cp for reliable large image uploads. No Linux paths, K3s core logic, policy engine, or inference routing are changed.

Related Issue

N/A — feature contribution (Podman on macOS was previously unsupported)

Changes

• Socket discovery fallback chain in check_docker_available(): $DOCKER_HOST > $CONTAINER_HOST > /var/run/docker.sock > Podman socket via podman machine inspect (macOS only)
• Podman runtime detection (is_podman_runtime()) via Docker version API response
• k3s container adaptations when Podman detected: security_opt unmask for cgroup/kmsg, kubelet KubeletInUserNamespace=true, cgroups-per-qos=false, enforce-node-allocatable=
• Image push reliability: extended timeout (120s → 600s) for Unix socket connections; docker cp CLI fallback when bollard put_archive API fails on large payloads
• Documentation: Podman setup in quickstart, support matrix entry, new troubleshooting page

Testing

• [ Y ] mise run pre-commit passes
• [ Y ] Unit tests added/updated (8 new tests: socket discovery, extended timeout, tar wrapping, docker cp fallback lifecycle and error messages — 97 total, 0 failures)
• [ Y ] E2E tests added/updated (if applicable) - manually verified end-to-end: nemoclaw onboard completes successfully on macOS M4 Mini 16GB with Podman 5.8.1 (rootful mode, Apple Hypervisor backend)

Checklist

• [ Y ] Follows Conventional Commits
• [ Y ] Commits are signed off (DCO)
• [ Y ] Architecture docs updated (if applicable) - docs/get-started/quickstart.md, docs/reference/support-matrix.md,
  docs/reference/troubleshooting.md (new)

[github-actions]

All contributors have signed the DCO ✍️ ✅
_{Posted by the DCO Assistant Lite bot.}

[craigamcw]

I have read the DCO document and I hereby sign the DCO.

[craigamcw]

recheck

[drew]

Thanks for the PR. I'm thinking through the best way to to test this. There is enough business logic and difference in implementation that we'll want some podman specific e2e tests.

[craigamcw]

Thank you Drew. I added Podman-specific E2E tests in e2e/rust/tests/podman_support.rs (4 tests):

Test	What it validates
doctor_check_succeeds_with_podman	Explicit DOCKER_HOST pointing at Podman socket works
doctor_check_auto_discovers_podman_socket	Auto-discovery via podman machine inspect without DOCKER_HOST (macOS)
doctor_check_respects_container_host	CONTAINER_HOST env var fallback (Podman convention)
gateway_lifecycle_with_podman	Full start → status → destroy — validates k3s runs under Podman with KubeletInUserNamespace and cgroups-per-qos flags

All tests skip gracefully when Podman is not installed, so they won't break CI on Docker-only runners.

Verified locally: 4/4 pass on macOS M4 with Podman 5.8.1 (applehv, rootful mode).

[drew]

Let's hold on this for now. podman isn't installed on our CI images, so our e2e tests are still going to fail.

We're going to switch to a microVM based approach which should alleviate this bug all together. If the microVM approach doesn't work, or we decide to continue to support docker we can bring the PR back and get proper CI support.

Feel free to contribute to the discussion here, #558.