Skip to main content

WORKER COMMANDS

CLI reference for managing remote execution workers and the Swamp server. This page covers token lifecycle commands, worker enrollment, pool inspection, and the swamp serve entry point.

For enrollment token lifecycle details (machine binding, expiry, state transitions), see Enrollment Tokens. For step-level placement fields that route work to specific workers, see Workflow Placement.

Global flags

All commands in this section accept the standard global options. These are documented once here rather than repeated per command.

Flag Description
--json Emit structured JSON instead of human-readable output
--log <path> Write log output to the given file
--log-level <lvl> Set log verbosity (debug, info, warn, error)
-q Quiet mode — suppress non-essential output
-v Verbose mode — increase output detail
--no-telemetry Disable telemetry for this invocation
--show-properties Print resolved configuration properties
--no-color Disable colored output

swamp worker token create

Mint a named worker enrollment token. The plaintext is shown exactly once in <name>.<secret> format.

swamp worker token create <name> --duration <duration> [--vault <vault>]

Flags

Flag Required Description Default
--duration <duration> Yes Token lifetime (e.g. 30m, 1h, 24h, 7d). Hard deadline: the enrolled worker is disconnected when it elapses. --
--vault <vault> No Vault that stores the token plaintext Sole configured vault

Example

$ swamp worker token create ci-runner --duration 24h
Token: ci-runner
Expires: 2026-06-16T10:34:17.833Z
Vault: sandbox-vault (key worker-token-ci-runner)

  ci-runner.9ce100bf00607d0edc3f231d6f7d85d028ba820b238fda113469cf0fdf7bfa97

This token is shown once and will not be displayed again — store it now.

The token value (ci-runner.9ce100bf...) is the credential passed to swamp worker connect --token. The name prefix before the dot identifies the token; the suffix after the dot is the secret. See Enrollment Tokens for the full token lifecycle.

swamp worker token list

List worker enrollment tokens showing recorded vs effective (display) state, expiry, and bound machine.

swamp worker token list

Table output

$ swamp worker token list
NAME       STATE   EXPIRES                   BOUND MACHINE
ci-runner  unused  2026-06-16T10:34:17.833Z  -

JSON output

$ swamp worker token list --json
[
  {
    "name": "ci-runner",
    "state": "unused",
    "effectiveState": "unused",
    "createdAt": "2026-06-15T10:34:17.833Z",
    "expiresAt": "2026-06-16T10:34:17.833Z",
    "vaultName": "sandbox-vault",
    "secretKey": "worker-token-ci-runner"
  }
]

JSON fields

Field Type Description
name string Token name as provided at creation
state string Recorded state (unused, enrolled, revoked)
effectiveState string Display state accounting for expiry (may differ from state)
createdAt string ISO 8601 creation timestamp
expiresAt string ISO 8601 expiry timestamp
vaultName string Vault storing the token plaintext
secretKey string Key under which the token is stored in the vault

swamp worker token revoke

Invalidate a worker enrollment token before it expires.

swamp worker token revoke <name>

Example

$ swamp worker token revoke ci-runner
✓ Token ci-runner revoked.
Revoked at: 2026-06-15T10:34:39.736Z

After revocation, swamp worker token list reflects the updated state:

NAME       STATE    EXPIRES                   BOUND MACHINE
ci-runner  revoked  2026-06-16T10:34:17.833Z  -

swamp worker connect

Connect this machine to an orchestrator as a remote execution worker.

swamp worker connect <url> --token <token> [--label k=v ...] [--cache-dir <dir>] [--data-plane-url <url>] [--no-reconnect]

Flags

Flag Required Description Default
--token <token> Yes Enrollment token in <name>.<secret> format --
--label <label> No Scheduling label key=value (repeatable) --
--data-plane-url <url> No Override the data-plane base URL Connect URL over HTTP
--cache-dir <dir> No Bundle/asset cache directory; also stores the machine-id file the token binds to Fresh temp dir (new identity per process)
--no-reconnect No Exit when the control socket closes instead of reconnecting Reconnect on disconnect

Cache directory

Set --cache-dir to a stable directory so the worker can re-enroll after a restart. Without it, the worker receives a fresh temp directory (and therefore a new machine identity) on every process start. A stable cache directory preserves the machine-id file that the enrollment token binds to, allowing the worker to resume its identity across restarts.

Example

$ swamp worker connect wss://orchestrator.example.com \
    --token ci-runner.9ce100bf00607d0edc3f231d6f7d85d028ba820b238fda113469cf0fdf7bfa97 \
    --label env=ci --label arch=arm64 \
    --cache-dir /var/lib/swamp-worker

swamp worker list

List workers in the pool showing status, labels, platform, and last seen.

swamp worker list

When the pool is empty:

$ swamp worker list
No workers found.
Workers appear here after enrolling with: swamp worker token create <name> --duration 24h

swamp serve

Start a WebSocket API server for workflow and model execution. Workers connect to this server.

swamp serve [--port <port>] [--host <host>] [--no-schedule] [--webhook <spec>] [--repo-dir <dir>]

Flags

Flag Required Description Default
--port <port> No Port to listen on 9090
--host <host> No Host to bind to 127.0.0.1
--no-schedule No Disable scheduled workflow execution Schedules enabled
--webhook <spec> No Register a webhook endpoint: <route>:<workflow>:<secret> --
--repo-dir <dir> No Repository directory .

Service deployments

Swamp loads all extensions through an embedded runtime under ~/.swamp. When running under a service manager (e.g. systemd), ensure HOME is set in the unit environment so the runtime can locate its extension store.

Example

$ swamp serve --port 8080 --host 0.0.0.0 --webhook /deploy:ci-deploy:s3cr3t
← PreviousRemote ExecutionNext →Enrollment Tokens