Agent Capability Matrix¶
Swarm Hosts agents share one task and heartbeat contract across operating systems. A platform may report a capability as unsupported, blocked, or experimental, but the control plane should still receive the same top-level fields and task semantics.
Linux remains the production baseline. Windows support is a foundation path
with validated registration, heartbeat, platform capability reporting, a
supported Docker Desktop/compatible Linux-container runtime gate for container
deployments, and an expanded native vanilla Minecraft parity slice. A Windows
host is not considered container-ready unless the agent account can run Docker
and Docker reports OSType=linux; Windows-container mode is blocked.
Linux parity now has its own distro/runtime validation matrix. Docker remains the default Linux runtime when it is available. The agent also supports a Podman runtime adapter for deployment lifecycle, registry login, image pull/prune, logs, inspect, RCON/game-command, and rootless capability reporting. Podman rootful and rootless entries still need distro-family live evidence before the matrix should mark them validated.
Status Key¶
| Windows classification | Meaning |
|---|---|
| Already equivalent | Windows uses the shared agent/control-plane contract and has enough implementation evidence to treat the behavior like Linux. |
| Equivalent via native Windows implementation | Windows reaches the same user outcome through Windows APIs, paths, services, or native processes instead of Linux tools. |
| Equivalent via Docker/WSL/runtime integration | Windows should use a Linux-container-capable Docker/WSL/runtime path to match the Linux game image model. |
| Implemented, pending live proof | Behavior is implemented in draft/runtime PRs and docs, but support claims are blocked until repeatable live evidence is recorded. |
| Intentionally unsupported | The Linux behavior depends on Linux-only kernel or networking tools and should be replaced with a documented Windows alternative. |
| Unknown / needs validation | Code may exist, but the Windows behavior still needs implementation hardening, lab proof, or UI/docs limits before support can be claimed. |
Recommended Windows Architecture¶
Use a hybrid Windows architecture:
- Keep one shared swarm host agent codebase and one control-plane task contract. Add platform adapters only where the operating system requires different service, filesystem, process, firewall, or runtime behavior.
- Use Docker Desktop or another Windows-accessible Docker CLI connected to a
Linux-container-capable engine as the preferred path for the broad game
catalog. This is the only architecture that can provide real parity with
Linux Docker images, volume semantics, container logs, metrics, and cleanup.
WSL2 Docker Engine is acceptable only when the Windows agent can drive it
through
docker.exewith Windows bind mounts and published ports. - Keep native Windows Minecraft Java process mode as the Minecraft-first fallback for Windows hosts where Docker/WSL Linux containers are unavailable. It is useful for vanilla Minecraft management parity (lifecycle, status, logs, backups/restores, import, file-manager, and command actions), but it is not a replacement for Docker parity across the catalog.
- Treat Windows Server as a foundation-agent platform until a supported Linux-container runtime architecture is selected. Docker Desktop is a Windows 10/11 path, not a Windows Server support path.
- Do not port Linux-only packet capture or WireGuard relay-host tooling directly to Windows unless a later issue proves a product-safe Windows equivalent. Prefer protocol-level probes, relay diagnostics, and system-owned relay nodes.
Current Platform State¶
| Capability | Linux behavior | Windows behavior | Windows classification | Tracking or decision |
|---|---|---|---|---|
| Product support posture | Recommended production host platform. | Foundation support when Linux-container runtime parity is established; Windows-native fallback remains a legacy lab mechanism and is not a production support claim. | Unknown / needs validation | Roadmap is this matrix plus #149, #150, #152, #153, and #154. Legacy native-fallback work remains in #151. |
| Agent registration and identity | Registers with a user token and stores identity under the agent identity path. | Shared registration path works. Interactive runs default to the user profile identity path; the Windows service installer uses C:\ProgramData\SwarmHosts\agent\identity.json. |
Already equivalent | Keep shared contract covered by #154. |
| Heartbeat and task polling | Sends heartbeat metadata and polls the same task queue. | Shared path works on Windows. | Already equivalent | Keep parity-drift checks in #154. |
| Platform/version/IP/health telemetry | Reports platform, agent version, public/private IPs, runtime status, data-root health, disk, CPU, memory, and network counters where available. | Reports normalized platform_family=windows, Windows release/edition, agent version, IPs, runtime status, data-root health, and resource fields where the standard library can read them. |
Already equivalent | Keep rendering and heartbeat coverage in #154. |
| Capability warnings | Linux reports unavailable optional features such as Docker or raw-packet permissions. | Windows reports Docker/Linux-container requirements, Windows Server Docker Desktop limitation, native Minecraft mode status, and Linux-only probe limits. | Already equivalent | Covered by current host detail UI and support reports. |
| Data root defaults | Defaults deployments to /var/swarm/deployments. |
Defaults deployments to C:\ProgramData\SwarmHosts\deployments. |
Equivalent via native Windows implementation | Windows file/backup edge cases remain in #153. |
| Service installation | systemd example is documented; production hosts can run the binary as a service. | NSSM-backed service installer supports idempotent install/reconfigure, startup-on-boot, first-registration token clearing, update, rollback, uninstall with identity/data preserved by default, diagnostics, and logs under C:\ProgramData\SwarmHosts\logs. Reboot and clean Windows 10/11 lab proof are still required before closing the production support claim. |
Unknown / needs validation | #149. |
| Agent binary build | Linux PyInstaller build script produces the downloadable agent artifact. | Windows PyInstaller build script produces downloads\swarm-agent.exe when run on Windows. Artifact availability, signing/release discipline, and update/rollback need hardening. |
Unknown / needs validation | #149 and #154. |
| Agent auto-update action | Compiled binary installs can check for and perform agent updates. | Service-managed Windows installs launch the installer-owned update path, which stops the service, downloads the Windows artifact, backs up the previous binary, replaces it, restarts, and records rollback state. Live lab proof is still required. | Unknown / needs validation | #149. |
| Container runtime readiness | Structured docker info or podman info gates deployment readiness. Linux auto-detect prefers Docker when ready and falls back to Podman; SWARM_CONTAINER_RUNTIME=podman forces Podman. |
The agent runs structured Docker readiness checks, records engine facts, and marks readiness only when Docker reports OSType=linux. Missing Docker, timeouts, Windows-container mode, and unknown container OS are blocked with actionable messages. |
Equivalent via Docker/WSL/runtime integration | Linux Podman parity: #156. Windows Docker parity: #150. |
| Automatic runtime install/start | Best-effort package-manager install/start on common Linux hosts. Auto mode installs Docker on apt-style hosts and Podman on Fedora/RHEL/openSUSE-style hosts. Docker uses systemctl enable --now docker; Podman is treated as daemonless for agent lifecycle checks. |
Not supported. Users must install/start Docker Desktop, WSL2 Docker Engine, or another approved runtime. | Intentionally unsupported | Manual runtime setup remains documented; production runtime path tracked by #150. |
| Container deployment lifecycle | Docker and Podman create/start/stop/restart/delete/update paths are supported for game images, with rootless Podman limitations reported in host capabilities. | Uses the shared Docker lifecycle when the Windows runtime reports Linux containers. Data roots default to C:\ProgramData\SwarmHosts\deployments; Docker Desktop file sharing or WSL path access and Windows Firewall rules must allow mounted data and published ports. |
Equivalent via Docker/WSL/runtime integration | Linux Podman parity: #156. Windows Docker parity: #150. |
| Registry login and image pulls | Agent logs into the configured registry with the selected runtime and pulls missing game images. | Uses the shared Docker path when the Windows runtime is Linux-container-capable; Windows defaults to an agent-owned Docker CLI config directory so service/SSH sessions do not depend on Docker Desktop's interactive credential helper. Otherwise blocked before deployment tasks run. | Equivalent via Docker/WSL/runtime integration | #150. |
| Broad game catalog | Linux container images are the supported catalog model through Docker or Podman. | Supported through Docker Desktop or a compatible Windows-accessible Linux-container Docker engine. Windows-container-only Docker and Docker daemons reachable only inside an unmanaged WSL shell are not supported Windows-agent paths. Native Windows game adapters should be added per game only when they can match user flows. | Equivalent via Docker/WSL/runtime integration | #150. |
| Minecraft Java through container runtime | Supported through the shared Linux-container game image path with Docker or Podman. | Supported through the shared Linux-container image path when the Windows Docker runtime reports OSType=linux; live per-host proof should include startup logs, Minecraft Java status, RCON/game-command delivery, lifecycle, and cleanup. |
Equivalent via Docker/WSL/runtime integration | Linux Podman parity: #156. Windows Docker parity: #150. |
| Native Minecraft Java process | Not needed for the default Linux path. | Legacy native Windows fallback remains experimental and is not part of production support claims; keep only for scoped lab reproduction. | Intentionally unsupported | Legacy native fallback is tracked in #151. |
| Minecraft version selection and server properties | Linux image supports version/env configuration through container environment and mounted data. | Legacy native fallback version handling exists for lab verification but is intentionally not claimed as support parity. | Intentionally unsupported | #151. |
| Start/stop/restart/delete | Supported for Docker and Podman deployments. | Linux-container parity remains the supported Windows lifecycle path; native-process lifecycle mappings are retained as legacy lab behavior only. | Intentionally unsupported | Docker parity: #150. Legacy fallback: #151. |
| Reconcile after agent restart or host reboot | Agent reconciles Docker and Podman deployments and reports missing/running state. | Legacy native-process stale-workload cleanup is a lab artifact and not a supported parity claim. | Intentionally unsupported | #151 and #149. |
| Deployment logs | Docker and Podman logs are synced to the control-plane log store. | Native-process log handling is legacy lab behavior; supported log parity remains container-runtime dependent. | Intentionally unsupported | Legacy fallback: #151. File/log surfaces: #153. |
| Deployment stats and resource reporting | Container stats can report CPU and memory usage/limits from the selected Docker or Podman runtime when available. | Legacy native fallback has JVM-specific memory visibility; production resource reporting parity is defined by container runtime behavior. | Intentionally unsupported | #151. |
| Resource limits | Linux selected-runtime path enforces container memory/CPU where configured, with rootless Podman caveats surfaced as runtime limitations. | Legacy native fallback does not provide Docker-style container CPU controls and is not a support-parity surface. | Intentionally unsupported | #151. |
| Host-local monitoring stack | Docker Compose or Docker-managed monitoring containers run on validated Linux hosts. | Not validated on Windows. It should follow the Docker/WSL runtime decision or remain unsupported with diagnostics. | Unknown / needs validation | Runtime dependency: #150. Automated proof: #154. |
| Game metrics sidecars | Supported for Docker deployments that configure sidecar metrics. | Depends on Docker/WSL runtime parity; not supported for native Minecraft process mode today. | Unknown / needs validation | #150 and #151. |
| Host IP and endpoint reporting | Agent reports public/private addresses and assigned ports; control plane renders direct/relay/local endpoints. | Shared reporting exists, but Windows firewall/NAT/relay diagnostics need product proof. | Implemented, pending live proof | #152. |
| Windows Firewall behavior | Linux docs assume host/router firewall configuration outside the agent. | Windows now includes managed rule orchestration in PR #177, but parity claims remain gated on live validation. | Implemented, pending live proof | #152. |
| Router/UPnP port mapping | Agent can sync desired port mappings when mapping features are enabled. | Code is platform-neutral and shares path coverage with live parity targets in PR #175/#177, but Windows behavior and firewall interaction still need proof. | Implemented, pending live proof | #152. |
| Relay-backed deployment reachability | Linux deployments can use relay selection and public probe diagnostics. | Windows must prove backend route, listener, firewall, relay, and user-facing endpoint behavior before parity is claimed. | Implemented, pending live proof | #152. |
| Minecraft Java status probe | Linux validation uses the actual Minecraft Java protocol endpoint, not TCP alone. | Native status checks are implemented in PR #175. Public/relay-path persistence and diagnostics still need parity work. | Implemented, pending live proof | #152. |
| Generic UDP packet observation | Linux can use raw AF_PACKET capture with CAP_NET_RAW for generic UDP public-health observations. |
Not supported because Windows does not provide the Linux AF_PACKET path. Use protocol-level probes and relay/public probe records instead. |
Intentionally unsupported | Documented exception. Windows diagnostics tracked by #152. |
| WireGuard relay host mode | Supported when wg, wg-quick, and ip are installed. |
Not supported by current Windows agent tooling. Windows user hosts should use system-owned relay infrastructure, not act as relay nodes. | Intentionally unsupported | Documented exception; no child issue required for user-host parity. |
| File manager task operations | Supports list/read/write/upload/delete/move/mkdir/download inside deployment data roots. | Windows file parity remains container-runtime dependent; legacy native fallbacks are not support claims. | Intentionally unsupported | #153. |
| File gateway HTTP service | Agent can expose a token-protected gateway service for deployment files. | Shared service can bind on Windows; parity is validated through container runtime pathways when present, with firewall/TLS/user-facing transport still gated by Windows-container support. | Unknown / needs validation | #153 and #152. |
| File transfer WebRTC | Supported when dependencies load and network path works. | Capability reports dependency status; Windows container-runtime pairing still determines whether this path is production-relevant. | Unknown / needs validation | #153 and #154. |
| Backups and restores | Docker path can create, upload, hydrate, and restore archives, stopping containers when needed. | Windows support is container-runtime-first; legacy native restore behavior is not a parity promise. | Unknown / needs validation | #153 and #150. |
| Minecraft world import | Linux path validates source folders, creates safety backups, and copies world/server data. | Windows parity is expected through the container runtime; legacy native import flow is not claimed as supported. | Unknown / needs validation | #153. |
| Minecraft RCON/game commands | Linux uses docker exec ... rcon-cli. |
Windows support depends on runtime path; legacy native RCON process mapping is not a production support surface. | Unknown / needs validation | Native fallback: #151. Docker parity: #150. |
| Minecraft admin action workflows | Linux supports scheduled Give Item and Saved Kit requests, recurring actions, approval/collaboration metadata, and offline policies through the shared structured admin-action queue in #302 and #306. Parent #301 adds server-aware item-registry discovery so Give Item can validate non-minecraft: IDs from modded deployments when runtime reports catalog freshness; #303 adds structured advanced Give Item metadata templates and compatibility-aware parsing while preserving the simple flow; #304 adds pending offline delivery keyed by player UUID with next-join replay semantics; and #305 adds broader safe command template/action families. |
Windows shares the same control-plane task surface; runtime claims remain pending until live proof is recorded for server-aware catalog freshness/discovery in #301 and scheduled/approval coverage in #302 and #306, plus deeper #303/#304/#305 surfaces. | Implemented, pending live proof | #301, #302, #303, #304, #305, #306. |
| Support report and copied diagnostics | Includes platform, version, runtime, recent action history, and sanitized context. | Host heartbeats and support reports now include Windows service state, configured identity/data/log/update paths, update state, and runtime diagnostics in PR #177. Windows file/backup diagnostics remain tracked separately. | Implemented, pending live proof | #149, #152, and #153. |
| Runtime repair actions | Linux supports guarded image prune with Docker or Podman. Docker/containerd cache reset remains Docker-specific and is reported unavailable when Podman is selected. Monitoring repairs and agent update actions remain separate host operations. | Docker-specific repairs should be disabled or adapted until the supported Windows runtime is selected. Agent update/service repairs need production hardening. | Unknown / needs validation | #149, #150, and #153. |
| CI and packaging smoke | Linux paths are covered by the default CI/test suite. | Basic Windows smoke exists, but it does not yet prove install/service/runtime/Minecraft parity automatically. | Unknown / needs validation | #154. |
| Live parity validation | Linux runtime validation is the baseline for new deployment behavior. | Windows validation is currently manual lab work. Repeatable sanitized lab evidence is needed for future parity claims. | Unknown / needs validation | #154. |
Linux Distro And Runtime Matrix¶
The Linux matrix tracks distribution families separately from the container runtime mode. A combination is not considered validated until the child issue records preflight evidence plus live install, registration, deployment lifecycle, Minecraft Java status protocol, RCON/game-command, logs, cleanup, and support-report proof.
| Distro target | Docker Engine | Podman rootful | Podman rootless |
|---|---|---|---|
| Ubuntu LTS | Verified in PR #179; validation issue #158. | Verified in PR #178; tracked by #158. | Conditional implemented target; rootless remains limited until distro-specific rootless proof is product-safe. |
| Debian stable | Verified in PR #179; validation issue #158. | Verified in PR #179; validation issue #158. | Conditional implemented target; rootless remains limited until distro-specific rootless proof is product-safe. |
| Fedora | Verified in PR #180; validation issue #159. | Implemented but unverified target; validate in #159. | Conditional implemented target; validate rootless limits in #159. |
| Rocky/Alma/RHEL-compatible | Verified in PR #180; validation issue #159. | Implemented but unverified target; validate in #159. | Conditional implemented target; validate rootless limits in #159. |
| openSUSE | Unverified target; validate in #160. | Implemented but unverified target; validate in #160. | Conditional implemented target; validate rootless limits in #160. |
| Arch/Manjaro rolling | Unverified target; validate in #160. | Implemented but unverified target; validate in #160. | Conditional implemented target; validate rootless limits in #160. |
Use scripts/validation/linux_runtime_matrix.py and
Linux Runtime Parity Validation to
generate sanitized matrix artifacts. Podman entries must not be promoted from
unverified until deployment lifecycle, Minecraft status, RCON/game-command,
logs, cleanup, and support reports pass on the selected distro family. Rootless
Podman also needs subordinate UID/GID, rootless networking, high-port, and
user-service survival proof before it should be treated as product-safe.
Roadmap¶
- Production-grade Windows agent lifecycle: finish install, service, update, rollback, uninstall, reboot survival, and service diagnostics in #149.
- Linux-container runtime parity: use Docker Desktop or another Windows-accessible Docker CLI connected to a Linux-container engine on Windows 10/11, and keep direct WSL-only or helper VM approaches out of the supported path until they prove Windows bind-mount, port publishing, firewall, logs, lifecycle, and cleanup parity in #150.
- Minecraft-first native path (legacy): maintain native Windows vanilla Minecraft as a scoped lab fallback only, and do not treat it as a supported parity lane. Remaining work focuses on Linux-container runtime parity, relay health, and release-safe deployment support in #150 and #151.
- Networking and relay parity: define Windows Firewall behavior, endpoint selection, relay diagnostics, and protocol-level public probe persistence in #152.
- Files, backups, and support diagnostics: harden Windows-safe path handling, file manager behavior, backup/restore, log access, and sanitized support reports in #153.
- Parity automation: add CI and lab scripts that make Windows drift visible before support claims regress in #154.
No additional child issue is required from this matrix as of this update: non-equivalent Windows gaps are either linked above or documented as Linux-only exceptions.
macOS Note¶
macOS is not part of the Windows parity roadmap. The agent can normalize Darwin
as platform_family=macos, but game-hosting support on macOS should not be
claimed until separate Docker/runtime, service, firewall, and live deployment
validation exists.
Heartbeat Contract¶
Agents report stable platform keys in host_info:
platform_family: normalized platform family such aslinuxorwindowsplatform_system,platform_release,platform_version,platform_machineruntime_name,runtime_platform,runtime_status,runtime_ready,runtime_mode,runtime_rootless, andruntime_limitationsruntime_container_os,runtime_engine,runtime_server_version,runtime_driver, and related Docker engine facts when Docker respondscapabilities: structuredsupported,available,status, anddetailfields for runtime, lifecycle, Minecraft, gateway, probes, relay, service, and update behaviorcapability_warnings: human-readable limitations surfaced in the host detail page and support reports
When a capability differs by platform, document the reason here and keep the agent/control-plane API contract unchanged.