Windows Swarm Host Agent¶

Windows 10/11 supports the same user-facing Swarm Host and Swarm Server features as Linux when the installed service can reach Docker Desktop in Linux-container mode. Feature availability still depends on the Windows service account, runtime, filesystem, firewall, and network prerequisites.

Requirements¶

• 64-bit Windows 10 or Windows 11
• administrator access
• a Swarm Hosts account, a one-use enrollment code, and a Windows agent that supports one-use enrollment
• Docker Desktop started in Linux-container mode
• a Windows user account that signs in after reboot so Docker Desktop can start
• enough CPU, memory, and disk for the selected game
• a Swarm Server data directory Docker Desktop can access

Windows Server is not a supported public game-hosting path. Use a supported Linux host or Windows 10/11 with Docker Desktop.

The installer configures Docker Desktop to launch automatically after the installation user signs in. For an unattended host, arrange for Windows to establish that intended user session after reboot or use a supported service-native Linux container engine. Do not configure automatic sign-in on a shared or physically unsecured computer.

If the web app still reports Docker unavailable, follow Windows Docker after-reboot troubleshooting.

Install¶

1. Choose Install agent in the sidebar or on the Swarm hosts page. Select Download Windows installer. If the installer is unavailable, wait for a release before connecting a new Windows computer.
2. Open SwarmHostsAgentSetup.exe. The Swarm Hosts setup wizard shows the logo and website. Windows asks for administrator approval because setup creates a background service.
3. When the wizard asks, generate a code from Profile → Connect a host. Each code connects one host and expires after 15 minutes.
4. Choose the computer name, paste the one-use code into the protected installer field, and finish setup.
5. Wait for the Swarm Host to appear in the web app, then confirm the page reports Docker ready and no blocking capability warning.

If setup reports connection pending, the service is installed but the connection is not confirmed. Check Swarm hosts and the tray app logs. If the computer stays offline, rerun setup with a fresh enrollment code. If installation fails, the wizard displays a retry message and the setup log location at C:\ProgramData\SwarmHosts\setup-logs\setup.log.

Windows security prompts¶

An administrator approval prompt is expected when installing a Windows service. An unknown publisher, SmartScreen, or Smart App Control warning is a separate trust check. If a download is blocked, cancel and contact support; keep Windows security protections enabled. A logo alone does not verify the publisher. Microsoft can still show reputation warnings for newly signed applications. See Microsoft's explanation of SmartScreen reputation.

The installer places the agent in C:\Program Files\SwarmHosts\Agent, starts the SwarmHostsAgent Windows service, and adds the Swarm Hosts tray app for the current Windows user. The tray menu shows service status and the installed version, opens the dashboard or local logs, checks for agent updates, and can restart the agent service after administrator approval. Updating or restarting the agent does not restart running game servers.

The installer clears the one-use code only after the confirmed enrolled identity is saved. A pending identity alone never clears it. Normal uninstall removes the service and tray app while preserving the host identity, game data, logs, and backups.

The Profile page is the recommended authenticated path. These official routes serve the same current artifacts when a direct download is needed:

• Windows agent download
• Windows installer download
• Windows bootstrap installer script
• Windows service installer script

The executable installer is the normal installation path. The raw agent and PowerShell installers remain available for recovery, automation, and service administration.

For advanced first installation, prefer the bootstrap command in the installation guide. Its hidden prompt keeps the code out of your saved PowerShell commands. The service helper is for managing an agent and service manager already installed on the computer.

When using the service helper directly, clear the code only after registration is confirmed in the web app:

.\install_agent_windows_service.ps1 -Action ClearToken

Keep the code out of screenshots, logs, saved command files, and support messages. Prefer the bootstrap installer’s hidden prompt.

Use a dedicated local identity directory owned by the service account, SYSTEM or Administrators with no other writers. The installer prepares new directories; existing directories are checked without changing their permissions. If that check fails after an older installation, have the host administrator prepare the dedicated directory before retrying.

Keep pending-enrollment.json and identity.json private and in place when recovering an interrupted install. The pending file preserves the exact host identity across retries and lost responses. Generate a fresh code if the original expired before enrollment. Existing enrolled hosts keep their credentials and do not need another code. A rejected stored identity is preserved for deliberate recovery.

Managed storage configuration and recovery¶

Managed storage uses local fixed or removable drives only. UNC paths, mapped network storage, files, traversal, symlinks, and junctions are rejected. The configuration is stored as storage-locations.json beside the host identity. On every write and read, the agent removes inherited access, makes the running service identity the owner, permits only that identity and local Administrators, and verifies the protected ACL. A write or boot validation fails closed when Windows cannot prove those permissions.

The agent preserves storage-locations.json.previous as the prior known-good selection. If the newest file or a selected drive is invalid, read the effective source and error in the Swarm Host view: prior_known_good means the agent is safely using the validated previous selection; legacy_fallback means it is using the service's CLI/environment paths. Restore the local drive and restart the service before attempting another selection.

Do not display or hand-edit the JSON files, copy them between hosts, or loosen their ACLs. Check only file presence and ACL ownership from an elevated shell:

Get-Item 'C:\ProgramData\SwarmHosts\agent\storage-locations.json' | Select-Object Name,Length,LastWriteTimeUtc
(Get-Acl 'C:\ProgramData\SwarmHosts\agent\storage-locations.json') | Select-Object Owner,AreAccessRulesProtected

Changing storage is empty-host onboarding, not migration. Both the current and selected game and backup locations must contain no managed data.

Service controls¶

The installed Windows service is named SwarmHostsAgent. Use the tray app for normal status, update, and restart operations. For recovery or automation, run these actions from an elevated PowerShell session. For a default executable installation, open the installed agent folder first:

Set-Location 'C:\Program Files\SwarmHosts\Agent'
.\install_agent_windows_service.ps1 -Action Status
.\install_agent_windows_service.ps1 -Action Start
.\install_agent_windows_service.ps1 -Action Stop
.\install_agent_windows_service.ps1 -Action Restart
.\install_agent_windows_service.ps1 -Action Diagnostics

The default Swarm Server data root is:

C:\ProgramData\SwarmHosts\deployments

Do not delete the identity or data directories to fix a normal offline or Docker problem. Preserve diagnostics and backups first.

Docker Desktop¶

Before launching a game, confirm Docker is running and reports Linux containers:

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

The second command must return linux. Docker working in your interactive PowerShell session does not prove the installed Swarm Hosts service can reach the same engine. If the web app reports the runtime unavailable, run the installer diagnostics and check the service account's Docker access.

The bootstrap and service-update installers also make Docker startup durable:

• com.docker.service is set to automatic startup;
• Docker Desktop's Start Docker Desktop when you sign in setting is enabled;
• a per-user sign-in task is registered as a fallback; and
• the configured Docker Desktop user profile is retained across agent updates.

If Docker Desktop later stops while that user session is active, the agent asks the same sign-in task to launch it again and continues bounded readiness retries. During those retries, the privileged agent also reasserts automatic startup for com.docker.service and starts that backend service if Windows or Docker Desktop reset it to manual after a reboot. The Linux engine still cannot become ready until the configured Docker Desktop user has an interactive sign-in session.

For startup repair, prefer the installed service helper with existing settings. If rerunning the bootstrap installer, retain the original identity and data paths and any customized installation options.

If bind mounts fail, confirm Docker Desktop can access the configured Swarm Server data root.

Backup capture parity¶

The Windows agent does not create ZFS inside a game container and does not require an NTFS volume conversion. For games that require consistent capture, the shared Linux-container path briefly pauses the container, stages its bind-mounted data, resumes it, and only then compresses or uploads the backup. Docker Desktop filesystems that cannot clone files use a bounded staged copy. If that path is unavailable, the UI and backup record disclose the graceful restart fallback.

This is the same backup-capture contract used on Linux, adapted to Windows host paths and Docker Desktop's Linux-container engine.

Firewall and public access¶

Windows Defender Firewall and Docker port publishing must allow the assigned game ports. Use the exact TCP or UDP protocols shown by the Swarm Server.

Public UDP observation uses elevated raw IPv4 access. If that permission or a usable IPv4 interface is missing, Swarm Hosts reports the observation feature unavailable until the prerequisite is fixed.

A managed relay is offered only when the Windows agent and Docker environment report the required routing capability. If it is unavailable, use direct port forwarding or move the Swarm Server to a compatible host.

Update and rollback¶

Use the tray app or the installed service helper's Update action. The helper downloads and validates the current agent release, stops the agent service, preserves the previous binary for rollback, replaces the installed agent, and starts the service again. It reads the existing service configuration when options are omitted. -AgentPath names the installation destination; it is not a path to a downloaded update source.

Run Status and Diagnostics after updating. If the new agent fails before a game task is queued, use the installer's rollback action and preserve the diagnostic output for support.

.\install_agent_windows_service.ps1 -Action Update
.\install_agent_windows_service.ps1 -Action Status
.\install_agent_windows_service.ps1 -Action Diagnostics
.\install_agent_windows_service.ps1 -Action Rollback

Uninstall¶

A normal uninstall removes the service but preserves the Swarm Host identity and Swarm Server data. Removing identity or Swarm Server data requires separate confirmation flags and should be done only after backups and migration are complete.

.\install_agent_windows_service.ps1 -Action Uninstall

To remove the preserved host identity too, use -Action Uninstall -RemoveIdentity. Removing Swarm Server data is a separate destructive choice and requires both -RemoveData -ConfirmDataRemoval DELETE_SWARMHOSTS_DATA. Back up or migrate important worlds before using either removal option.

Troubleshooting¶

1. Run the installer Diagnostics action.
2. Confirm Docker Desktop is started and using Linux containers.
3. After a reboot, confirm the configured Docker Desktop user has signed in.
4. Open the Swarm Host page and read the current capability warning.
5. Confirm the data root exists and has free disk space.
6. Check Windows Defender Firewall for the assigned game protocols.
7. Use a redacted support report if the warning does not identify the fix.

Default Windows paths are:

• installed agent: C:\Program Files\SwarmHosts\Agent
• Swarm Server data: C:\ProgramData\SwarmHosts\deployments
• host identity: C:\ProgramData\SwarmHosts\agent\identity.json
• service logs: C:\ProgramData\SwarmHosts\logs

Do not post the full service log without reviewing it for tokens, player data, private addresses, and Swarm Server configuration.

Current limitations¶

• Docker Desktop is a Windows 10/11 path, not a Windows Server runtime.
• Windows-container mode is unsupported; the engine must run Linux containers.
• Podman is not supported by the Windows service path.
• Files, backups, monitoring, firewall, relay, and public access depend on the Windows service account and Docker integration.
• Managed relay routing requires the Linux-container runtime and routing helper reported by the host.

Private LAN replica checks¶

For a degraded Swarm Zone, copy the current private address and file-gateway port from the owner-only Swarm Host Overview page. Confirm that LAN backup replication says Ready, LAN replication capability says Reported, and copy the exact LAN backup gateway port. In an administrator PowerShell session, replace the examples and check that reported port:

$GatewayPort = 8085
Get-NetTCPConnection -State Listen -LocalPort $GatewayPort
Test-NetConnection -ComputerName 192.168.1.20 -Port $GatewayPort

Allow inbound TCP on that port only from the other zone peers' private addresses. The source and target must both report LAN backup replication as ready on a fresh heartbeat; an assigned port-range end is not a gateway-port fallback. Archives default to a 64 GiB maximum and network reads time out after 120 seconds. If NTFS or the selected paths cannot create a hard-link, the agent makes a full local copy, which requires extra disk space and write I/O. When both peers support incremental transfer, the target requests only missing backup chunks after an encrypted manifest exchange. Older peers or a failed negotiation use the encrypted full LAN archive. Zone backup data does not use the public game relay.

See Swarm Host Compatibility for the public capability matrix and Get Started for the main installation flow.