Feat/runtime detection to add podman support (and base for others)

[duplo-darren]

What this changes

The kit assumed Docker. $RUNTIME — docker or podman, resolved once in
scripts/_runtime.sh — now replaces every hard-coded docker call across run.sh,
stop.sh, logs.sh and scripts/, and two preflights catch the podman
misconfigurations that otherwise fail late and blame the wrong thing:

• Undersized machine — an OOM kill during the Angular build, surfacing only as
  exit status 137 at the foot of a Go stack trace.
• No Rosetta — an amd64 studio image then runs under QEMU, which cannot run .NET.
  It aborts at startup, the container still reports Up, /healthz never answers, and
  run.sh spends ~4.5 minutes on a dot loop before exiting with Login failed — a
  message about credentials for a problem that has nothing to do with them.

Both replace a baffling failure with an accurate one, both are no-ops on docker, and
both stay silent when they cannot determine the answer rather than guessing.

Rosetta is a provider question first

podman does not enable Rosetta by default, and an absent containers.conf behaves
exactly like rosetta = false. But the trap that costs the most time is one level up:
Rosetta is an applehv feature, and podman 6 defaults to libkrun on Apple Silicon.
Upstream's LibKrunStubber.GetRosetta returns false unconditionally, so rosetta = true
under libkrun is read and discarded, leaving no trace anywhere except the missing binfmt
handler. The config looks right, podman machine inspect keeps saying Rosetta: false,
and recreating the machine changes nothing.

The check therefore leads on the provider, resolved from the running machine's
VMType first — podman machine init --provider applehv does not write
containers.conf, so the file describes the next machine, not the one you are
talking to — then the environment, then the config.

The remediation keeps two lifetimes apart, because conflating them is what sends people
in circles:

Setting	Lifetime	Fix
provider	fixed at podman machine init	recreate the VM
rosetta	re-read by applehv's StartVM every start	stop/start is enough

The Rosetta remediation is read from your existing config, which is not polish:
appending [machine]\nrosetta = true to a containers.conf that already has that
table is a TOML duplicate-key error, after which podman refuses to run at all —
strictly worse than the missing Rosetta. The check reads the file podman will read and
prints one of six specific instructions: the provider case above, or one of five conf
states, including "your config is already correct, the machine just needs restarting"
— which is now correctly scoped to applehv, where it is true.

finch is temporarily de-listed pending validation — not auto-detected,
RUNTIME=finch rejected. A claim-reduction, not a removal: every finch code path is
retained and correct (builder_run_direct, and the {{json .Server}} probe fix for a
server struct with no .Server.Version). Re-enable by putting finch back in
_RUNTIME_SUPPORTED.

Verified on real hardware, both directions

• libkrun machine — the check names the provider, prints the applehv config and the
  recreate sequence, exits 1.
• rebuilt applehv machine (rosetta = true) — podman machine inspect reports
  Rosetta: true, the VM's binfmt_misc has rosetta and no qemu-x86_64, both
  preflights exit 0 silently, and the amd64 studio image serves /healthz 200 with
  uname -m = x86_64 inside the container and no QEMU abort in the log.

39 tests in tests/test-runtime.sh, all static or pure-function, so the suite runs the
same on a docker laptop, a podman box and CI.

Docs

configuration.md gains the Container runtime section it was missing despite
promising every .env variable; prerequisites.md gains the Apple Silicon podman setup
— now three steps, provider first; troubleshooting.md gains the full symptom-to-fix
entry, with libkrun called out ahead of the applehv-measured Rosetta table. All three
record that auto-detection tests presence only, with no daemon check, so installing
Docker silently takes precedence over an installed podman.

Note for reviewers

On rootless podman the UI container fails to start — nginx: bind() to 0.0.0.0:80 failed (13: Permission denied) — because it has no CAP_NET_BIND_SERVICE. That is fixed by
#17 (and #19 stacked on it), not here. This PR makes podman work; the UI needs #17 to
come up on it.

4 commits · 14 files · +1624 / −119 · new: scripts/_runtime.sh, tests/test-runtime.sh

[aboutte]

Reviewed this end to end, including running the suites locally and rebasing onto current dev (bc5ef99, which now has #19). It replays clean, and test-runtime.sh 39/39 + test-ui-nginx.sh 6/6 pass together.

This is unusually careful work. Two things worth naming because a quick review would skip them: splitting _runtime_host_arch / runtime_rosetta_active / _runtime_machine_vmtype purely so the policy is testable on any host, and the note at tests/test-runtime.sh:203 about pipefail + grep -q silently inverting three assertions. That's a bug class most people ship.

Four blockers.

1. RUNTIME from .env is ignored on any run that creates .env

run.sh:129   runtime_resolve || RUNTIME_OK=0          ← resolves + memoizes
run.sh:145   "$RUNTIME" info ... "doesn't look ready"
run.sh:162   [ -f "$ENV" ] || cp .env.example "$ENV"  ← .env created HERE

With no .env yet, runtime_resolve has nothing to read, auto-detects, picks docker on presence, and sets _RUNTIME_RESOLVED=1. That memoization holds for the whole run — both podman preflights, compose pull and compose up all use docker.

Hit in practice: .env had RUNTIME=podman and we still got Note: docker doesn't look ready. Setting RUNTIME=podman in .env.example doesn't help either, since the copy at :162 happens after resolution is locked in.

This is the feature's headline promise failing on exactly the first run, on any machine with Docker installed alongside podman.

Fix: move the .env creation above the preflight block — it has no dependency on $RUNTIME.

2. A [machine] header with a trailing comment produces advice that bricks podman

scripts/_runtime.sh:484 (and the same scan at :428) anchors on ^[[:space:]]*\[machine\][[:space:]]*$. [machine] # my settings is valid TOML and doesn't match. Reproduced on-branch:

$ printf '[containers]\n[machine]   # my settings\nrosetta = true\n' > $F
$ CONTAINERS_CONF=$F ... _runtime_rosetta_conf_state
state: no-machine

no-machine prints "Open it and ADD this section: [machine]" — producing exactly the Key 'machine' has already been defined breakage the function's own header comment exists to prevent, on a user who already had it right.

Fix: \[machine\][[:space:]]*(#.*)?$, plus a fixture case in the conf helper.

3. Drop the apt/dnf install guidance — we don't support Linux right now

Two places added here:

• run.sh:138 — podman — install the provider it delegates to: apt install podman-compose (or dnf/brew).
• docs/getting-started/prerequisites.md — sudo apt-get install podman-compose, or brew install podman-compose

Both should be brew install podman-compose only. Leading with apt sends the large majority of users to a command that doesn't exist on their machine.

4. Retire the Rosetta machinery and unpin amd64 — release blocker

New information that changes the calculus on this PR's largest subsystem: we do have arm64 studio builds, and going forward every devkit release will pin a studio tag that is both amd64 and arm64.

That makes most of the Rosetta apparatus obsolete — not because it's wrong, but because the advice it generates stops being the advice we want to give. Once an arm64 image resolves natively, the correct remediation is one sentence ("unset STUDIO_PLATFORM"), which replaces every branch of the containers.conf surgery.

This is a blocker for the release, not necessarily for this merge. If it's cleaner to land the runtime abstraction first and stack this on top, fine — but it has to go in before we ship, otherwise we release ~150 lines of machinery that is already obsolete and that actively misdirects Apple Silicon users toward configuring Rosetta they no longer need.

Four coupled parts, which must land atomically:

1. Unpin the platform. docker-compose.yml:61 is the only platform: pin in the stack; every other service already resolves natively from its manifest. Correct value is no pin, not linux/arm64 (that breaks amd64 Linux). The idiom is already two lines down: platform: ${BUILDER_PLATFORM:-}.

2. Trap — the adoption mechanism can't propagate a blank. run.sh:565: [ -z "$ex" ] && continue # only track keys the example ships non-blank. STUDIO_PLATFORM is a tracked key, so blanking it in .env.example means existing users keep linux/amd64 forever. Needs a one-time migration that removes the line from .env when it still matches the old default and .env.defaults agrees it was never hand-pinned.

3. Trap — the check's own default goes stale at the same moment. scripts/_runtime.sh:516: [ -n "$plat" ] || plat=linux/amd64. Once the pin is dropped, unset means native, and this line hard-exits with a false positive on every Apple Silicon podman user. Must change in the same commit.

4. Then delete _runtime_rosetta_conf_state, _runtime_machine_provider / _runtime_machine_conf_provider / _runtime_machine_vmtype, the six-branch remediation, and the troubleshooting Rosetta table — roughly 150 lines of script, 100 of docs, 14 of the 39 tests.

   Keep _runtime_host_arch + runtime_rosetta_active + a ~25-line check that fires only on an explicit amd64 pin, with "unset STUDIO_PLATFORM" as the advice. Still needed for stale .env files and amd64-only registry mirrors — the failure is still a 4.5-minute lie ending in Login failed. runtime_machine_check (the OOM one) is unrelated; leave it alone.

Non-blocking

• run.sh never says which runtime it picked on the happy path — only on failure. One line next to ==> Pulling images… is the cheapest mitigation for presence-based auto-detect, and doubly useful given feat(run.sh): add a subscription LLM provider (Claude Code subscrip… #1 above.
• builder_run_direct is unreachable with _RUNTIME_SUPPORTED=(docker podman). Retaining it is the right call given finch is de-listed rather than removed — just add a line saying it's currently unreachable and what re-enables it.
• Blast-radius section omitted from the PR body, though this touches .env.example (+34). Risk is nil (comments plus a commented-out key), but worth saying so.
• SUPPORT.md:47 and hackday/*.md still instruct docker compose ps / docker --version. SUPPORT.md is what a podman user pastes into a support request.
• runtime_is_rootless_podman caches 0 when podman info fails, which then makes runtime_builder_ids return the real uid — the value documented as harmful under rootless podman. Distinguishing "not rootless" from "couldn't tell" would match the three-state honesty used elsewhere in the file.

Happy to take items 1–3 as commits if that's easier than a round trip.

[duplo-darren]

Thanks — this was an unusually useful review. All four blockers are addressed; blocker 4 is stacked separately as you offered. This PR is now 12 commits.

1 — RUNTIME from .env ignored on a run that creates .env. Confirmed exactly as described. .env creation moved from run.sh:162 to :111, above the preflight block; it needs neither python3 nor $RUNTIME, so it is safe there. A test asserts the cp .env.example line precedes runtime_resolve, since this is an ordering bug a future edit could silently reintroduce.

2 — [machine] header with a trailing comment. Reproduced with your fixture, and against a clean-header control that still returns enabled, so the comment was the only variable. All three scan sites now allow (#.*)?$, plus a fixture case in the conf helper. Note this fix is deleted by blocker 4, which removes the function entirely — it still matters because this PR ships first.

3 — apt/dnf guidance. Dropped. I first replaced it with brew install podman-compose only, and that was also wrong: podman needs a compose provider, not that specific package. Verified on a machine with no docker at all — podman-compose absent, a docker-compose binary present, podman compose version answering. Both places now describe the requirement and point at the check, so the advice holds whichever provider is installed.

The pre-existing apt/dnf hint for python3 at run.sh:123 is untouched — it predates this branch, so the accompanying test is scoped to the podman-compose lines. Worth its own issue if Linux stays unsupported.

4 — retire Rosetta, unpin amd64. Done, stacked in a follow-up PR. I verified your premise independently: the studio tag currently pinned is already an OCI index carrying both arches, so this is not forward-looking — the pin was forcing QEMU today when a native arm64 layer already existed. Three commits, parts 1–3 atomic as you specified. scripts/_runtime.sh goes 651 → 489 lines; the troubleshooting entry 206 → 71.

The migration is deliberately conservative: it removes the line only when .env still holds linux/amd64 and .env.defaults agrees that was the last-applied default. Both guards are mutation-tested — loosening either one makes a specific test fail.

The doc sweep was wider than the review listed: faq.md, configuration.md and upgrading.md carried the same stale "amd64-only" claim. Four tests now fail if any of it returns.

---

Three further findings, downstream of your blocker-4 framing

Retiring that machinery meant looking at what the kit says when a runtime is not usable, and the messages turned out wrong in the same way three times over — reciting prerequisites at someone who already meets them:

• error:runtime told anyone with a stopped Docker Desktop to install docker. That is the largest affected group, and podman is not involved at all. It now distinguishes four cases: nothing on PATH → install; present but not answering → start it; another runtime answers → use it, named, with the command; explicitly requested → the same, without implying they chose wrong.
• The compose preflight in run.sh had the identical gap. Hit in real use: .env pinned RUNTIME=podman, podman's socket had broken, docker was up with Compose v2 — and the failure listed install advice for both runtimes without mentioning that docker would have worked immediately.
• All three messages then recommended RUNTIME=<x> ./script, which manufactures the cross-runtime warning documented two entries away in troubleshooting.md: run.sh, the build scripts, logs.sh and stop.sh each resolve independently, so a one-off leaves the next command on the other runtime. They now point at .env only, and say why.

Also added your non-blocking runtime announcement (==> Using <runtime> beside Pulling images), and a troubleshooting entry for the cross-runtime build warning — including that probing the SDK feed unauthenticated returns 401, which proves the route works, since that result otherwise reads as the fault.

Not done

Four of your non-blocking items: the builder_run_direct unreachability comment, SUPPORT.md:47 and hackday/*.md still instructing docker compose ps, the runtime_is_rootless_podman three-state, and the blast-radius section. Happy to take any of them.

One correction to this PR's own body

It says the bind() to 0.0.0.0:80 failure is "on rootless podman". I hit it on a rootful machine too, so #17 is needed more broadly than that note implies.

---

62 runtime tests (was 39), 121 across the suite, all passing. Merges clean into dev.

[duplo-darren]

Heads-up on what follows this

Blocker 4 is done and pushed, but not opened as a PR yet. Basing it on dev today would pull this PR's 12 commits into its diff, and basing it on this branch would mean a duplicate base branch upstream that goes stale if this PR's head moves. So it waits until this merges, then goes up against dev as a clean 3 commits.

Reviewable now without a PR, if you want it early:

duplo-darren/devkit-fork@feat/runtime-detection...feat/studio-platform-unpin

That compare shows exactly the three commits and nothing from this PR:

• feat(runtime): unpin the studio platform and retire the amd64 default — the four coupled parts, one commit: compose unpinned to ${STUDIO_PLATFORM:-}, .env.example pin commented out, runtime_rosetta_check treating unset as native, and a one-time .env migration. Atomic because any subset is broken — dropping the pin without part 3 hard-exits every Apple Silicon podman user on a false positive, and without part 4 existing users keep linux/amd64 forever, since the adoption pass skips keys the example ships blank.
• refactor(runtime): retire the Rosetta diagnosis machinery with the pin — deletes _runtime_rosetta_conf_state, the three provider helpers and the six-branch remediation. scripts/_runtime.sh 671 → 540 lines. runtime_rosetta_check survives at ~25 lines, firing only on an explicit amd64 pin.
• docs(runtime): rewrite the Apple Silicon guidance around the unpinned platform — the troubleshooting entry 206 → 71 lines, plus the same stale "amd64-only" claim in faq.md, configuration.md and upgrading.md.

The migration is the part worth your eye, since it writes to a user's .env. It removes the line only when .env still holds linux/amd64 and .env.defaults agrees that was the last-applied default — so a hand-pinned value is never touched, and when it declines, runtime_rosetta_check explains the situation rather than leaving anyone stuck. Both guards are mutation-tested.

65 runtime tests there (62 here). One thing that will look odd across the two PRs: it deletes the function fixed by "match a [machine] header that carries a trailing comment" in this PR. That fix still earns its place — this merges first and covers anyone who hits it in the interim.