Get Started: Install a Swarm Host¶

Install the agent on the computer that will run your game servers. Swarm Hosts stays in your browser; game servers and world data stay on your hardware.

Create and verify your account¶

Create an account, then open the verification link in your email. The link signs you in. Free signup takes you directly to Profile → Agent download; if you selected Plus, you continue to Profile → Plan.

If the email has not arrived, check your spam or junk folder. On the verification screen, enter your account password and choose Resend verification email. Use the newest email because resending replaces older links. If email delivery is temporarily unavailable, your account is saved; try again later.

An expired link takes you back to sign in to request a new one. You can also choose Return to sign in on the verification screen to use a different account.

Before you start¶

You need:

• a Swarm Hosts account;
• a Linux or Windows 10/11 computer you control, with administrator access;
• outbound internet access to Swarm Hosts and the game's download services; and
• enough CPU, memory, and disk space for the game, operating system, and backups.

Open Profile → Agent download and check that the download for your platform is available and supports new host enrollment. If the page reports an update is required, wait for a supported download. Existing enrolled hosts keep their own credentials.

Choose Generate connection code on Profile → Agent download when you are ready to install. Each code connects one host and expires after 15 minutes. Paste it into the installer's hidden prompt. Account passwords, account tokens, and personal API tokens cannot enroll hosts.

Keep the code private. After successful enrollment, the agent saves a private host identity and uses that identity for future connections. Do not display, share, or delete the identity file. If registration is interrupted, keep the saved pending identity so retries use the same host. If the code expires before enrollment succeeds, generate a fresh code and rerun the installer with the same identity and data paths.

Linux and Windows offer the same management features when their required capabilities are ready. An online host can still have a blocked container runtime. See Host Compatibility for the platform and runtime requirements.

Linux installation¶

Use a Linux distribution with systemd. Run this command on the host computer:

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

The installer:

• detects the distribution and CPU architecture;
• installs prerequisites on supported apt/dnf distributions, including the tools needed for managed relay networking;
• installs Docker packages when needed and enables Docker to start at boot;
• downloads the public swarm-agent binary;
• creates and starts a root-owned swarm-agent system service;
• uses /var/swarm/deployments for game data; and
• enrolls the host using the code you enter.

The public download must be compatible with your CPU architecture. Detecting an architecture does not mean a matching agent or game image is available.

After confirmed enrollment, the installer removes the code from its root-only environment file and restarts the agent. If enrollment is still incomplete after 60 seconds, it retains the code for retries. Keep the pending identity intact and follow Linux Agent Recovery.

Optional installation settings¶

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 both port-range arguments together. Game ports are assigned from the accepted range; you do not choose individual ports at launch.

Use --no-install-docker to skip Docker/Moby package installation and Docker service setup. This flag does not remove Docker or select Podman.

Using Podman¶

Install Podman using your distribution's instructions first. The installer runs the agent as root, so check Podman in that same account:

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

Automatic runtime selection prefers ready Docker, then uses ready Podman on Linux. If both are installed and you want Podman, use a root-owned editor to add the following line to /etc/swarm-agent/swarm-agent.env:

SWARM_CONTAINER_RUNTIME=podman

Then restart the agent:

sudo systemctl restart swarm-agent

Rootless Podman is an advanced setup with additional networking, file ownership, and service limitations. It is not the root-owned installer path.

Distribution prerequisites¶

For manual prerequisite setup, provide curl, CA certificates, Python 3, ip, iptables, sysctl, and wg, plus a working container runtime. The installer requires systemd for its automatic service path. A manual agent process is an advanced alternative documented in Agent CLI Arguments.

Updating or repairing an existing installation¶

The installer can refresh the binary and generated service configuration. Before rerunning it, review active host operations and privately retain your custom settings. Use the original server, host name, identity, installation, data-root, and port-range options. The installer does not read those settings back from the existing environment file: it replaces that file and the service unit with generated content. After the rerun, reapply any custom runtime or environment settings and restart the agent. Check that the host reports the intended runtime and paths.

For a file-access warning, use the narrower repair in Linux Agent Recovery; it preserves the binary, identity, environment, and original service unit.

Windows installation¶

Windows 10/11 hosts use Docker Desktop in Linux-container mode. The SwarmHostsAgent service must be able to reach that engine. Docker working in your PowerShell session does not prove the service has the same access.

Choose Install agent in the sidebar, then Download Windows installer. Open SwarmHostsAgentSetup.exe to start the Swarm Hosts setup wizard. When prompted, generate a one-use enrollment code under Profile → Connect a host and paste it into setup. Codes expire after 15 minutes. See the Windows guide for security prompts and setup troubleshooting.

The executable installer bundles the agent, service manager, service helper, and tray app. It installs or refreshes the SwarmHostsAgent service, starts it, and adds the tray app at sign-in. The tray provides status, local update, restart, dashboard, and log access.

The installer checks Docker readiness and configures Docker's privileged service for boot startup and Docker Desktop for launch after the installation user signs in. Docker Desktop still requires a user session; an unattended host must establish that session after a reboot before the Linux engine is available. Starting the agent service alone does not start a ready game runtime.

Docker Desktop is not installed by default. Install it, complete any required WSL2 setup or reboot, start it, and select Linux containers. Windows Server and native Windows game processes are not supported public hosting paths.

Advanced PowerShell installation¶

For recovery or automation, open PowerShell as Administrator:

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

This path downloads the agent and service helper and installs or refreshes the service. -InstallNssm downloads the service manager if it is missing; the executable installer already bundles it. The advanced script does not install the tray app. Add -InstallDockerDesktop only if you want the script to attempt Docker Desktop installation; you must still complete its runtime setup.

After confirmed enrollment, the service helper clears the code from the service environment. If registration is incomplete, follow the bounded Windows service operations, tray controls, updates, and diagnostics instead of sharing raw service logs or identity files.

Verify the host¶

After installation:

1. Sign in and open Swarm hosts.
2. Confirm that your host appears and has a recent heartbeat.
3. Open the host and check container-runtime readiness and the capability warnings before launching a server.
4. Check the reported storage and network details against your intended setup.

Before creating your first server, you can select local game and backup drives under the host's Operations → Game and backup drives. Location changes require empty current and selected locations; this does not move existing worlds. See Agent CLI Arguments for storage details.

If the host is online but game hosting is blocked, resolve the displayed runtime, storage, firewall, or relay warning. On Linux, the selected runtime must work as root. On Windows, the installed service must be able to reach Docker Desktop's Linux engine and the game-data folder.

Use Linux Agent Recovery or the Windows Agent guide for local checks, updates, and recovery. Troubleshooting covers offline agents, registration errors, full disks, and port conflicts.

Next step¶

Continue to First Swarm Server.