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
`--ws-idle-timeout <duration>`		WebSocket idle timeout — how long the server waits for a pong before closing the connection. Accepts seconds (`30`), explicit units (`2m`, `5m`), or `0` to disable
`--queue-timeout <duration>`	`10m`	How long a placed step queues for a matching worker before timing out. Accepts seconds (`60`), explicit units (`2m`, `10m`), or `0` to disable
`--verify-on-enroll`	(off)	Run a fleet probe on each enrolling worker before it becomes schedulable. Workers that fail the probe are marked `unverified` and excluded from dispatch until they re-enroll successfully
`--hot-reload`	(off)	Enable SIGHUP-based hot-reload for pulled extension bundles. Writes a PID file to `.swamp/serve.pid`; use `swamp serve reload` to trigger a reload
`--group-refresh-interval <d>`	`4h`	How often the server refreshes IdP group memberships from the OAuth provider's userinfo endpoint. Accepts duration units (`30m`, `4h`, `1d`), or `0` to disable
`--trusted-hosts <hosts>`		Comma-separated hostnames to trust for Host header validation when binding off-loopback (e.g. `host.docker.internal,host.minikube.internal`)

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. By default, Host header validation rejects requests whose Host does not match the bound address — a DNS rebinding defense. Use --trusted-hosts to whitelist additional hostnames (such as host.docker.internal) so Docker and Kubernetes workers can connect via platform-specific hostnames without disabling the protection.

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)
`SWAMP_WS_IDLE_TIMEOUT`	Default for `--ws-idle-timeout` (default: `30s`)
`SWAMP_QUEUE_TIMEOUT`	Default for `--queue-timeout` (default: `10m`)
`SWAMP_SERVE_EXTRA_HEADERS`	Extra HTTP headers sent by clients through proxies/tunnels (newline-separated `Name: value`)
`SWAMP_GROUP_REFRESH_INTERVAL`	Default for `--group-refresh-interval` (default: `4h`)
`SWAMP_TRUSTED_HOSTS`	Default for `--trusted-hosts`

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.

WebSocket token transports

The server accepts tokens on the WebSocket upgrade request via three transports:

Transport	Header / parameter	Format
Authorization header	`Authorization: Bearer <name>.<secret>`	Standard HTTP Bearer scheme
WebSocket subprotocol	`Sec-WebSocket-Protocol: bearer.<name>.<secret>`	Single subprotocol value, dot-delimited
Query parameter	`?token=<name>.<secret>`	Appended to the WebSocket URL

When multiple transports are present on the same request, the server uses the first match in this priority order: Authorization header, Sec-WebSocket-Protocol, query parameter.

The Authorization header does not expose the token in URLs. Query-string tokens appear in proxy access logs, browser history, and Referer headers. See Token transports on WebSocket for background on when each transport applies.

See Connect with a token for connection examples.

oauth

OAuth-based authentication. Users authenticate via an OAuth device flow. The server validates tokens against the OAuth provider specified by --oauth-provider. See Set Up OAuth Authentication for the setup guide.

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

See Webhooks for the full reference — provider schemes, secret sources, signature verification, and CEL context.

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 requires a custom header name and accepts an optional value prefix.

Secret indirection

The <secret> field supports indirection prefixes so signing secrets don't appear as literal values in process argv:

Prefix	Source	Example
`@env=VAR_NAME`	Environment variable `VAR_NAME`	`@env=WEBHOOK_SECRET`
`@file=/path`	File contents (trailing newline trimmed)	`@file=/run/secrets/webhook`
(plain string)	Literal value (backward compatible)	`mysecret`

swamp serve --webhook '/hooks/github:my-workflow:@env=WEBHOOK_SECRET'
swamp serve --webhook '/hooks/linear:wf:@file=/run/secrets/webhook:linear'

The server reads the resolved secret at startup. If the environment variable is unset or the file cannot be read, the server refuses to start.

Hot Reload — swamp serve reload subcommand and hot-reload behavior
Webhooks — provider schemes, secret sources, signature verification, and CEL context
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