Get Started: Install A Swarm Host

This page is the quickest path for turning your own Linux or Windows machine into a Swarm Host. Swarm Hosts stays in your browser. Game servers and world data stay on your hardware.

Before You Start

You need:

  1. A Swarm Hosts account.
  2. A machine you control with outbound HTTPS access to https://swarmhosts.com.
  3. Administrator access on that machine.
  4. Your Agent token from Profile in the Swarm Hosts app.

The install scripts prompt for the token with hidden input. They do not print the token to the terminal. After first registration succeeds, the Linux script removes the token from its root-only environment file. The Windows script asks the service helper to clear the token from the service environment after the host identity file exists.

Linux is the recommended swarm host platform for production use today. The bootstrap script defaults to Docker and can install Docker packages on the supported apt/dnf families. Podman is also supported by the agent after you install it manually; set SWARM_CONTAINER_RUNTIME=podman before starting the agent when you want to force Podman instead of auto-detect. Rootless Podman should use high host ports and relay-backed access when router or NAT behavior is uncertain.

Windows agent support is in foundation status: registration, heartbeat, service startup, runtime readiness reporting, and capability reporting are implemented. The current game images are Linux containers, so Docker on Windows must be reachable from the installed service and able to run Linux containers for the broad game catalog. Docker Desktop can still require user sign-in, WSL2 setup, a reboot, or service-account access before the service can reach its Linux engine. A Windows-native vanilla Minecraft process path is available for scoped validation when Docker Desktop or WSL2 is blocked. It covers lifecycle, status, logs, backups/restores, file-manager actions, imports, and RCON/game-command paths for vanilla deployments in the current experimental slice, but does not replace Docker for other games. Some optional features, especially generic UDP reachability observation, rely on Linux capabilities.

The token is not your login password.

Use this password/token model:

  • Password: needed for web login and account management.
  • Agent token: used only to register and identify a swarm host.

Treat the token like a machine credential: do not paste it in public chat, and rotate it in Profile if it leaks.

Linux Install

Run this on the Linux host you want to register:

curl -fsSL https://swarmhosts.com/agent/install/linux.sh | sudo bash -s -- --name my-swarm-host

The script:

  • detects the Linux distribution, version, and CPU architecture;
  • installs curl, CA certificates, and Docker packages where the distribution package manager supports it;
  • downloads the public swarm-agent binary;
  • creates a root-owned systemd service;
  • stores deployment data under /var/swarm/deployments;
  • registers the host with your agent token;
  • starts the agent and prints local verification commands.

Re-run the same command to refresh the agent binary, repair the service file, or report the current Docker/service state.

Optional Linux flags:

curl -fsSL https://swarmhosts.com/agent/install/linux.sh | sudo bash -s -- \
  --name basement-pc \
  --data-root /var/swarm/deployments \
  --port-range-start 40000 \
  --port-range-end 40100

Use --no-install-docker if you already manage Docker yourself or want the script to skip package installation.

Windows Install

Open PowerShell as Administrator, then run:

Set-ExecutionPolicy -Scope Process Bypass -Force
$script = Join-Path $env:TEMP 'install-swarm-host.ps1'
Invoke-WebRequest -Uri 'https://swarmhosts.com/agent/install/windows.ps1' -OutFile $script
& $script -Name 'my-swarm-host' -InstallNssm

The script:

  • detects Windows version and CPU architecture;
  • downloads swarm-agent.exe;
  • downloads the Windows service helper;
  • checks whether Docker is installed and responding;
  • installs NSSM when -InstallNssm is supplied;
  • installs or refreshes the SwarmHostsAgent Windows service;
  • registers the host with your agent token;
  • starts the service and prints local verification commands.

Docker Desktop is not installed automatically unless you add -InstallDockerDesktop to the script arguments. Docker Desktop can require WSL2 setup, a reboot, user sign-in, and switching to Linux containers, so the default script reports the Docker blocker and leaves those steps explicit.

Example with Docker Desktop install opt-in:

Set-ExecutionPolicy -Scope Process Bypass -Force
$script = Join-Path $env:TEMP 'install-swarm-host.ps1'
Invoke-WebRequest -Uri 'https://swarmhosts.com/agent/install/windows.ps1' -OutFile $script
& $script -Name 'gaming-pc' -InstallNssm -InstallDockerDesktop

Example for the experimental vanilla Minecraft fallback when Docker Desktop cannot be reached by the Windows service:

Set-ExecutionPolicy -Scope Process Bypass -Force
$script = Join-Path $env:TEMP 'install-swarm-host.ps1'
Invoke-WebRequest -Uri 'https://swarmhosts.com/agent/install/windows.ps1' -OutFile $script
& $script -Name 'gaming-pc' -InstallNssm -EnableNativeMinecraft

Install Java 21 first, or pass -NativeMinecraftJava with the path to java.exe if it is not on PATH.

Re-run the Windows command to refresh the binary, reinstall the service wrapper, or report current Docker/service state.

For service-managed Windows hosts, use the downloaded service helper for updates, rollback, diagnostics, and uninstall:

.\install_agent_windows_service.ps1 -Action Update -Start
.\install_agent_windows_service.ps1 -Action Rollback -Start
.\install_agent_windows_service.ps1 -Action Diagnostics
.\install_agent_windows_service.ps1 -Action Uninstall

Uninstall removes the service and preserves identity/data by default.

Supported OS And Runtime Matrix

Ubuntu Or Debian With systemd

Installer behavior: installs the distro docker.io package when Docker is missing, downloads the agent, writes a systemd service, and starts it.

Runtime status: recommended production path for Minecraft and the broader Linux-container game catalog.

Fedora Or RHEL-Like Linux With systemd

Installer behavior: installs curl/CA certs and tries distro Docker/Moby packages when available. If the distro repository does not provide Docker, install Docker Engine manually and rerun.

Runtime status: supported once docker info succeeds.

Linux With Podman

Installer behavior: install Podman manually first, then run the installer with --no-install-docker and set SWARM_CONTAINER_RUNTIME=podman for the agent service when you want to force Podman instead of Docker auto-detect.

Runtime status: supported once podman info succeeds for the agent account.

Other Linux Distributions

Installer behavior: detects the OS and installs the agent/service when systemd is available. Package installation may be manual.

Runtime status: supported after you install Docker Engine or Podman and the selected runtime's info command succeeds.

Windows 10/11

Installer behavior: downloads the Windows agent, installs the NSSM-backed service, and checks Docker Desktop readiness.

Runtime status: foundation support. Use Docker Desktop in Linux-container mode for the general game catalog, and confirm the Swarm Hosts host detail page shows the service can reach that runtime. Docker working in your interactive PowerShell session does not always mean the Windows service can reach the same Linux engine.

Windows Server 2022

Installer behavior: registers and runs the foundation agent/service path when prerequisites are present.

Runtime status: Docker Desktop is not a Windows Server runtime. Use a supported Linux-container-capable runtime before expecting Docker game deployments to work.

Windows Native Minecraft Mode

Installer behavior: requires Java and the -EnableNativeMinecraft installer flag. Use -NativeMinecraftJava when java.exe is not on PATH.

Runtime status: experimental vanilla Minecraft-only fallback. It does not replace Docker for other games.

Linux is the recommended swarm host platform for production use today. Windows registration, heartbeat, service startup, runtime readiness reporting, and capability reporting are implemented, but full Windows game-hosting parity is still tracked separately. See the Windows Agent page and the Agent Capability Matrix.

The current game images are Linux containers, so Docker on Windows must be able to run Linux containers. Check Docker locally:

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

The value must be linux, and the Swarm Hosts host detail page must also show the service-side runtime as ready. If Docker is missing, times out, reports windows, cannot report its container OS, or is visible only to the interactive user and not to the service, the host can still register but deployment lifecycle capabilities will be shown as blocked.

On Windows, the agent uses a Docker CLI config directory under the agent data root by default. The installer seeds that config from the installing user's Docker context when possible. This avoids Docker Desktop credential-helper failures in non-interactive SSH or Windows Service sessions and stores registry auth there when Docker Hub or registry credentials are provided. Set SWARMHOST_DOCKER_CONFIG only if you need a different writable Docker config path for the service account.

There is also a native Windows process mode for lab validation when Docker Desktop or WSL2 is blocked. It requires Java, opt-in environment variable SWARMHOST_NATIVE_MINECRAFT_ENABLED=1, and currently supports vanilla Minecraft only. This path covers lifecycle, status checks, logs, backups/restores, import, file-manager actions, and RCON/game commands, but it remains a limited and experimental Windows Minecraft path rather than general Windows game hosting.

Verify The Host

After the installer finishes:

  1. Sign in to Swarm Hosts.
  2. Open Swarm hosts.
  3. Confirm the host appears and shows a recent heartbeat.
  4. Open the host detail page and check runtime readiness, platform capabilities, data root, public/private IPs, and gateway status.

On Linux, local checks are:

sudo systemctl status swarm-agent --no-pager
sudo journalctl -u swarm-agent -n 100 --no-pager
docker info
# or, if you selected Podman:
podman info

On Windows, local checks are:

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

If Docker is missing or blocked, the host can still register and heartbeat, but game deployments will show runtime readiness warnings until Docker is fixed.

Manual Fallbacks

If the bootstrap script cannot install prerequisites automatically:

  • Install Docker Engine on Linux, then rerun the Linux installer.
  • Install Podman on Linux, rerun the Linux installer with --no-install-docker, and set SWARM_CONTAINER_RUNTIME=podman for the agent service.
  • Install Docker Desktop on Windows 10/11, start it, switch it to Linux containers, then rerun the Windows installer.
  • Install NSSM manually or place nssm.exe in C:\SwarmHosts\agent, then rerun the Windows installer without -InstallNssm.
  • Use Troubleshooting for offline agents, bad tokens, Docker failures, full disks, and port conflicts.

Advanced flags and manual run commands are documented in Agent CLI Arguments.

Next Step

Continue to First Deployment.