macOS Docker runtimes: QUIC/UDP port forwarding breaks control plane connection
The miren control plane uses QUIC (HTTP/3) over UDP port 8443. On macOS, some container runtimes don't forward UDP by default, causing the cluster to be unreachable with a silent timeout after install appears to succeed.
Prior art: MIR-569 addressed a symptom of this (install hanging on healthz polling) with a startup delay. This issue addresses the underlying transport problem, which persists for affected runtimes even after the container is fully started.
Root cause
Colima (and likely Rancher Desktop) use Lima under the hood, which defaults to SSH-based port forwarding — TCP only. UDP packets sent to localhost:8443 arrive at the container but responses never reach the host, so the QUIC handshake never completes. miren doctor server reports "not connected" with no actionable guidance.
Confirmed fix for Colima: set portForwarder: grpc in ~/.colima/default/colima.yaml and restart.
Known status by runtime
| Runtime | Status | Notes |
|---|---|---|
| OrbStack | Works | Native macOS networking |
| Docker Desktop | Works (v4+) | Needs verification |
| Colima | Broken by default | portForwarder: grpc in colima.yaml fixes it |
| Rancher Desktop | Untested | Likely same issue as Colima (Lima-based) |
Proposed work
- Install-time QUIC probe (
miren server docker install): after starting the container, test UDP connectivity tolocalhost:8443. If it fails, detect the active Docker runtime and emit a specific, actionable error with the fix for that runtime. - Doctor enhancement (
miren doctor server): run the same QUIC probe and surface runtime-specific remediation for users with existing broken installs. - Docs: add a single callout table on the docker install page listing runtime status and known fixes.
Not in scope
TCP fallback for the control plane transport layer (separate discussion if needed).