Auto-detect Rancher Desktop and Podman container runtimes

[skyrpex]

What

lstk now works out of the box with Rancher Desktop and Podman, alongside Docker Desktop, Colima, OrbStack, and Lima:

• Runtime auto-discovery: added socket auto-detection for Rancher Desktop and Podman (machine on macOS, rootful/rootless on Linux), and lstk now also resolves the current Docker CLI context (docker context use … / DOCKER_CONTEXT). An explicit DOCKER_HOST still always wins.
• Helpful "runtime not available" errors: the error now suggests the start command for the runtime you actually have (rdctl start, podman machine start, colima start, …) instead of always assuming Docker Desktop.
• Port 443 degrades gracefully: runtimes like Rancher Desktop (Traefik ingress) and rootless Podman often make port 443 unavailable. Instead of failing the start, lstk now starts without 443 and prints a warning with a runtime-specific fix. HTTPS stays available on the edge port (4566 serves both HTTP and HTTPS). If you explicitly configured 443 via GATEWAY_LISTEN, a conflict remains a hard error.
• Docs: new docs/container-runtimes.md with per-runtime setup notes and caveats.

Why

Users on Rancher Desktop or Podman had to manually export DOCKER_HOST, and then still hit a fatal, cryptic port-443 error on startup. Discovery and startup should just work across Docker-API-compatible runtimes (DEVX-639, DEVX-637).

How to test

• Rancher Desktop: install it, set container engine to dockerd (moby), quit Docker Desktop, then lstk start — auto-detected via ~/.rd/docker.sock or the rancher-desktop docker context. With Kubernetes enabled, expect the 443 warning with the Traefik hint (transcript below).
• Podman machine (macOS): podman machine init && podman machine start, quit other runtimes, then lstk start — auto-detected via the podman machine socket; also works via a manually created context (docker context create podman --docker "host=unix://$(podman machine inspect --format '{{.ConnectionInfo.PodmanSocket.Path}}')" && docker context use podman). In rootless mode, expect the 443 warning with the --rootful hint (transcript below).
• Colima / OrbStack: start one, quit the others, lstk start — auto-detected as before.
• Override: DOCKER_HOST=unix://… lstk start must beat context and auto-detection.
• Stopped runtime: with everything stopped, lstk start should suggest the start command for whatever runtime is installed.

Before / after

Before (any runtime that cannot bind 443 — fatal):

$ ./bin/lstk start

   ▟████▖   lstk (dev)
  ▟██▙█▙█▟  LocalStack Enterprise
    ▀▛▀▛▀   ~/.config/lstk/config.toml

✔︎ Pulled localstack/localstack-pro:latest
✔︎ Valid license (Enterprise)
✗ failed to start LocalStack: Error response from daemon: something went wrong with the request: "listen tcp 127.0.0.1:443: bind: permission denied\n"

After (rootless Podman machine — the daemon rejects the 443 bind at start time, lstk retries without it):

$ ./bin/lstk start

   ▟████▖   lstk (dev)
  ▟██▙█▙█▟  LocalStack Enterprise
    ▀▛▀▛▀   ~/.config/lstk/config.toml

✔︎ Pulled localstack/localstack-pro:latest
✔︎ Valid license (Enterprise)
> Warning: Port 443 cannot be published (bind: permission denied) — starting without it. Clients that hardwire HTTPS on port 443 must use
           https://localhost:4566 instead (the edge port serves both HTTP and HTTPS). Podman machine cannot publish ports below 1024 in rootless mode
           — switch with `podman machine set --rootful`, then restart lstk.
✔︎ LocalStack is running (containerId: 18c4f21195cf)
• Endpoint: localhost.localstack.cloud:4566
• Web app: https://app.localstack.cloud
> Tip: View emulator logs: lstk logs --follow

After (Rancher Desktop with Traefik holding 443 — caught by the preflight, before the image pull):

$ ./bin/lstk start

   ▟████▖   lstk (dev)
  ▟██▙█▙█▟  LocalStack Enterprise
    ▀▛▀▛▀   ~/.config/lstk/config.toml

> Warning: Port 443 is in use — starting without it. Clients that hardwire HTTPS on port 443 must use https://localhost:4566 instead (the edge port
           serves both HTTP and HTTPS). Rancher Desktop's Kubernetes ingress (Traefik) usually holds port 443 — free it with `rdctl set
           --kubernetes.options.traefik=false`, then restart lstk.
✔︎ Pulled localstack/localstack-pro:latest
✔︎ Valid license (Enterprise)
✔︎ LocalStack is running (containerId: d14e0903f36d)
• Endpoint: localhost.localstack.cloud:4566
• Web app: https://app.localstack.cloud
> Tip: View emulator logs: lstk logs --follow

Closes DEVX-637
Towards DEVX-639

[claude]

This PR makes lstk auto-discover Rancher Desktop / Podman daemons and degrade gracefully when port 443 can't be published; the design is careful and the test coverage is strong.

1. thought(non-blocking): on internal/container/start.go — in startWithOptionalPortFallback, when rt.Remove fails you return the original bind error and leave a created-but-never-started container behind under the same name, so the next lstk start would hit a name-conflict. The comment acknowledges the tradeoff, but surfacing a hint (or the leftover container name) in that error path would save the user from a confusing follow-up failure.

2. question(non-blocking): on internal/runtime/docker_context.go — resolveDockerContextHost now dials the context socket (200ms timeout) inside NewDockerRuntime whenever a non-default context is set, which puts a synchronous probe on the start/status/stop path. It's almost certainly negligible, but was that hot-path cost a conscious call versus honoring the context without the reachability probe?

3. praise: the two-layer handling — a preflight dial for host-busy ports plus a start-time retry for daemon bind-denied ports, with the evidence pair (rt.Flavor() + DetectInstalledFlavor()) driving runtime-specific hints and Windows' named-pipe blind spot explicitly handled — is a genuinely thorough take on a messy cross-runtime problem, and the CLAUDE.md/docs updates capture the reasoning clearly. @skyrpex

---

Generated by Claude Code