Swarm Hosts User Guide

This guide explains what a user can do in the current Swarm Hosts product and how the main screens fit together.

Before You Start

  • The control plane is running.
  • You have a Swarm Hosts account.
  • At least one swarm host agent is running on a Linux host you control.
  • Docker is available on that swarm host.

If you still need to set up a swarm host, start with Installation.

Product Model

Swarm Hosts has three main pieces:

  • Control plane: the web UI and API where you sign in, view swarm hosts, and manage deployments
  • Swarm host: a Linux machine you control that runs the Swarm Hosts agent
  • Deployment: one game server instance running on a swarm host through Docker

Today, Swarm Hosts is best understood as a control plane for your own fleet of swarm host machines. It is not yet a public marketplace that automatically rents out third-party capacity.

  • Launch: choose a game, a swarm host, and the deployment settings
  • Swarm hosts: all swarm hosts you can access
  • Deployments: all deployments you can access
  • Audit log: security-relevant account and admin events
  • Profile: your account settings, agent token, API tokens, agent download, password change form, and sharing access center
  • Admin users: admin-only account management and diagnostics

Register A Swarm host

  1. Open Profile and copy your agent token.
  2. Start the swarm host agent with --user-token on the machine you want to register.
  3. Wait for the swarm host to appear in Swarm hosts.
  4. Open the swarm host detail page to confirm:
  5. last heartbeat
  6. agent version status
  7. public and private IPs
  8. swarm host port range
  9. whether overcommit is enabled
  10. gateway reachability
  11. DNS status, if DNS sync is enabled

Note

The agent registers the swarm host automatically. There is no separate swarm host creation form in the UI.

Launch A Game Server

  1. Open Launch.
  2. Pick a supported game.
  3. Choose the target swarm host.
  4. Set a server name.
  5. Set CPU and memory limits.
  6. Fill in any game-specific configuration fields.
  7. If the game offers multiple image versions, pick the version you want.
  8. Click Launch.

Swarm Hosts then:

  • validates swarm host access
  • checks the swarm host still has enough free CPU and RAM, unless overcommit is enabled on that swarm host
  • assigns host ports automatically from that swarm host's allowed port range
  • writes assigned host ports back into environment variables for games that need them
  • queues a deployment task for the swarm host agent

You can launch more than one server from the same account when your selected swarm host or Swarm Zone has enough remaining CPU, memory, and free ports.

Track Deployment Status

Open Deployments or a specific deployment detail page to watch progress.

Common statuses:

  • pending_deploy: the task is queued
  • dispatched: the swarm host agent has picked it up
  • running: the container is up and any readiness check passed
  • stopped: the container exists but is not running
  • error: deployment failed or hit a runtime problem
  • pending_start, pending_stop, pending_delete, pending_update: an action is in progress

The deployment detail page shows:

  • host port mappings
  • swarm host public and private IPs
  • public reachability badge
  • current resource limits
  • container ID when one exists
  • version management, mod-file guidance, and backup management sections
  • links to logs, resource monitor, and file manager

Manage A Deployment

From the deployment detail page you can:

  • Start a stopped container
  • Stop a running container
  • Restart a deployment with an existing container
  • Update resource limits when the deployment is running or stopped
  • Change the game version with an optional safety backup first
  • Manage mods through the file manager
  • Create, schedule, restore, download, and delete backups
  • Requeue a stuck task
  • Delete a deployment
  • Force delete if normal cleanup is stuck

The swarm host agent receives these actions through the control plane task queue and executes the matching Docker operations on the swarm host.

Connect Players

Share the swarm host public IP plus the assigned host port shown in the deployment view.

Example:

<SWARM_HOST_PUBLIC_IP>:<HOST_PORT>

Protocol matters:

  • some games use TCP
  • some use UDP
  • some use both
  • some reserve related ports together, such as Valheim and Rust

Use the game-specific docs to confirm the expected protocol and any special connection notes.

File Manager

Every deployment has a File manager view for its persistent data directory.

Current capabilities:

  • browse files and directories
  • upload files or folders
  • create folders
  • create empty files
  • read and edit text files
  • rename or move files
  • delete files
  • request bundled downloads

The file manager prefers a direct browser-to-swarm host connection through the swarm host gateway. When that path is unavailable, the UI can fall back to the older WebRTC transfer flow if the swarm host supports it.

Resource Monitor And Logs

When a deployment or swarm host has live stats available, you can open Resource monitor to view CPU and memory history. The UI uses WebRTC-backed stats sessions for live updates when available.

Use Logs on a deployment to inspect recent runtime output and troubleshoot startup failures.

Versions, Mod Files, Backups, And Migration

The deployment detail page now groups higher-risk lifecycle actions into dedicated sections:

  • Version Management: switch to a managed Docker Hub game image tag and optionally create a backup before the redeploy
  • Mod Files: use the file manager to upload, edit, or remove mods directly in the deployment data directory
  • Backups: create manual backups, configure schedules, restore in place, or restore as a new deployment on another swarm host

Migration between swarm hosts is handled through the backup workflow. Create a backup on the source deployment, then restore that backup as a new deployment on the destination swarm host.

What The Version Selector Means

When a game shows a version selector in Launch or Version Management, those choices are managed image tags that Swarm Hosts already knows about.

Important behavior:

  • you choose a named game version tag, not a raw container image
  • Swarm Hosts no longer accepts custom image overrides in the UI
  • latest is not treated as a real game version because it is mutable and does not tell you what build is actually running
  • the selected image version is stored with the deployment, and the swarm host agent reports the running game server version after startup when that version can be detected from the container

If You Do Not See Version Options

Some games may not show multiple version choices yet.

That usually means one of these is true:

  • only one managed version is currently available for that game
  • managed version tags have not been imported for that game yet

If managed tags are not available yet, the deployment can still use the platform's current game image, but the deployment detail page may show Untracked catalog image instead of a specific game version label.

Existing Deployments

Older deployments may not always have a clean managed version label yet.

You may see one of these states:

  • a specific managed version tag if the deployment already matches a known version
  • Untracked catalog image if the deployment is still using an older image reference that has not been matched to a managed version tag

This does not mean the deployment is broken. It only means the UI cannot confidently name the exact managed version yet.

Changing Versions Safely

From Version Management on the deployment detail page you can:

  • move to another managed game image tag
  • create a safety backup first
  • change any supported runtime version field for games that expose one, such as Minecraft's VERSION

Recommended workflow:

  1. Create the safety backup.
  2. Queue the version change.
  3. Wait for the deployment to come back up.
  4. Check Logs and connect once to confirm the upgrade worked.
  5. Keep the validation backup until you are confident the server is healthy.

Backups And Restore

From the deployment detail page you can create manual backups, configure scheduled backups, download backup archives, inspect backup events, restore a backup in place, or restore a backup as a new deployment.

Use Restore here when you want to roll the current deployment back to a saved state. Use Restore as deployment when you want a separate copy, a migration to another swarm host, or a safer upgrade validation path.

Scheduled backups run automatically from the control plane when the deployment supports backups. Each schedule has an interval, retention count, next run time, and last run result.

Mod Files

Swarm Hosts treats mod files as normal deployment files. Open File manager, upload or edit the files the game expects, then restart the deployment if the game only loads mods at startup. Create a backup before large modpack changes so rollback stays simple.

Deployment Ownership Transfer

Deployment owners can fully hand a deployment off to another registered user from the deployment detail page.

To transfer a deployment:

  1. open the deployment detail page
  2. find Transfer Ownership
  3. enter the new owner's email
  4. enter the destination swarm host ID
  5. optionally choose a new restored server name
  6. submit the transfer

Swarm Hosts validates that the recipient can already administer the destination swarm host, creates a backup, restores that backup as a new deployment for the recipient, and queues cleanup of the original source deployment. Swarm host ownership cannot be transferred.

Swarm host Agent Status And Updates

Swarm host pages now show whether the swarm host agent is:

  • up to date
  • outdated
  • unknown
  • manual update required

If the swarm host supports self-update, swarm host admins can use Force update agent from the swarm host detail page. Source installs do not support self-update and must be updated manually on the host.

Swarm host Overcommit

Swarm host admins can enable Allow over commit from the swarm host detail page.

When overcommit is enabled:

  • launch and update-limit workflows stop enforcing the swarm host's reported CPU and RAM capacity
  • per-game minimum resource requirements still apply
  • host-port availability is still enforced

Use this only when you intentionally want to oversubscribe a host and you understand the performance risk.

Public Reachability And DNS

Swarm host and deployment pages include internet-facing reachability badges when the public probe worker is configured.

  • Deployment pages show Public Access
  • Swarm host pages show Gateway reachability
  • A help link points to the Port Forwarding Basics guide when a check fails or cannot be verified

If DNS sync is configured, swarm host pages also show:

  • generated hostname
  • DNS status
  • last successful DNS update
  • DNS error details when sync fails

Sharing

Owners can share swarm hosts or deployments with other registered users.

How it works:

  1. Open a swarm host or deployment.
  2. Click Manage sharing.
  3. Search for another registered user by email.
  4. Choose a role.
  5. Click Share.

Rules:

  • up to 20 shared users per swarm host
  • up to 20 shared users per deployment
  • sharing supports view and admin roles
  • swarm host and deployment owners keep full control
  • deployment view access is read-only
  • deployment admin access allows operational changes
  • swarm host admin access allows swarm host-level operations such as force update
  • only the owner can change sharing

Account Management

From Profile you can:

  • copy the agent token used for swarm host registration
  • rotate that token
  • create and delete personal API tokens for automation
  • change your password
  • review swarm hosts and deployments shared with you
  • review swarm hosts and deployments you have shared with others

Personal API tokens can authenticate JSON API requests with Authorization: Bearer <token>, X-User-Token, or X-API-Token. See API Access for endpoint groups and examples.

From the login and reset flow you can:

  • register a new account
  • request a password reset link
  • open the reset link and set a new password

Authentication lifecycle events are recorded in Audit log.

Admin Features

Admins can open Admin users to:

  • search users by email
  • disable and enable accounts
  • rotate a user's agent token
  • run bulk disable and bulk enable actions
  • view runtime diagnostics and catalog diagnostics

Admin actions are guarded with one-time confirmation tokens for high-impact operations and are recorded in the audit log.