Skip to main content
← Back to list
01Issue
FeatureShippedSwamp Club
Assigneesstack72

Relationships

#975 Docs: add worker verify, --verify-on-enroll, and env-var config to references

Opened by stack72 · 7/5/2026· Shipped 7/5/2026

Summary

Phase 2 PR2 (#969) added three features: env-var configuration for `worker connect`, `swamp worker verify`, and `--verify-on-enroll`. Three documentation pages need updates.

Changes needed

1. `content/manual/reference/remote-execution/worker-commands.md`

`swamp worker connect` section — add an env-var table after the flags table:

Variable Flag Description
`SWAMP_ORCHESTRATOR_URL` `` positional Orchestrator WebSocket URL (`ws://` or `wss://`)
`SWAMP_WORKER_TOKEN` `--token` Enrollment token in `.` format
`SWAMP_WORKER_LABELS` `--label` Comma-separated `key=value` pairs (e.g. `region=us-east,gpu=true`)
`SWAMP_WORKER_CACHE_DIR` `--cache-dir` Bundle/asset cache directory

Note that explicit flags always win when both are set. Add an example:

```bash

Container/cloud-init: connect using only environment variables

SWAMP_ORCHESTRATOR_URL=wss://orch:9090 \ SWAMP_WORKER_TOKEN=ci-pool.a3f9... \ SWAMP_WORKER_LABELS=tier=ci,region=us-east \ SWAMP_WORKER_CACHE_DIR=/var/lib/swamp-worker \ swamp worker connect ```

Update the command synopsis to show the URL as optional: `swamp worker connect [url]`

Add `swamp worker verify` section — new section between `swamp worker list` and `swamp serve`:

``` swamp worker verify [name] [--label k=v] [--server ] ```

  • No args: verify all connected workers
  • Positional name: verify one worker
  • `--label k=v`: verify workers matching the label selector

Exits non-zero when any worker fails — usable as a CI gate.

Show example output (table with WORKER, STATUS, PLATFORM, ARCH, DETAILS columns) and JSON output structure (`{ workers: [{ name, status, probeMarkerOk, queryOk, dataPlaneOk, failures }], total, passed, failed }`).

Explain what each seam tests:

  • `probeMarkerOk` — dispatch-level metadata arrives intact
  • `queryOk` — capability RPC channel (worker → orchestrator) works
  • `dataPlaneOk` — HTTP data plane write + read round-trip works

2. `content/manual/reference/swamp-serve/serve-flags.md`

Add to the flags table:

Flag Default Description
`--verify-on-enroll` (off) Run a fleet probe on each enrolling worker before it becomes schedulable. Workers that fail the probe are marked `unverified` and excluded from dispatch until they re-enroll successfully. Opt-in.

3. `content/manual/reference/remote-execution/enrollment-tokens.md`

In the Restart and reboot scenarios table, add a row for the `unverified` outcome:

Scenario Token state What happens
Worker fails `--verify-on-enroll` probe enrolled Worker is marked `unverified` — visible in `swamp worker list` but excluded from scheduling. Re-enroll or run `swamp worker verify` to retry.

Files verified as needing NO changes

  • `tutorials/remote-execution.md` — tutorial doesn't use env vars, verify, or verify-on-enroll
  • `explanation/remote-execution.md` — conceptual architecture, no flag-level detail
  • `how-to/remote-execution.md` — deployment examples could mention env vars but are still valid without them; a follow-up can add an env-var-based deployment example
  • `reference/remote-execution/security.md` — no changes needed for these features

Context

Ship alongside or shortly after #969 merges. All three features are opt-in and backward-compatible, but users who discover them need accurate reference documentation.

02Bog Flow
✓OPEN✓TRIAGED✓IN PROGRESS✓SHIPPED+ 1 MOREASSIGNED+ 4 MOREREVIEW+ 3 MOREPR_MERGED+ 1 MORENOTIFICATION_SKIPPED

Shipped

7/5/2026, 4:04:41 PM

Click a lifecycle step above to view its details.

03Sludge Pulse
stack72 assigned stack727/5/2026, 3:47:48 PM

Sign in to post a ripple.