Agent CLI Arguments

This page documents the current Swarm Hosts swarm host agent CLI.

Basic Usage

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

Primary Arguments

Argument Default Purpose
--server https://swarmhosts.com Control plane base URL; omit for the public Swarm Hosts service
--name current hostname Friendly swarm host name shown in the UI
--user-token SWARM_USER_TOKEN Agent registration token from Profile
--identity-file ~/.swarm_agent/identity.json Cached swarm host identity file
--force-register false Ignore the cached identity and create a new swarm host

Fixed Agent Behavior

These behaviors are built into the swarm host agent and are not CLI options.

Behavior Fixed value Purpose
Heartbeat interval 15 seconds Reports host health and capacity to Swarm Hosts
Task polling interval 5 seconds Checks for deployment and host actions
Auto-update checks enabled every 600 seconds Binary builds check for newer agent releases
Image pull behavior pull when missing locally Deployment images are fetched when the host does not already have them
Docker command debug logging disabled Docker commands are not logged individually

Deployment Runtime

Argument Default Purpose
--data-root SWARM_DATA_DIR or /var/swarm/deployments Host directory used for per-deployment persistent data
SWARM_REPLICA_DIR <data-root>/.backup_replicas Host directory used for assigned replicated backup archives
SWARM_REPLICA_REHYDRATE_TIMEOUT_SECONDS 120 Max time a restore waits for a remote verified replica to rehydrate through the control plane
SWARM_REPLICA_REHYDRATE_POLL_SECONDS 2 Poll interval while waiting for remote replica rehydration

Swarm host Port Range

Argument Default Purpose
--port-range-start SWARM_HOST_PORT_RANGE_START First host port the swarm host may use for deployment mappings
--port-range-end SWARM_HOST_PORT_RANGE_END Last host port the swarm host may use for deployment mappings

Both range arguments must be supplied together.

Relay Access

Relays are platform-operated infrastructure. A profile agent token is only for swarm hosts that run game deployments.

When relay-backed access is available for your account, it is selected from the deployment workflow.

Logging

Argument Default Purpose
--log-level INFO Python logging level

Important Environment Variables

  • SWARM_USER_TOKEN
  • SWARM_DATA_DIR
  • SWARM_REPLICA_DIR
  • SWARM_REPLICA_REHYDRATE_TIMEOUT_SECONDS
  • SWARM_REPLICA_REHYDRATE_POLL_SECONDS
  • SWARM_HOST_PORT_RANGE_START
  • SWARM_HOST_PORT_RANGE_END
  • DOCKER_HUB_REPO, DOCKER_HUB_USERNAME, DOCKER_HUB_PAT, DOCKER_HUB_REGISTRY
  • REGISTRY_URL, REGISTRY_USERNAME, REGISTRY_PASSWORD
  • HARBOR_URL, HARBOR_USERNAME, HARBOR_PASSWORD

Examples

Basic swarm host registration:

./swarm-agent --name lab-host --user-token <USER_TOKEN>

Increase log verbosity:

./swarm-agent --name lab-host --user-token <USER_TOKEN> --log-level DEBUG

Use a custom data directory:

./swarm-agent --name lab-host --user-token <USER_TOKEN> --data-root /srv/swarm/deployments

Configure a swarm host-specific port range:

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

Notes

  • --user-token is required for first registration.
  • Use --server http://127.0.0.1:5000 for local development, or another URL for a private control plane. Bare hostnames such as swarmhosts.com are treated as HTTPS.
  • Linux is the recommended swarm host platform, especially for generic UDP public-health observation.