mcpx testing: extended platforms -- which artifacts ship static; alpine, scratch, distroless, flatpak, Fedora, Windows tiers #1987

Relocated from dezren39/darwin-nix#136 on 2026-10-28 (placement audit): mcpx's single source lives in developing-today/code (pkgs/mcpx); re-home tracked at #309. Original body below; issue references inside it are historical (dezren39/nix numbering).

Parent: #97

Summary

The notes list a wish-list of further environments (alpine-slim, FROM scratch, distroless, flatpak, fedora-kde, silverblue/kinoite, ubuntu, windows-11) and justify it with "basically everything should work because static binary". This issue checks that claim. mcpx itself can be a static binary; what stands in the way is elsewhere:

1. The shipped artifacts are not static -- by choice, not by necessity. The default nix package is built with the nixpkgs cgo default and installed behind a C wrapper with nix-store paths baked in; Phase 5: tag event bodies must travel with the event #182's Containerfile keeps ARG CGO_ENABLED=1 deliberately. A CGO_ENABLED=0 build is fully static and works (verified in Phase 5: tag event bodies must travel with the event #182, docs/container.md §4). Which artifacts should be static is a policy decision (decision 1 below), not a feasibility question.
2. exec needs a JS runtime, which no minimal image has -- and bun, deno and git are dynamically linked distribution binaries, so a static mcpx beside them does not make an image static.
3. mcpx does not compile for Windows today.

It then assigns each environment a tier, says what it needs (a copied binary or an installer, and any extra config), and says which runner provides it.

Original notes

• testing
  • a general goal is to ensure all features have one or more integration tests
    • for both binary && app entrypoint (consider binary a superset)
      • all tests should pass for nix flake & container
        • ideally would like if worked:
          • alpine-slim/FROM scratch/distroless/flatpak
          • fedora-kde,silverblue/kinoite,ubuntu
          • windows-11
        • basically everything should work because static binary
          • non-vanilla may need extra config
          • installers make assumptions and require permissions

Current state: is the binary static? (checked on main d0b7e01; #182's measurements added at 05c78b2)

The claim, corrected: a CGO_ENABLED=0 build (or -tags netgo,osusergo) of the unwrapped binary is static on Linux -- verified, not assumed (#182) -- so the non-exec surfaces should run anywhere with a Linux kernel. That covers ls, call, serve, the daemon, /v1, /mcp, and api --spec. exec/run do not, because they spawn deno, bun or node. The static-binary argument covers the daemon and CLI surfaces only. Nothing in mcpx "prevents" a static build; the open question is which shipped artifacts should be static, below.

The runtime caveat (exec)

So "FROM scratch/distroless-static" means non-exec surfaces only, unless a runtime is added, which then makes the image distroless/cc or larger. #182 confirmed the same from the other side: in its debian image bun and git are dynamically linked distribution binaries, so a static mcpx beside them "saves nothing at all" until everything in the image is static or exec is dropped (docs/container.md §4).

Environments, tiered

"installers make assumptions and require permissions": the tier 1-2 set needs no installer. It uses nix, or a copied binary into ~/.local/bin or the image. Installers appear only for:

• rpm-ostree layering (root, reboot);
• flatpak (a portal/permission model);
• Windows (winget/scoop: per-user vs machine-wide, SmartScreen, Defender scans of a new unsigned .exe).

Recommendation: ship and test "copy the static binary" as the universal path, and treat each installer as its own tier 3 target with its own issue when one is wanted.

Windows, in detail

• Build: split runner.go, stdio.go, client.go process handling into _unix.go/_windows.go. Windows has no process groups in the POSIX sense. The equivalent is a Job Object (CREATE_NEW_PROCESS_GROUP + JobObject with KILL_ON_JOB_CLOSE), and Setsid detach becomes DETACHED_PROCESS. This is not a build-tag exercise: process-group kill is how mcpx stops an MCP server and everything it spawned, and without a Job Object a Windows mcpx leaks children -- the failure scripts/stress.sh exists to catch (from Phase 2: group action codec does not cover friendship or policy #163). internal/pool/pool.go:736 also checks liveness with syscall.Signal(0), meaningless on Windows.
• Sockets: AF_UNIX exists on Windows 10 1803+ and Windows 11 (https://devblogs.microsoft.com/commandline/af_unix-comes-to-windows/), and Go supports net.Listen("unix", ...) there. Whether deno's and bun's unix-socket clients work on Windows is unverified. Node already uses TCP (fix(deps): update rust crate axum to 0.6.20 #35), so a TCP-only mode (daemon.port + MCPX_ENDPOINT) is the fallback.
• Paths: XDG_* fallbacks become %LOCALAPPDATA%. The maxSocketPath logic (internal/daemon/paths.go:96 at 05c78b2) differs on Windows (sun_path is 108 there too, but paths are longer and use backslashes). os.Getuid() in privateRuntimeDir (paths.go:148) returns -1 on Windows.
• Signals: signal.NotifyContext(..., SIGINT, SIGTERM) (cmd/mcpx/main.go:53). SIGTERM is never delivered on Windows. The HTTP shutdown route will not help as written: handleShutdown stops the daemon by sending SIGTERM to its own process (internal/daemon/server.go:774-780), and on Windows os.Process.Signal supports only os.Kill. Shutdown has to become a context cancel.
• e2e: e2e_test.go:590 uses syscall.Signal(0) for liveness, :2704 and :2717 (added by Phase 5: tag event bodies must travel with the event #182) use syscall.Kill(pid, 0), and exec_test.go:107-108 uses syscall.Stat_t. All need build tags.

GitHub-hosted vs self-hosted

Hosted: ubuntu-latest/ubuntu-24.04-arm, macos-latest, windows-latest. container: and services: run only on Linux runners (https://docs.github.com/en/actions/writing-workflows/choosing-where-your-workflow-runs/running-jobs-in-a-container). So every distro and minimal image above is a Linux container: job. Silverblue/kinoite on a real ostree host, and a real KDE session, need a VM or a self-hosted runner. Flatpak can be built and run headless on ubuntu.

Approaches

Decision 1 -- which artifacts are static (policy)

What CGO_ENABLED=0 costs, for users rather than for images: pure-Go os/user parses /etc/passwd instead of asking NSS (LDAP/sssd users lose only the user name in trace records, since trace.go:143 tolerates the error), and the pure-Go resolver stops honouring nsswitch.conf and the host resolver's configuration (on Linux; this is the whole trade-off. On macOS CGO_ENABLED=0 changes nothing: since Go 1.20 net and os/user there call the system resolver and user database without cgo, https://go.dev/doc/go1.20#cgo). It matters for hostnames mcpx resolves itself: daemon.endpoint, HTTP MCP servers, the registry. Inside a container neither matters.

• A -- flip the default nix package to CGO_ENABLED=0 on Linux. One artifact, static everywhere. But it changes DNS and user lookup for every nix user on a Linux desktop to fix a problem only containers and tarballs have, and the installed bin/mcpx is still a wrapper with nix-store paths, so the nix package does not become copyable anyway. Not recommended.
• B -- static only through the container build arg (docker build --build-arg CGO_ENABLED=0, already wired in Phase 5: tag event bodies must travel with the event #182). No new package, nothing changes for nix users. But there is no static artifact outside an image -- nothing for amd host fails at evaluation: no outputHashes for p2panda-core-0.7.1 #158's release tarball, and nothing for the tier-2 images below to copy except by rebuilding in each Dockerfile.
• C -- keep the default nix package as it is; add a Linux mcpx-static output (recommended). env.CGO_ENABLED = 0, no wrapper, Linux only (darwin cannot be fully static and keeps the system resolver). It is the artifact every container entry copies and amd host fails at evaluation: no outputHashes for p2panda-core-0.7.1 #158 ships in a tarball, with a test that go version -m reports CGO_ENABLED=0 and file reports "statically linked". The Containerfile's default (ARG CGO_ENABLED=1) is the GIT architect's to set; C does not depend on it. Recommended because it gives the static artifact to the places that need it without changing name resolution for anyone who installed the ordinary package.

Decision 2 -- how far to go

A -- attempt the whole list as tier 1 (least recommended)

Every entry gates merges. CI time would exceed any budget (#95), Windows fails until a port is done, and silverblue needs self-hosted infrastructure. The first red flatpak job would train everyone to ignore CI.

B -- containers only

Add the Linux container: entries (alpine, distroless, scratch, fedora, ubuntu) as tier 2 nightly. Declare flatpak, silverblue and Windows out of scope. This is cheap and covers most real deployments. It drops a user-stated wish (windows-11) without a plan.

C -- tiers, with a static build first (recommended)

1. Ship the static artifact chosen in decision 1 (C: a Linux mcpx-static output, env.CGO_ENABLED = 0, no wrapper) with its test (go version -m reports CGO_ENABLED=0, file reports "statically linked"). Phase 5: tag event bodies must travel with the event #182 already showed the build works; this makes it a product. It is the artifact every container entry copies.
2. Tier 1 (gates merges): ubuntu host, nix. Already in Update Rust crate rand to v0.9.3 [SECURITY] #134.
3. Tier 2 (nightly): macOS, debian-slim (including Phase 5: tag event bodies must travel with the event #182's Containerfile), distroless/cc, alpine, scratch. Each runs the Update Rust crate rand to v0.9.3 [SECURITY] #134 labels its surface supports. For example, scratch runs everything except tests labelled needsRuntime, so the label system from Update Rust crate rand to v0.9.3 [SECURITY] #134 and Update dependency argoproj-labs/argocd-autopilot to v0.4.20 #137 gains needsRuntime:<deno|bun|node|any> -- and needsGit for the repo/worktree scopes, unless the GIT architect's native git resolution removes that dependency (from Phase 2: removal: weak is stored but not built #161). Where an image lacks what a test needs, prefer asserting mcpx's own refusal over skipping: no JavaScript runtime found is a feature, a crash is a bug, and only a run that expects the failure can tell them apart (from Phase 2: removal: weak is stored but not built #161).
4. Tier 3 (best-effort or manual, on release): fedora, toolbox, flatpak, silverblue VM, and Windows. The Windows port is its own design issue (process groups, detach, socket vs TCP). It becomes tier 2 once GOOS=windows go build passes, and a cheap go vet-level cross-compile check can go into tier 1 right away to stop it getting worse.

Recommended because it turns an unverified claim into a checked property, orders the work by users reached per unit of effort, and keeps every wish-list item on a path, not dropped.

Make the tiers mean something with entry and exit rules (from #163): tier 1 admits a platform where a bug has been found or an artifact that ships; tier 2 admits a plausible user environment that runs unattended and passes its surface; a tier-2 leg with no finding for two months is demoted; each tier-3 item gets one paragraph now saying what it would cost and what it would prove, so "ideally would like if worked" becomes a decision someone can revisit rather than a list re-argued every quarter. #163 also argued macOS belongs in tier 1, not 2: #35 is the only cross-OS bug on record, and a parallel leg costs queue time, not wall clock. Decide against #95's budget (#140).

Open questions

• Is CGO_ENABLED=0 acceptable for the default Linux nix package too, or only for a -static variant? Now decision 1 above (recommended: a -static variant; feasibility was settled by Phase 5: tag event bodies must travel with the event #182).
• What is bun's first release with musl builds, and does the pinned bun (1.3.11) have one? Does bun's unix-socket fetch work on musl?
• Is a Windows port wanted at all, or is WSL2 (which is ubuntu, tier 1) the supported Windows story? If WSL2 is the answer, "windows-11" becomes a doc page plus a WSL2 smoke job.
• Flatpak: is there a real user for it, given the sandbox fights the whole design (spawning host processes)? Proposal: tier 3 "documented as unsupported" unless a user appears.
• Should the static image default to daemon.inline=true, since there is no init to reap children?
• meta.platforms = lib.platforms.unix: narrow it to linux ++ darwin to match what is tested, or keep the BSD claim as an aspiration (from Phase 2: group action codec does not cover friendship or policy #163)?
• Who triages a nightly failure? A nightly nobody reads is worse than none; Bump unsafe-libyaml from 0.2.8 to 0.2.10 in /sources/pavex/examples/realworld #99 should name the owner (from Phase 2: group action codec does not cover friendship or policy #163).
• macos-latest is arm64, so a macOS leg is also a second architecture; ubuntu-24.04-arm is the Linux arm64 leg (Update Rust crate rand to v0.9.3 [SECURITY] #134).

Ease · Impact · Related

Ease XL as a whole (static build and tier-2 containers: M; Windows port: L; silverblue/flatpak: M each, self-hosted) · Impact med (tier 2), low-med (tier 3)
Depends on / related: #134 (container image and #182's Containerfile, labels, matrix entries), #137 (which real servers each image must carry), #133 (binary override to test a copied binary), #158 (the release tarball ships the static artifact), #95 (tiers map to PR/nightly/release workflows), #49, #35 (the Linux/macOS split that motivates cross-OS runs), #99.

Security/auth deferred; see tracker.

Acceptance criteria

• The extended-platforms question is answered with evidence: which artifacts ship static, and the alpine/scratch/container legs specified in the body run or are explicitly deferred with reasons recorded on this issue.
• The work described in the Summary/Scope above is delivered via a branch + PR (no direct push to main); verification runs in GitHub Actions CI, not on the sandbox.
• Evidence (CI links, timings, or probe output as applicable) is recorded on this issue before it is closed.