SWAMP SERVE

swamp serve starts a WebSocket API server that exposes your Swamp repository for remote workflow and behavior execution. The server holds the repository, clients connect over WebSocket, and workers execute steps remotely.

For a first-time walkthrough of starting a server and connecting a worker, see the Remote Execution tutorial. For TLS setup (direct certificates or reverse proxy with Caddy), see Set Up TLS for swamp serve.

In This Section

• Deploy swamp serve on Kubernetes applies raw manifests, hydrates managed config, configures TLS and secrets, and verifies Pod replacement
• Set Up Token Authentication — start the server with token auth, mint and distribute tokens, store credentials for automatic use
• Set Up OAuth Authentication — authenticate users through swamp-club with collective-based admission
• Deploy with Headless OAuth — deploy swamp serve with OAuth in unattended environments using SWAMP_API_KEY
• Keep the Token Secrets Key Outside the Datastore — move the key that encrypts server token secrets into your own vault
• Manage Access Grants — create allow and deny grants, add CEL conditions, reload the policy snapshot
• Manage Groups — create local groups, assign members, and grant access by group
• Limit Which Vaults a Run Can Use — scope the vaults serve runs can read and write with vault grants and a workflow vaults: list
• Check Your Permissions — check what you can do on a server without asking an admin
• Run Commands on a Remote Server — run behaviors, query data, and manage vaults on a remote server
• Work Offline Against swamp serve — take a behavior lease, keep working while serve is unreachable, and settle what lands on reconnect
• Real-World Scenarios — team isolation, environment separation, deny overrides, and user offboarding
• Run as a System Daemon — enable swamp serve as a system daemon on macOS or Linux, check status, and disable
• Use a Config File — replace long CLI flag chains with a .swamp/serve.yaml config file for repeatable production deployments
• Use Extra Headers with Proxies — send custom HTTP headers through reverse proxies or tunnels that require authentication