SWAMP SERVE
swamp serve starts a WebSocket API server for remote workflow and behavior
execution. Clients connect over WebSocket, authenticate with tokens or OAuth,
and execute commands against the server's repository.
Core Concepts
| Concept | Role |
|---|---|
| Server | swamp serve instance exposing a WebSocket API |
| Token | Named credential that binds a principal identity to the server |
| Grant | Authorization rule: subject + effect (allow/deny) + actions + resource |
| Group | Named collection of principals for batch grant assignment |
| Policy snapshot | Compiled set of active grants and groups, rebuilt on reload |
| Principal | Identity a token authenticates as: user:<id> or worker:<id> |
| Subject | Who a grant applies to: user:<id>, group:<name>, idp-group:<name>; grant files in oauth mode also accept username:<name> |
In This Section
- Access Commands — CLI
reference for
swamp accesssubcommands: tokens, grants, groups, checks - Authorization — the grant model: subjects, effects, actions, resource selectors, CEL conditions, deny-wins
- Serve Flags —
swamp serveflags, config file format, environment variables, and credential storage - REST API — HTTP endpoints for cancelling running executions
- Dashboard — the opt-in web
dashboard at
/dashboard - Daemon Management —
swamp serve daemon enable,disable, andstatussubcommands for running as a system daemon - Hot Reload — reloading extensions and grants without restart
- Enable Managed Config — how-to guide for sharing config across instances via the datastore
swamp serve records a telemetry event for each workflow run and behavior
method run it executes, with triggerSource and initiatedBy set. See
Usage Telemetry Events for the
fields, the 60-second flush, and how to turn it off.