feat(podman): auto-detect container engine and support Podman

[wmeints]

Why

Huddle was hardwired to Docker (Docker Desktop on Windows). Teams that standardise on Podman couldn't run it: huddle init failed and devcontainers couldn't reach the Docker socket proxy. This change makes Huddle detect the container engine automatically and adapt its socket mapping and container configuration accordingly, so it starts and runs on Podman as well as Docker. Scope is intentionally limited to Docker + Podman.

What changed

The gateway stays engine-agnostic — it drives the engine through the Docker-compatible REST API on /var/run/docker.sock, which Podman also serves. The real differences are around socket mapping and SELinux, handled at the edges:

• cli/src/runtime.ts — ContainerRuntime gains:
  • isRemote — whether the engine runs in a VM (Podman machine / Docker Desktop). Detected via podman info --format {{.Host.ServiceIsRemote}}; for Docker, platform !== 'linux'.
  • securityOpts — ['label=disable'] for Podman, empty for Docker.
• cli/src/init.ts
  • Pre-creates the socket dir inside the machine VM for remote Podman (podman machine ssh "mkdir -p /tmp/dc-sockets") — Podman does not auto-create a missing bind source the way Docker Desktop does, and native Linux still mkdirs locally.
  • Adds --security-opt label=disable and -e HUDDLE_RUNTIME=<engine> to the huddle container.
• gateway/src/docker.ts — when HUDDLE_RUNTIME=podman, adds SecurityOpt: ['label=disable'] to each devcontainer's HostConfig so it may access the SELinux-labeled per-container proxy socket.
• huddle.ps1 — resolves the engine once (same precedence as the CLI: explicit HUDDLE_RUNTIME, then Docker, then Podman), routes every direct docker call through & $RUNTIME, and exports HUDDLE_RUNTIME so the delegated huddle init uses the same engine. On Windows + Docker Desktop nothing changes.
• cli/dist/index.js — restore the executable bit on the CLI bin entrypoint (was committed as non-executable, causing "permission denied" after a global install).

Important parts to review

• gateway/src/docker.ts — label=disable on devcontainers. This relaxes SELinux confinement on devcontainers when on Podman. It is required for them to reach the proxy socket (verified: a confined client gets "Permission denied"). The huddle container itself already gets label=disable from the CLI. Note the child-container guard in socket-proxy.ts still rejects label=disable from containers spawned inside a devcontainer — that path is unchanged.
• cli/src/init.ts — socket-dir precreation for remote Podman. The podman machine ssh call assumes the default machine. Worth a look for multi-machine setups.
• cli/src/runtime.ts — isRemote detection and the Docker platform !== 'linux' heuristic.
• huddle.ps1 — runtime resolution + HUDDLE_RUNTIME export, ensuring the script and the delegated CLI agree on the engine when both are installed.

Risks

• Docker regression risk: low. For Docker the new fields are inert (securityOpts empty, no SecurityOpt injected, existing socket-dir behavior preserved for Windows/Linux). huddle.ps1 picks Docker first, so the Windows/Docker Desktop flow is unchanged.
• label=disable reduces SELinux isolation for the huddle container and Podman devcontainers. Acceptable given the huddle container already has full engine access via the mounted socket, but it is a real posture change on SELinux-enforcing hosts.
• Podman-machine assumptions: single default machine; /tmp/dc-sockets lives on VM-local tmpfs (shared correctly between huddle and devcontainers). Untested against remote/rootful Podman over SSH or multi-machine configs.
• Not exercised live: full devcontainer creation on Podman needs the base images (not available locally); the socket-sharing + label=disable behavior was verified in isolation and via the gateway's own startup socket calls.

Verification

• huddle init --runtime podman on a Podman machine: huddle container comes up on devcontainer-net,podman, correct SecurityOpt/env/mounts, gateway boots with no socket errors, and a request over /var/run/docker.sock from inside returns HTTP 200.
• huddle.ps1 end-to-end on Podman: resolves podman, delegates huddle init without error, status shows [ON] Huddle draait.
• CLI + gateway typecheck/build clean; all 85 gateway unit tests pass.

🤖 Generated with Claude Code

[wmeints]

Follow-up fix: engine detection through the docker shim

Testing surfaced a detection bug on Podman hosts where docker is a symlink/shim to Podman (podman-docker). Podman emulates even docker --version, so the original name-based auto-detect picked docker and misconfigured the socket path, network, and skipped label=disable → huddle init failed with:

Command failed: docker run ... -e HUDDLE_RUNTIME=docker ... -v /var/run/docker.sock:/var/run/docker.sock ...

Fix (commit 2a836d4): probe the real engine via a Podman-only info field — <cmd> info --format {{.Host.ServiceIsRemote}} returns a value on Podman (even through the shim) and errors on Docker. Applied in both cli/src/runtime.ts (detectEngine) and huddle.ps1 (Get-TrueEngine); auto-detect now looks behind the docker command first, then podman. A real Docker engine still wins when present.

Verified: huddle init with no --runtime on a Podman host that exposes docker→podman now resolves podman, creates the VM socket dir, and starts with SecurityOpt=[label=disable], HUDDLE_RUNTIME=podman.

[wmeints]

Follow-up fix: operator locked out of the web UI on Podman

On rootless Podman the web UI returned {"error":"forbidden","reason":"endpoint not allowed from devcontainer network"} for the operator on http://localhost:3000.

Cause: Podman's rootless port forwarder (pasta) delivers host -p traffic into the container via its primary network interface, sourced from that subnet. With devcontainer-net (10.89.0.0/24) as the primary network, the operator's browser arrived as e.g. 10.89.0.8 — inside a subnet the source-IP gate (api.ts) blocks — so the UI was rejected. Docker doesn't hit this: its port forward goes through the docker proxy and is sourced from loopback/the bridge gateway, independent of the primary network.

Fix (commit ed3d824): on Podman, start huddle with the egress network (runtime.defaultNetwork) as primary and attach devcontainer-net afterwards. Host traffic then arrives from the non-blocked egress subnet (10.88.0.0/16), while devcontainers keep arriving from devcontainer-net/dc-net-* and stay blocked. Docker keeps its existing ordering.

Verified on rootless Podman: operator GET / and /api/state → 200; a container on devcontainer-net hitting huddle:3000/api/state → 403 (gate intact).

Minor note for reviewers: as with Docker's bridge, other containers the user runs on the default podman network could now reach the API — same posture as the existing Docker setup.

[wmeints]

Heads-up: fixed a Podman DNS regression that broke egress (pushed as c0b6e5d)

While testing this branch I hit a 502 from api.anthropic.com inside the devcontainer — Claude Code couldn't reach the API at all. Worth a careful look during review since it touches the new Podman networking.

Root cause

The gateway attaches to the --internal devcontainer networks. Podman adds each of those networks' aardvark-dns (the network gateway, e.g. 10.89.x.1) to the gateway's /etc/resolv.conf. Those servers only know container names and answer NXDOMAIN for external hostnames.

The gateway image is Alpine (musl), and musl's resolver queries all nameservers in parallel and uses the first reply. The on-host aardvark returns its NXDOMAIN almost instantly and wins the race against the slower real egress resolver → every external lookup fails with ENOTFOUND → the proxy's upstreamReq.on('error') returns 502.

Confirmed against the live gateway's own audit log (all 502s had res_headers=null/res_body=null, i.e. the proxy's own error path, not an Anthropic response) and reproduced in isolation. Two subtleties that shaped the fix:

• Reordering resolv.conf doesn't help — musl ignores order, so the broken servers must be removed.
• huddle init connects the second network after the gateway process starts, so the pollution lands after the first sanitize (hence the settling window below).

Fix (c0b6e5d)

• New gateway/src/dns-egress.ts: probes each nameserver and drops the ones that can't resolve externally. Fail-safe — leaves the file untouched if no resolver works.
• Runs at startup, over a short settling window (catches the post-start network connect), and after every gateway network connect/disconnect (docker.ts).
• Left cli/src/init.ts on run -d + post-start connect — I tried create/connect/start to attach both nets before startup, but that makes Podman drop the egress resolvers entirely. Comment added explaining why.

Verified end-to-end: api.anthropic.com resolves and the upstream returns 401 (auth expected) instead of 502; stable past the settling window. tsc clean, all 85 gateway tests pass.

This is Docker-safe: Docker's embedded DNS resolves external names on internal networks, so the sanitizer is a no-op there.

[insuT0ver]

Ik sluit deze PR omdat de ideeën uit deze branch zijn samengevoegd met #29, #49 en #51 in één consolidatiebranch gekoppeld aan #47: experiment/47-podman-support-consolidated.

Zou je willen testen of dit nu werkt in jouw setup?

huddle experiment use 47

of

huddle init --experiment 47

Dit installeert de CLI en gateway image van dit experiment, zodat je end to end kunt testen op je eigen Podman host of VM. Zodra je klaar bent, kun je terugschakelen naar de stabiele versie met:

huddle experiment reset

Laat gerust weten als je nog problemen of onverwacht gedrag tegenkomt. Dan lossen we dat op in de experiment branch voordat alles naar main gaat.