SERVE FLAGS
Flags
| Flag | Default | Description |
|---|---|---|
--port <port> |
9090 |
Port to listen on |
--host <host> |
127.0.0.1 |
Host to bind to |
--cert-file <path> |
Path to PEM-encoded TLS certificate | |
--key-file <path> |
Path to PEM-encoded TLS private key | |
--auth-mode <mode> |
none |
Authentication mode: none (deprecated), token, or oauth |
--admins <principals> |
Comma-separated principal IDs for admin access | |
--grant-reload <mode> |
manual |
Policy snapshot reload: manual or auto |
--no-schedule |
Disable scheduled workflow execution | |
--webhook <spec> |
Register a webhook endpoint (repeatable) | |
--allowed-collectives |
Comma-separated collective slugs for OAuth admission | |
--allowed-users |
Comma-separated user identifiers for OAuth admission | |
--oauth-provider <url> |
OAuth authorization server URL | |
--oauth-client-id <id> |
OAuth client ID (required for oauth mode) |
|
--groups-field <field> |
Userinfo field name for group memberships (default: collectives) |
|
--trust-proxy |
Trust X-Forwarded-For for client IP in token auth rate limiting |
Off-loopback binding (--host set to anything other than 127.0.0.1 or ::1)
requires both TLS (--cert-file + --key-file) and authentication
(--auth-mode other than none, which is itself deprecated). The server
refuses to start without them.
Environment variables
| Variable | Description |
|---|---|
SWAMP_SERVE_URL |
Default server URL for --server on client commands |
SWAMP_SERVE_CERT_FILE |
Default for --cert-file |
SWAMP_SERVE_KEY_FILE |
Default for --key-file |
SWAMP_SERVER_TOKEN |
Server token (alternative to stored credential) |
Authentication modes
none (default — deprecated)
Warning
Deprecated. --auth-mode none will be removed in a future release. See
Set Up Token Authentication.
No authentication. Connections on loopback are accepted without credentials. Off-loopback binding is refused.
token
Token-based authentication. Users authenticate with a server token minted via
swamp access token mint. Unauthenticated connections receive HTTP 401.
oauth
OAuth-based authentication. Users authenticate via an OAuth device flow. The
server validates tokens against the OAuth provider specified by
--oauth-provider.
Credential storage
swamp auth server-login stores tokens in ~/.config/swamp/servers.json. Each
entry maps a server URL to a token. When a command uses --server, the stored
credential is used automatically.
swamp auth server-login --server wss://swamp.example.com \
--token 'paul-token.<secret>'Webhook endpoints
The --webhook flag registers an HTTP endpoint that triggers a workflow on
incoming requests:
--webhook '<route>:<workflow>:<secret>[:<scheme>[:<header>[:<prefix>]]]'Supported schemes: github (default), linear, stripe, slack, generic.
The generic scheme accepts a custom header name and optional value prefix.
Related
- Set Up TLS for swamp serve — certificate setup and reverse proxy configuration
- TLS and Proxies — client-side trust stores and server-side TLS details
- Access Commands — CLI reference for tokens, grants, and groups