#146

feat: add support for Nix via a flake

s12d ago

← Back to list

01Issue

FeatureShippedSwamp Club

Assigneesstack72

Relationships

#968 Docs: update enrollment token references for fleet tokens (--max-enrollments)

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

Summary

Phase 2 PR1 (#1753) added fleet tokens (--max-enrollments, bindings list, fleet worker naming). Follow-up #1754 refined the token list display. Three documentation pages need updates to reflect the new behavior.

Changes needed

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

Opening paragraph (lines 8-12): Replace "Each token is single-use: once bound to a machine, no other machine can use it" with language that explains the default is single-machine but `--max-enrollments` allows multiple machines to enroll on one token.

Machine binding section (lines 40-52): The statement "Any other machine presenting the same token is rejected" is only true for single-enrollment tokens. Add:

Fleet tokens (`--max-enrollments N` or `unlimited`) allow multiple machines to bind to one token
Each machine gets a distinct worker name: `-` (4-char hex hash of machine ID)
A `fleet=` label is auto-injected at enrollment
The allowance is a hard cap — once exhausted, new machines are rejected with "enrollment allowance exhausted"

Restart scenarios table (line 89): The "Second machine (different id) → Rejected" row needs a note: only applies to single-enrollment tokens (the default). For fleet tokens, a second machine appends a new binding.

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

`worker token create` section (lines 36-73):

Update the command synopsis: ``` swamp worker token create --duration [--vault ] [--max-enrollments ] ```

Add to the flags table:

Flag	Required	Description	Default
`--max-enrollments `	No	Maximum machines this token can enroll (positive integer or `"unlimited"`). Fleet tokens name workers as `-` and auto-inject a `fleet=` label.	`1`

Add a fleet example: ``` $ swamp worker token create gpu-fleet --duration 7d --max-enrollments 10 ```

`worker token list` section (lines 76-127):

Update the table output to show the hybrid display from #1754:

Single-enrollment tokens show the bound machine ID (e.g. `machine-42`) — same info as the old `BOUND MACHINE` column
Fleet tokens show `used / allowance` (e.g. `3 / 10`, `8 / unlimited`)

Update column header from `BOUND MACHINE` to `ENROLLMENTS`: ``` NAME STATE EXPIRES ENROLLMENTS ci-runner enrolled 2026-06-16T10:34:17.833Z machine-42 gpu-fleet enrolled 2026-07-05T00:00:00.000Z 3 / 10 ```

Update JSON example to show `maxEnrollments`, `bindingCount`, `bindings` instead of the old `boundMachineId` field: ```json [ { "name": "ci-runner", "state": "enrolled", "effectiveState": "enrolled", "createdAt": "2026-06-15T10:34:17.833Z", "expiresAt": "2026-06-16T10:34:17.833Z", "maxEnrollments": 1, "bindingCount": 1, "bindings": [{"machineId": "machine-42", "enrolledAt": "2026-06-15T10:34:30.000Z"}], "vaultName": "sandbox-vault", "secretKey": "worker-token-ci-runner" } ] ```

3. `content/manual/reference/remote-execution/security.md`

Line 21-22: Update "It is single-use: once bound to a machine identity, no other machine can present it" to reflect that fleet tokens allow multiple machines. Suggest: "By default, a token binds to a single machine identity. Fleet tokens (`--max-enrollments`) extend binding to multiple machines, each tracked independently."

Files verified as needing NO changes

`tutorials/remote-execution.md` — uses single token with `target:` placement; works identically
`explanation/remote-execution.md` — no single-machine token language
`how-to/remote-execution.md` — deployment examples still valid (fleet tokens are additive)
`reference/swamp-serve/serve-flags.md` — no token content

Context

Ship alongside or shortly after #1753 and #1754 merge. The behavior is backward-compatible (default `--max-enrollments 1` is identical to pre-upgrade), but users who discover fleet tokens need accurate reference documentation.

02Bog Flow

Shipped

7/4/2026, 9:46:24 PM

Click a lifecycle step above to view its details.

03Sludge Pulse

stack72 assigned stack727/4/2026, 9:23:26 PM

Scorecard: beta/rc-only extensions show "not scored" despite successful scoring (GET /score resolves only latestVersion)

`swamp extension search --channel beta|rc|stable` ignores the filter — all channels + the no-flag default return an identical result set

Beta-channel extensions are never scored — perpetual 'Scoring is taking longer than expected'

feat: allow models to call other models mid-execution via context.runModel()

swamp-club: enable OAuth provider for swamp serve collective-based admission

extension update/install reports new version while on-disk pulled files stay old

command/shell: step with timeout + a surviving child process reports exit -1 despite command exiting 0

swamp serve startup/shutdown is very slow on large repo and lacks diagnostics

Vault push log overstates what left the machine: Pushed N vault file(s) to datastore counts every dirty file, not just vault files

serve-auth: mode: oauth — device grant client + collective-based admission

serve-auth: enable OIDC Provider + Device Authorization plugins in swamp-club

Orphaned data (migrated-away/deleted model) can't be GC'd or deleted

Docs: document swamp data prune (orphaned-data reclamation)

UAT: CLI coverage for swamp data prune (orphaned-data reclamation)

Session credential revocation scans entire credential map on every dispatch completion

Docs: update worker-commands.md for --all flag and JSON output change

datastore migrate-index aborts on hardcoded 30s S3 requestTimeout for large shards

swamp worker list: hide disconnected workers by default, add --all flag

swamp serve should survive bad extension failures

Worker fleets phase 7: how-to guides and explanation docs

swamp serve: catch unhandled promise rejections from extensions

[@adam/cfgmgmt] SSH helper can crash swamp serve via unhandled finally() rejection

Docs: add --server-token flag to worker connect reference

Add --server-token to worker connect for authenticated orchestrators

Docs: document --trusted-hosts flag for swamp serve

Document SWAMP_SERVE_EXTRA_HEADERS for reverse proxy/tunnel setups

Add --trusted-hosts flag to swamp serve for Docker/Kubernetes worker connections

Allow swamp clients to send custom headers when connecting to swamp serve

Docs: update serve-flags.md default queue timeout from 60s to 10m

Worker fleets phase 6: raise default queue timeout to 10 minutes

Worker fleets phase 4b: capacity slots and concurrent dispatch

MethodContext docs/comments mention context.putSecret but runtime exposes vaultService.put

Docs: add --concurrency flag and SLOTS column to worker-commands reference

install.sh still points users to systeminit/swamp

Support user systemd units for 'swamp serve daemon enable'

swamp serve scheduled execution runs steps in an isolated data scope: readResource sees empty state, writeResource never reaches the model-scope chain — stateful scheduled workflows duplicate instead of deduplicating

Support installing swamp via mise GitHub backend

Worker fleets phase 4a: dispatch runner extraction — child process per dispatch

Docs: add swamp worker daemon enable/disable/status to worker-commands reference

Worker fleets phase 3 PR2: swamp worker daemon enable

Docs: add drain, lifecycle policies, and exit-code contract to references

Worker fleets phase 3 PR1: drain state machine, lifecycle policies, signal handling

Leaderboard search excludes ghosts — a visible ghost can't be found by its alias

issue-lifecycle: plan lifecycle entry silently dropped when summary exceeds 1000 chars

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

Labs - Filters do not apply to Blocked status and Billing Tier category

Worker fleets phase 2 PR2: env-var config, swamp worker verify, --verify-on-enroll

Docs: add --type flag to issue edit reference and how-to

Docs: update manual with whole-field expression syntax for workflow task inputs/globalArgs

Allow changing an existing issue to security/confidential after submission

Allow dynamic object expressions for workflow task inputs/globalArgs

Docs: update enrollment token references for fleet tokens (--max-enrollments)

Worker fleets phase 2 PR1: fleet tokens (--max-enrollments, bindings, worker naming)

$identify events are never consumed — anonymous web history never binds to the account

Worker fleets phase 1 PR3: boot reconciliation and integration test

Login success still shows login tip

Support confidential visibility for non-security issues

Fine-grained scopes for swamp.club access tokens

Add associative info to user profiles: collective membership + collaborative contributions

Remove comments from /feed and redesign the page

feed_post_score_events queue grows unboundedly (no TTL, no delete-on-delivery)

Make paid subscribers visually stand out (badge, profile popup summary)

Relax the profanity filter

Giphy integration via /giphy command

@-mention autocomplete for users when writing lab ripples

Worker fleets phase 1 PR2: step_queued events, pending-dispatch model, queue introspection

Docs: add swamp worker queue to worker-commands reference

/lab shipped list is sorted by issue number, not ship date

Docs: update manual for ephemeral data and step-output dependency deferral

Docs: update remote execution references for elastic queueing

Support dynamic host discovery from external sources

Worker fleets phase 1: elastic queueing

catalog backfill should support scoped population for targeted lookups

Docs: document global skill sync behavior for custom tools in manual

swamp update syncs global skills to default agent directories instead of configured custom Pi skillsDir

coerceToSuffix does not sanitize path-unsafe characters, causing forEach items and vary dimensions with / to produce invalid data instance names

Badge for activity on other people's issues

swamp serve: add @keychain=<service>/<account> indirection for secret args on macOS

swamp serve: eliminate wrapper scripts via @vault= secret refs and native startup hooks

Automate mechanical frontmatter fixes in the fixing stage