Installation

This guide covers the supported way to register a swarm host with Swarm Hosts.

What You Need

  • A Linux host you control
  • Docker installed and running on that host
  • Network access from that host to the Swarm Hosts control plane
  • A Swarm Hosts account so you can copy your agent token from Profile

Linux is the recommended swarm host platform. Some optional features, especially generic UDP reachability observation, rely on Linux capabilities.

Placeholders Used Below

  • <HOST_NAME>: a friendly label for the swarm host
  • <USER_TOKEN>: your agent registration token from Profile

The agent registers with https://swarmhosts.com by default. Use --server only when connecting to a local development control plane or a private Swarm Hosts deployment.

Option 1: Download The Compiled Agent

If the control plane already has a built agent binary, the easiest path is:

  1. Sign in to Swarm Hosts.
  2. Open Profile -> Agent download.
  3. Copy the binary to the swarm host.

You can also download it directly from:

https://swarmhosts.com/agent/download

Then make it executable:

chmod +x swarm-agent

Option 2: Run The Agent From Source

For development environments, you can run the Python agent directly:

python agents/swarmhost-agent/agent/agent.py --name <HOST_NAME> --user-token <USER_TOKEN>

If you need a compiled binary but one has not been built yet, create it from the repo with:

./scripts/release/build_agent.sh

Start The Agent

Basic example:

./swarm-agent --name <HOST_NAME> --user-token <USER_TOKEN>

Useful optional flags:

  • --data-root /var/swarm/deployments
  • --force-register
  • --port-range-start 40000 --port-range-end 40100

The agent always sends heartbeats, polls for tasks, checks for binary updates, and pulls deployment images when they are missing locally. Those behaviors are fixed and are not exposed as agent CLI flags.

On first start the agent:

  • registers the swarm host to your account
  • stores its identity at ~/.swarm_agent/identity.json
  • begins heartbeats and task polling
  • starts the swarm host file gateway

Verify The Swarm host

  1. Sign in to Swarm Hosts.
  2. Open Swarm hosts.
  3. Confirm the swarm host appears and sends heartbeats.
  4. Open the swarm host detail page to check:
  5. public and private IPs
  6. port range
  7. overcommit status
  8. gateway status
  9. DNS status, if configured

Re-Register A Host

If the host was previously registered and you want it to create a new swarm host identity:

./swarm-agent --name <HOST_NAME> --user-token <USER_TOKEN> --force-register

or delete the cached identity file:

rm -f ~/.swarm_agent/identity.json

Run As A systemd Service

Example service:

[Unit]
Description=Swarm Hosts agent
After=network.target docker.service

[Service]
Type=simple
WorkingDirectory=/opt/swarm-agent
ExecStart=/opt/swarm-agent/swarm-agent --name <HOST_NAME> --user-token <USER_TOKEN> --data-root /var/swarm/deployments
AmbientCapabilities=CAP_NET_RAW CAP_CHOWN
CapabilityBoundingSet=CAP_NET_RAW CAP_CHOWN
Restart=always
RestartSec=3

[Install]
WantedBy=multi-user.target

Then enable it:

sudo systemctl daemon-reload
sudo systemctl enable --now swarm-agent
sudo systemctl status swarm-agent --no-pager

Notes For Home Networks

If you run multiple swarm hosts behind the same public IP, give each swarm host its own non-overlapping port range:

./swarm-agent --name host-a --user-token <USER_TOKEN> --port-range-start 40000 --port-range-end 40100
./swarm-agent --name host-b --user-token <USER_TOKEN> --port-range-start 40101 --port-range-end 40200

Swarm Hosts rejects overlapping ranges for swarm hosts on the same account and public IP.

Next Step

Continue to First Deployment.