Windows Swarm Host Agent

Windows support is in foundation status. The shared Python agent can import on Windows, register with the control plane, run under a Windows Service, send heartbeats, report platform/service/update/log diagnostics, report Docker readiness, and expose its current capability limits. The supported Windows container path is Docker Desktop or a compatible Windows Docker CLI connected to a Linux-container engine. The agent blocks Docker readiness when Docker is missing, unreachable, in Windows-container mode, or unable to report its container OS. Linux remains the recommended production host path. For Windows Minecraft, a native Java process adapter for vanilla Minecraft is the fallback path when Docker Desktop or WSL2 cannot provide Linux containers. It is an experimental parity slice for lab validation and is not a production-equivalent Windows-hosting path outside scoped vanilla Minecraft validation.

For the complete Linux-vs-Windows support inventory and implementation roadmap, see the Agent Capability Matrix. The roadmap tracks each non-equivalent Windows gap to a follow-up issue or a documented Linux-only exception.

Windows Minecraft Host Path

Use this decision order for Windows Minecraft hosts:

  1. Prefer Docker Desktop or a compatible Docker Engine that can run Linux containers on Windows 10/11. This keeps the same Docker image path as Linux. The host should report Docker runtime: Ready, and docker info --format '{{.OSType}}' must return linux from the same account that runs the agent.
  2. Use a WSL2 Docker Engine only when the Windows agent can reach it through a Windows docker.exe path that supports Windows bind mounts and published ports. A Docker daemon reachable only inside an interactive WSL shell is not a supported Windows-agent runtime path.
  3. Use the native Minecraft process mode for vanilla Minecraft on Windows hosts where Docker Desktop or WSL2 Linux containers are unavailable or blocked. It currently includes lifecycle actions, status checks, logs, backup/restore, import, file-manager tasks, and Minecraft command actions in the scoped parity slice.
  4. Treat Windows Server as a foundation-agent platform until a supported Linux-container runtime architecture is selected. Docker Desktop is not a Windows Server runtime path.

The native path starts java -jar server.jar nogui directly on Windows and keeps the same control-plane task contract for deploy, start, stop, restart, delete, logs, backup/restore, file manager actions, import, and Minecraft RCON/game-command tasks. It does not provide Docker image parity, container isolation, or support for non-vanilla Minecraft images.

The recommended parity architecture is hybrid: use native Windows implementations for agent service/install behavior and the current vanilla Minecraft fallback, but use Docker Desktop, WSL2 Docker Engine, or another Linux-container-capable runtime for Linux-equivalent hosting across the broader game catalog.

Requirements

  • Windows 10/11 with administrator access when using Docker Desktop.
  • Windows Server 2022 may run the foundation agent registration/service path, but Docker Desktop is not supported on Windows Server. Windows Server hosts need a separate Linux-container-capable runtime architecture before Docker game deployments should be expected to work.
  • Docker Desktop or another compatible Docker Engine that can run Linux containers. Current game images are Linux containers, so Windows-container-only Docker is not enough.
  • docker info --format '{{json .}}' must complete within five seconds and report OSType as linux for the agent account. If it reports windows, switch Docker Desktop to Linux containers before launching deployments.
  • On Windows, the agent uses an agent-owned Docker CLI config directory under the data root by default so service or SSH sessions do not depend on Docker Desktop's interactive credential helper. When Docker Hub or registry credentials are configured, the agent writes that registry auth into this managed config. Set SWARMHOST_DOCKER_CONFIG to a different writable directory only when you intentionally manage Docker CLI credentials there.
  • For native Minecraft-only parity mode, Java must be installed and SWARMHOST_NATIVE_MINECRAFT_ENABLED=1 must be set for the agent process. The Get Started installer can set that service environment with -EnableNativeMinecraft; pass -NativeMinecraftJava if java.exe is not on PATH. This path is not a replacement for the shared Docker runtime for other games.
  • Outbound HTTPS access to https://swarmhosts.com.
  • Windows Firewall rules for any game ports, file gateway ports, or relay paths you choose to expose.
  • A Swarm Hosts agent token from Profile -> Agent token.

Build The Native Artifact

PyInstaller must build Windows binaries on Windows.

.\scripts\release\build_agent_windows.ps1

To build a Windows artifact that matches an already-deployed control-plane agent version, pass the version stamp explicitly:

$version = (Invoke-RestMethod 'https://swarmhosts.com/agent/version').version
.\scripts\release\build_agent_windows.ps1 -VersionStamp $version

The script writes:

downloads\swarm-agent.exe

The repository also ships the Windows service installer script:

scripts\release\install_agent_windows_service.ps1

When that artifact exists, the control plane serves it from:

https://swarmhosts.com/agent/download/windows

Production operators can publish a Windows-built artifact into the web deployment's persistent downloads volume from a machine with the production Kubernetes context:

WINDOWS_AGENT_ARTIFACT=/path/to/swarm-agent.exe ./scripts/release/publish_windows_agent_artifact.sh

The existing Linux artifact remains at:

https://swarmhosts.com/agent/download

Install And Register

Create the agent directory:

New-Item -ItemType Directory -Force 'C:\Program Files\SwarmHosts\Agent'
Set-Location 'C:\Program Files\SwarmHosts\Agent'

Download the Windows artifact:

Invoke-WebRequest -Uri 'https://swarmhosts.com/agent/download/windows' -OutFile .\swarm-agent.exe

Start the agent interactively:

.\swarm-agent.exe --name <HOST_NAME> --user-token <USER_TOKEN> --data-root 'C:\ProgramData\SwarmHosts\deployments'

Leave the process open until the host appears in Swarm hosts and reports Docker runtime: Ready.

Native Minecraft Runtime (parity slice)

Windows hosts may use a Windows-native Minecraft Java process when Docker Desktop or WSL2 cannot provide a Linux-container runtime on a lab VM. Enable it for scoped vanilla Minecraft parity validation:

$env:SWARMHOST_NATIVE_MINECRAFT_ENABLED = '1'
.\swarm-agent.exe --name <HOST_NAME> --user-token <USER_TOKEN> --data-root 'C:\ProgramData\SwarmHosts\deployments'

This adapter supports Minecraft Java TYPE=VANILLA only. It downloads the official Mojang server jar for the requested VERSION (cached per version), preserves key existing server.properties values such as level-name, starts java -jar server.jar nogui, reports a native-process:<pid> runtime id, and maps start/stop/restart/delete to Windows process lifecycle operations. It is intended to prove the Windows agent task contract and Minecraft protocol path while Docker Desktop is blocked. MEMORY maps to JVM heap size, and CPU is reported as Docker-required in this native process path.

The lab slice has covered Windows host registration and heartbeat, native Minecraft startup, external Minecraft Java status handshake, RCON/game-command delivery, stop/start/restart/delete lifecycle, stale-process reconciliation, backup/restore/import, file-manager tasks, logs, and cleanup. Re-run live validation for the same scope before promoting this path beyond the native parity slice.

Run As A Windows Service

The Windows service installer uses NSSM as the service wrapper. Install NSSM first, or place nssm.exe beside swarm-agent.exe.

Download and run the service installer:

Invoke-WebRequest -Uri 'https://swarmhosts.com/agent/install/windows-service.ps1' -OutFile .\install_agent_windows_service.ps1
.\install_agent_windows_service.ps1 -Action Install -AgentPath .\swarm-agent.exe -Name <HOST_NAME> -UserToken '<USER_TOKEN>' -DataRoot 'C:\ProgramData\SwarmHosts\deployments' -Start

The installer stores the first-registration token in the NSSM service environment instead of the service command line. After the host appears in Swarm Hosts and C:\ProgramData\SwarmHosts\agent\identity.json exists, remove the token from the service environment:

.\install_agent_windows_service.ps1 -Action ClearToken
.\install_agent_windows_service.ps1 -Action Restart

Re-running -Action Install is safe. It reconfigures the existing service with the current binary path, identity path, data root, log path, and service environment.

Service logs are written to:

C:\ProgramData\SwarmHosts\logs\swarm-agent.out.log
C:\ProgramData\SwarmHosts\logs\swarm-agent.err.log

Service identity and update state are stored under:

C:\ProgramData\SwarmHosts\agent\identity.json
C:\ProgramData\SwarmHosts\agent\update-state.json
C:\ProgramData\SwarmHosts\agent\backups\

Keep tokens out of screenshots, logs, shell history, and GitHub comments.

Update, Roll Back, And Uninstall

The installer owns Windows service updates because a running Windows .exe cannot be replaced reliably by the process that is currently executing it.

Update the service-managed agent:

.\install_agent_windows_service.ps1 -Action Update -Start

The update action downloads the current Windows agent from https://swarmhosts.com/agent/download/windows, stops the service, backs up the old binary under C:\ProgramData\SwarmHosts\agent\backups\, replaces the binary, reconfigures the service, and starts it again. If replacement or start fails after a backup exists, the installer attempts to restore the previous binary and records the result in update-state.json.

Roll back to the latest backup:

.\install_agent_windows_service.ps1 -Action Rollback -Start

Check service diagnostics:

.\install_agent_windows_service.ps1 -Action Diagnostics

Diagnostics include service state, configured paths, agent binary metadata, identity-file presence, Docker readiness, update state, and redacted recent agent log lines. They do not print the agent token.

Uninstall removes only the Windows service by default and preserves host identity and deployment data:

.\install_agent_windows_service.ps1 -Action Uninstall

To intentionally remove the cached host identity too:

.\install_agent_windows_service.ps1 -Action Uninstall -RemoveIdentity

Deployment data is preserved unless you pass both -RemoveData and -ConfirmDataRemoval DELETE_SWARMHOSTS_DATA.

Troubleshooting

Check Docker from the same account that runs the agent:

docker info
docker info --format '{{.OSType}}'

If Docker is missing, times out, reports windows, or fails to report an OSType, the host will register but deployment lifecycle capabilities will show as blocked. The Windows service installer diagnostics use the same Linux-container check as the agent heartbeat.

On Windows Server, do not treat a stopped or failing Docker Desktop install as a supported production runtime. Use the host detail page capability warnings to confirm whether the runtime is ready before launching Minecraft.

If a deployment fails during docker run with a bind-mount or sharing error, confirm Docker Desktop can access C:\ProgramData\SwarmHosts\deployments or move --data-root to a Windows path shared with the Linux-container engine. If an SSH or Windows Service run fails before pulling with a Docker credential helper or logon-session error, make sure the agent can write its Docker CLI config directory or set SWARMHOST_DOCKER_CONFIG to a clean writable path for the service account. If the container starts but players cannot connect, allow the assigned game ports through Windows Firewall or use the managed relay path.

Check the service logs:

Get-Content C:\ProgramData\SwarmHosts\logs\swarm-agent.err.log -Tail 100

Check the installer diagnostics:

.\install_agent_windows_service.ps1 -Action Diagnostics

Open the Swarm Host detail page and review Platform capabilities. Windows hosts should explicitly show unsupported Linux-only probe/relay features instead of silently looking identical to Linux hosts.

Current Limitations

  • Full Windows parity is tracked in the Agent Capability Matrix; do not treat a Windows host as equivalent to a Linux production host until the relevant matrix rows are marked equivalent.
  • Generic UDP packet observation uses Linux raw socket behavior and is not available on Windows.
  • WireGuard relay host mode depends on Linux tools in the current agent.
  • Docker installation is manual on Windows.
  • Docker Desktop is a Windows 10/11 runtime path, not a Windows Server runtime path. Windows Server needs a separate supported Linux-container runtime before Minecraft parity can be claimed.
  • Docker readiness on Windows requires Linux-container mode. Windows-container Docker engines are blocked because Swarm Hosts game images are Linux containers.
  • Minecraft Java deployment lifecycle through Docker uses the shared task path when the Windows Docker runtime reports Linux containers; each Windows host still needs live deployment proof before it should be used for production gameplay.
  • Native Minecraft process mode is Windows-only, opt-in, and limited to vanilla Minecraft. It has initial lab evidence for registration, heartbeat, startup, Java status reachability, RCON/game commands, lifecycle, stale-process reconciliation, backups/restores, imports, file-manager tasks, and cleanup, and remains experimental until #151 has repeatable live-Windows validation evidence. It does not provide Docker image parity, container resource limits, or support for the broader game catalog.