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
Unused image pruning enabled at 80% selected runtime storage usage When Docker or Podman storage crosses the threshold, the agent runs the matching image prune -a --force command with a cooldown
Runtime command debug logging disabled Container runtime commands are not logged individually

Owners and swarm host admins can also open a swarm host's Operations tab and queue Prune unused images. Manual prune requests run immediately instead of waiting for the automatic threshold check.

Deployment Runtime

Argument Default Purpose
--data-root SWARM_DATA_DIR, /var/swarm/deployments on Linux, or C:\ProgramData\SwarmHosts\deployments on Windows Host directory used for per-deployment persistent data
SWARM_CONTAINER_RUNTIME auto Selects docker, podman, or auto; auto prefers Docker when ready and falls back to Podman on Linux
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
SWARMHOST_IMAGE_PRUNE_ENABLED 1 Set to 0 to disable automatic unused container image pruning
SWARMHOST_IMAGE_PRUNE_THRESHOLD_PERCENT 80 Selected runtime storage usage percent that triggers unused image pruning
SWARMHOST_IMAGE_PRUNE_CHECK_INTERVAL_SECONDS 60 Minimum interval between storage-pressure checks
SWARMHOST_IMAGE_PRUNE_COOLDOWN_SECONDS 3600 Minimum interval between prune attempts while storage remains above threshold

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_CONTAINER_RUNTIME
  • SWARM_DATA_DIR
  • SWARM_REPLICA_DIR
  • SWARM_REPLICA_REHYDRATE_TIMEOUT_SECONDS
  • SWARM_REPLICA_REHYDRATE_POLL_SECONDS
  • SWARMHOST_IMAGE_PRUNE_ENABLED
  • SWARMHOST_IMAGE_PRUNE_THRESHOLD_PERCENT
  • SWARMHOST_IMAGE_PRUNE_CHECK_INTERVAL_SECONDS
  • SWARMHOST_IMAGE_PRUNE_COOLDOWN_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

Windows PowerShell example:

.\swarm-agent.exe --name lab-host --user-token <USER_TOKEN> --data-root 'C:\ProgramData\SwarmHosts\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 production swarm host platform, especially for generic UDP public-health observation.
  • Windows agents report platform_family=windows and a capability map in heartbeats. See Windows Swarm Host Agent and Agent Capability Matrix.