ROTATE A WORKER ENROLLMENT TOKEN

This guide shows you how to keep workers connected past their enrollment token's expiry by rotating the token before it lapses. A rotation keeps the token's name, so each worker keeps its name, labels and placement targets.

For why tokens expire and how the old and new tokens overlap, see Token lifecycle. For every flag and output field, see swamp worker token rotate.

Start workers from a token file

A worker writes a rotated token back only to the file it read its token from. Start each worker with --token-file:

swamp worker connect wss://swamp.example.com \
  --token-file /etc/swamp/worker-token \
  --cache-dir /var/lib/swamp-worker

SWAMP_WORKER_TOKEN_FILE works the same way, and so does a daemon:

swamp worker daemon enable wss://swamp.example.com \
  --token-file /etc/swamp/worker-token

The worker must be able to write the file. A worker started with --token or SWAMP_WORKER_TOKEN, or from a read-only file such as a Kubernetes Secret mount, holds a rotated token in memory only. After a restart it presents the token it started with, which stops working at the old token's deadline.

Check the deadline

swamp worker token list --server wss://swamp.example.com

The EXPIRES column is the deadline. Rotate before it.

Rotate the token

Rotate through the server, so that serve sends the new token to the connected workers:

swamp worker token rotate gpu-fleet --server wss://swamp.example.com

Add --duration 30d to give the new token a different lifetime; without it the new token gets the current one. If the server needs an access token, pass it with --token or --token-file. On this command --token-file names the server token file, not the worker's enrollment token file.

You will see output like:

✓ Token gpu-fleet rotated.
Expires: 2026-11-14T16:07:25.868Z
Old token valid until: 2026-11-13T18:06:51.686Z
Workers:
  ! gpu-fleet-f263fbc0 rotated in memory only (no token file was written; after a restart it does not have the new token)
  ✓ gpu-fleet-18845217 rotated

  gpu-fleet.debee79b46b41288d25824bb0753ee9b69d046f11527c712508f8c43a8ac1e76

The new token is shown once — store it now.
Give it to hosts that were not rotated: swamp worker connect <url> --token-file <file>

Store the new token now, in the same place you keep the worker's token. It is not printed again.

Act on the report

Old token valid until is the deadline for every host the rotation left behind. Before that time:

Report line	What to do
`✓ <worker> rotated`	Nothing. The worker wrote the new token to its file
`! <worker> rotated in memory only`	Put the new token where the worker reads it at startup: its Secret, environment variable or service unit
`✗ <worker> not rotated (its swamp version cannot take ...)`	Upgrade Swamp on the worker, then give it the new token
`✗ <worker> not rotated (<any other reason>)`	Give the worker the new token and restart it
`N enrolled machine(s) not connected — they can enroll ...`	Give those hosts the new token. This count includes workers connected to an HA peer of the serve instance you rotated through
`N enrolled machine(s) not connected still hold a token ...`	Those hosts cannot enroll until they have the new token

To give a host the new token, write it to the host's token file and restart the worker:

swamp worker connect wss://swamp.example.com \
  --token-file /etc/swamp/worker-token \
  --cache-dir /var/lib/swamp-worker

Rotate again only after every host has the current token. A second rotation retires the old token at once, and any worker still holding it is cut off.

Recover a lost token

If the rotate output was lost, or the command failed with The rotation may already have landed, do not rotate again. Read the current token back:

swamp worker token reveal gpu-fleet --server wss://swamp.example.com

The command asks for confirmation. In a script, add --yes, or --json to get the token in the token field.

← PreviousScale from Zero Workers Next →Set Up TLS for swamp serve