Skip to main content

Exe Dev/swamp Serve Fleet

@webframp/exe-dev/swamp-serve-fleetv2026.11.05.1· Apache-2.0· 15d agoBEHAVIORSWORKFLOWSACCEPTED WARNINGS
01README

One-shot bootstrap for a swamp serve orchestrator + remote worker fleet on exe.dev, run from an operator's local workstation. Creates the orchestrator VM and workers, joins them to a tailnet, installs a pinned Deno + swamp, mints the serve/worker/dashboard tokens into a vault, enables serve and the workers as systemd user daemons, exposes serve through tailscale serve and the exe.dev HTTPS proxy, promotes the operator's local swamp data into a shared datastore, and — after an operator approval — claims the datastore for serve (team mode).

This generalizes the reference deployment documented in the webframp devsecops repo. Every site-specific value (names, admin principal, datastore, vaults, ports) is an input with a generic default. No confidential values are baked in.

Architecture (no reverse proxy)

Serve binds plain HTTP on loopback. Two native proxies terminate TLS on their own side: the exe.dev HTTPS proxy fronts the browser dashboard; tailscale serve fronts the workers. Putting a reverse proxy in the middle forces Host rewriting, Origin spoofing, CORS for the dashboard's crossorigin assets, and hand-wired WebSocket upgrades — all avoided by binding plain and letting each platform's proxy do TLS.

Prerequisites

  • An exe.dev account and an API token in a vault (the @webframp/exe-dev/vm setup method mints it).
  • A tailnet with the exe.dev catalog integration configured, and a tailnet auth key in a vault.
  • Credentials in the default chain for the chosen shared datastore (S3/GCS/...).

Phases

  1. provision_orchestrator — orchestrator VM, serve daemon, proxies, tokens.
  2. enroll_worker — worker VMs enrolled under the placement label.
  3. verify — /ready + swamp worker list.
  4. promote — local data into the shared datastore; vault migration.
  5. operator approval gate.
  6. cutover — datastore claim + restart serve (team mode).

Running

swamp extension pull @webframp/exe-dev/swamp-serve-fleet

swamp behavior create @webframp/exe-dev/swamp-serve-fleet swamp-serve-fleet
# edit the behavior and wire its global arguments:
#   adminPrincipal, datastoreConfig, tokenVault,
#   exeToken:       ${{ vault.get("exe-dev", "API_TOKEN") }}
#   tailnetAuthKey: ${{ vault.get("tailscale", "AUTH_KEY") }}

swamp workflow run @webframp/bootstrap-swamp-serve-fleet \
  --input migrate_vaults='["gitlab"]' --input vault_type=@zts/aws-ssm
# the run suspends at the approval gate; approve to cut over:
swamp workflow approve @webframp/bootstrap-swamp-serve-fleet --run <id>

See the bundled README for the full configuration shape and gotchas.

02Release Notes

Release Notes

2026.11.05.1

Initial release.

Added

  • @webframp/exe-dev/swamp-serve-fleet provisioner behavior with six methods: provision_orchestrator, enroll_worker, verify, promote, cutover, and teardown.
  • @webframp/bootstrap-swamp-serve-fleet workflow chaining the phases with a single operator approval gate before the irreversible cutover (autoResume: true).
  • Composes @webframp/exe-dev/vm (declared dependency) for VM lifecycle and drives swamp, tailscale, and exe.dev CLIs over SSH for serve/worker/token and promotion wiring.
  • Production serve flag set (plain HTTP on loopback, --trusted-hosts covering every presented name, no middle reverse proxy) assembled generically from operator inputs.
  • Secret discipline: tokens minted during provisioning, copied into the operator-named tokenVault via a reveal→vault put pipeline, and delivered to workers over SSH stdin (never argv, never worker→orchestrator SSH); resources store token names and vault keys only, never values; captured SSH/CLI output is secret-redacted before persistence.
  • Serve and worker daemons are enabled as systemd user services (daemon enable --user), matching the reference deployment's lingered user-service model.
  • verify reads the server token from its vault key, asserts it is non-empty, and treats an unparseable swamp worker list as unhealthy rather than silently reporting zero workers.
  • provision_orchestrator keeps the exe.dev HTTPS proxy private (share set-private) so the dashboard is never left publicly reachable.
  • provision_orchestrator and enroll_worker are idempotent: VM creation is skipped when a VM of that name already exists (the fleet is synced and checked first), token provisioning rotates/recreates an existing token with a fresh secret instead of failing on a duplicate name, and the remaining steps (tailscale join, installs, daemon enable, proxy wiring) are self-asserting. A re-run after a partial failure converges rather than erroring.

Security

  • adminPrincipal, tokenVault, datastoreType, magicDnsName, and clubApiKeyPath are format-constrained to reject shell metacharacters before they are interpolated into remote SSH (or local promote) commands; a runtime-resolved magicDnsName is validated before use.
  • tailnetAuthKey is format-validated (tskey-…) and delivered to tailscale up over SSH stdin into TS_AUTHKEY (sudo --preserve-env), so it never appears in argv or the remote /proc table.
  • promote and cutover build their swamp datastore/vault commands as explicit argv (no sh -c), so config blobs, vault names, and backend types are passed as individual arguments and cannot inject a command.
  • cutover tolerates an already-claimed datastore on a re-run and always records its result: if datastore claim succeeds but the serve restart fails, the resource is still written with serveRestarted: false and a restartError, so a partial cutover is recoverable rather than leaving the store claimed, serve down, and no record.
  • promote accepts migrateVaults as an array or a JSON-array string (the shape a workflow string input passes), parsing and re-validating each element against the vault-name constraint.
  • The token reveal→vault put pipelines run under set -o pipefail, so a jq parse failure fails the step instead of silently piping an empty token into vault put (which would surface later as a misleading "empty value" error in enroll_worker).
  • datastoreConfig is validated as a JSON object at the schema level, so a malformed blob is rejected early with a clear error rather than reaching swamp datastore setup.
  • teardown checks both VM-destroy runModel results (and passes modelType explicitly) instead of discarding them, so a failed destroy raises an error naming the still-running VMs rather than exiting clean while VMs keep billing.
  • The swamp install steps cap their remote output (pipefail + tail -c) so a verbose installer cannot grow the provisioner's capture buffer without bound.
  • provision_orchestrator and enroll_worker pin swamp's bundled Deno to denoVersion (deno upgrade --version) after install, so the configured version is actually honored on the fleet rather than being metadata only.
  • The secret-stdin SSH helpers arm their SIGTERM/SIGKILL timeouts before writing stdin, so a remote process that exits without reading stdin cannot hang the call on a full pipe buffer.
03Behaviors1
@webframp/exe-dev/swamp-serve-fleetv2026.11.05.1exe-dev/swamp_serve_fleet.ts
fn provision_orchestrator(cpu?: number, memory?: string, disk?: string)
Create the orchestrator VM, join it to the tailnet, install the
ArgumentTypeDescription
cpu?numberOrchestrator VM CPU count.
memory?stringOrchestrator VM memory.
disk?stringOrchestrator VM disk.
fn enroll_worker(cpu?: number, memory?: string, disk?: string)
Create and enroll `workerCount` worker VMs. Each VM joins the
ArgumentTypeDescription
cpu?numberWorker VM CPU.
memory?stringWorker VM memory.
disk?stringWorker VM disk.
fn verify()
Check orchestrator `/ready` and `swamp worker list`, recording a
fn promote()
Move the operator's local swamp data into the shared datastore
fn cutover()
Hand datastore ownership to serve (team mode): set managedConfig,
fn teardown()
Stop the serve and worker daemons and, when dryRun=false, destroy
04Workflows1
@webframp/bootstrap-swamp-serve-fleet3f2b9c7a-1d4e-4a6b-8c3f-9e2a7b5d6c10

Stand up a complete swamp serve orchestrator + worker fleet on exe.dev from the operator's local workstation, promote local data into the shared datastore, pause for an operator approval, then cut over to team mode (serve owns the datastore). The provisioner behavior `swamp-serve-fleet` (type @webframp/exe-dev/swamp-serve-fleet) must be pre-created with its global arguments wired (orchestratorName, adminPrincipal, datastoreConfig, tokenVault, exeToken, tailnetAuthKey, ...).

bootstrapCreate the orchestrator and worker VMs and enable the daemons.
1.provision-orchestratorswamp-serve-fleet.provision_orchestrator— Create the orchestrator VM, enable serve, expose it.
2.enroll-workersswamp-serve-fleet.enroll_worker— Create and enroll the worker VMs.
3.verify-fleetswamp-serve-fleet.verify— Probe /ready and `swamp worker list`.
promoteMove local data to the shared datastore and migrate vaults.
1.promote-dataswamp-serve-fleet.promote— datastore setup + vault migrate (safe, reversible).
cutoverOperator confirms, then serve claims the datastore (team mode).
1.approve-cutover— Operator confirms the running, data-promoted fleet is correct before serve claims the datastore. This is the one irreversible step.
2.claim-datastoreswamp-serve-fleet.cutover— datastore config migrate + claim + restart serve.
05Stats
A
100 / 100
Downloads
2
Archive size
31.6 KB
  • Has README or module doc2/2earned
  • README has a code example1/1earned
  • README is substantive1/1earned
  • Most symbols documented1/1earned
  • No slow types (deprecated)1/1earned
  • Dependencies pass trust audit2/2earned
  • Docs keep secrets in a vault1/1earned
  • Has description1/1earned
  • Platform support declared (or universal)2/2earned
  • License2/2earned
  • Verified public repository2/2earned

07Platforms
08Labels