Agent CLI Arguments¶

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

For the installed Linux system service, registration behavior, and bounded diagnostics, see Linux Agent Recovery.

Basic Usage¶

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

Primary Arguments¶

Commands¶

Default agent behavior¶

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

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.

Swarm Server Runtime¶

Swarm host Port Range¶

Both range arguments must be supplied together. They set the first enrollment proposal. An enrolled host loads its accepted range from the saved identity; changing startup arguments alone does not replace it.

To propose a correction, first review active operations, stop only the agent service, and run configure-ports using the same server, identity, and data paths as the service. For the default Linux installation:

sudo systemctl stop swarm-agent
sudo /opt/swarm-agent/swarm-agent configure-ports \
  --identity-file /var/lib/swarm-agent/identity.json \
  --data-root /var/swarm/deployments \
  --port-range-start 40000 --port-range-end 40100
sudo systemctl start swarm-agent

The command saves a proposal; the next agent start submits it. Check the host page for acceptance or rejection. An accepted range change can redeploy game servers. Use configure-ports --use-accepted with the same identity and data paths to propose using the current accepted range again. Neither form accepts an enrollment code or --force-register.

Relay Access¶

Relays are platform-operated infrastructure. A host enrollment code cannot enroll a relay.

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

Logging¶

Important Environment Variables¶

• SWARM_USER_TOKEN
• SWARM_CONTAINER_RUNTIME
• SWARM_DATA_DIR
• SWARMHOST_STORAGE_CONFIG_FILE
• SWARM_PRIMARY_BACKUP_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

Examples¶

The swarm host owner can open Swarm Host → Operations → Game and backup drives to discover local drives or mounts and browse safe directories. The control plane stores the desired selection and the agent writes its versioned managed configuration. After the agent saves a new selection, restart it so every runtime subsystem uses the boot-validated paths. The host page reports whether the selection is pending, active, using a prior-known-good setting, or blocked by validation.

The host page shows capacity for the selected local filesystems. Game and backup locations on the same filesystem share its available space.

Choose locations from the host's discovered local drives. Network shares, UNC paths, symlinks, and Windows junctions are not accepted. The agent refuses to change roots while the current or selected locations contain data; no automatic migration or adoption occurs.

Storage selection is an empty-host onboarding workflow. Finish the selection before creating the first Swarm Server or backup. Once either exists, the host page locks location changes instead of offering to move data.

For a managed backup selection, the chosen root is partitioned as primary/ for locally created backups and replicas/ for zone replicas.

Basic swarm host registration:

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

Increase log verbosity:

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

Use a custom data directory:

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

Windows PowerShell example:

.\swarm-agent.exe --name lab-host --user-token <ENROLLMENT_CODE> --data-root 'C:\ProgramData\SwarmHosts\deployments'

Configure a swarm host-specific port range:

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

Notes¶

• --user-token is required to begin first registration. Use the installer’s hidden prompt when possible to keep the code out of shell history.
• An interrupted registration uses the private pending-enrollment.json beside the identity file. Restart with that file intact to resume the same host. If an unused code expires, supply a fresh one; the host identity is preserved. Never print either identity file.
• Account tokens and personal API tokens cannot enroll hosts. Existing enrolled hosts do not need new codes.
• A rejected stored host identity is preserved for recovery; the agent never silently creates a replacement host.
• Check Profile → Agent download for current binary support. A first install requires one-use enrollment support; older source builds and unsupported Windows binaries receive an update-required error.
• Use --server only when your account belongs to a separately managed private control plane. Bare hostnames are treated as HTTPS.
• Linux and Windows expose the same user-facing feature set. Current availability still depends on the host runtime and operating-system prerequisites. See Windows Swarm Host Agent and Swarm Host Compatibility.

Swarm Zone replica networking¶

For replication, both peers must report LAN backup replication → Ready with fresh private LAN addresses. Read the source host's LAN backup gateway port from its Overview page; the end of its game-port range is not a substitute.

Allow inbound TCP to that port only from the other private addresses in the same zone. Do not expose the LAN backup endpoint publicly. The default per-archive limit is 64 GiB (SWARM_LAN_REPLICA_MAX_BYTES), and each network connect/read operation has a 120-second timeout.

When both peers support incremental transfer, they exchange an encrypted manifest and only the backup chunks missing from the target. Older peers or a failed negotiation use the encrypted full-archive LAN transfer. Zone backup data does not use the public game relay.

Backup files share local storage where hard links are available. A filesystem that cannot create hard links uses full local copies, which require additional disk space and write activity. Incremental transfer also retains compressed chunks referenced by backup manifests; leave room for both the restore archives and that chunk storage.