ENROLLMENT TOKENS
Enrollment tokens are short-lived credentials that bind a worker to a Swamp
server. They are created with
swamp worker token create
and consumed when a worker first connects. Each token is single-use: once bound
to a machine, no other machine can use it.
State machine
A token moves through four states:
| State | Description |
|---|---|
| unused | Created but no worker has connected with it yet |
| enrolled | A worker has connected and bound the token to a machine identity |
| expired | The --duration lifetime has elapsed; the orchestrator rejects the token |
| revoked | Manually invalidated via swamp worker token revoke; immediate cutoff |
Valid transitions:
unused ──► enrolled ──► expired
│ │
▼ ▼
revoked revokedrevoked can be applied from unused or enrolled. Once a token reaches
expired, it cannot be revoked (it is already terminal). Both expired and
revoked are terminal states.
Machine binding
When a worker connects with an unused token for the first time, the token
binds to the worker's machine identity. The identity is read from a machine-id
file stored in the worker's --cache-dir directory.
- The bound machine can reconnect across socket interruptions, process restarts,
and machine reboots, as long as the
machine-idfile survives. - Any other machine presenting the same token is rejected. The orchestrator compares the connecting machine's identity against the identity recorded at enrollment time.
- The machine-id is client-asserted. It prevents accidental reuse from different machines but does not defend against a malicious token holder. See the Security page for the full trust model.
Warning
Always set --cache-dir to a stable path. Without --cache-dir, the
worker uses a fresh temporary directory each time it starts. This means:
- A new
machine-idis generated per process. - After a restart, the worker presents a different identity and the orchestrator rejects the connection (the token is already bound to the previous identity).
Set --cache-dir to a persistent path (e.g., /var/lib/swamp-worker) for any
worker that needs to survive restarts. See
swamp worker start --cache-dir
for details.
Expiry
Expiry is a hard deadline set at creation time via --duration. The countdown
starts when the token is created, not when the worker enrolls.
- When the lifetime elapses, the orchestrator disconnects any connected worker using that token.
- Re-enrollment with an expired token is rejected.
- To cut off a worker before the expiry time, use
swamp worker token revoke.
Restart and reboot scenarios
| Scenario | Token state | What happens |
|---|---|---|
| Socket blip (network hiccup) | enrolled | Worker reconnects automatically; same machine-id matches |
| Process restart (same machine) | enrolled | Worker re-enrolls with the same machine-id from --cache-dir; connection resumes |
| Machine reboot (same disk) | enrolled | Same as process restart — machine-id file persists across reboots |
| Token expired | expired | Orchestrator rejects connection; mint a new token |
| Token revoked | revoked | Orchestrator rejects connection immediately; mint a new token |
| Second machine (different id) | enrolled | Rejected: token is bound to the first machine's identity |