SERVE FLAGS

Flags

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.

Health endpoint

GET /ready returns a JSON object indicating whether the server is ready to accept requests. The response includes an instanceId field — a unique identifier for this server instance, stable for the lifetime of the process:

{ "ready": true, "instanceId": "a1b2c3d4" }

The instanceId is used internally for heartbeat registration and run ownership. In a multi-instance deployment, each instance reports a distinct instanceId, which can help identify which instance is handling a request or owns a particular run.

Config file

swamp serve can read configuration from a YAML file instead of (or in addition to) CLI flags. By default, the server looks for .swamp/serve.yaml in the repository directory. Use --config <path> to specify a different location.

Resolution priority

When the same setting is provided through multiple sources, the highest-priority source wins:

1. CLI flag (explicit)
2. Environment variable
3. Config file
4. Built-in default

See Configuration Layers for background.

Loading behavior

Supported keys

The config file uses kebab-case keys matching the CLI flag names. Not all flags are available in the config file — security-sensitive flags (authentication, TLS, admin identity) are CLI-only and environment-variable-only.

Duration strings accept the same formats as the corresponding CLI flag: plain seconds (30), explicit units (2m, 5m), or 0 to disable.

List-typed keys (trusted-hosts) use YAML sequences instead of comma-separated values:

trusted-hosts:
  - host.docker.internal
  - host.minikube.internal

Flags not available in the config file

The following flags must be provided via CLI flags or environment variables. They are not recognized in the YAML config file:

--auth-mode, --admins, --cert-file, --key-file, --grants-file, --no-schedule, --allowed-collectives, --allowed-users, --oauth-provider, --oauth-client-id, --groups-field, --group-refresh-interval, --restricted-model-types, --restricted-commands

Webhook format in config files

On the CLI, webhooks use a colon-delimited string:

--webhook '<route>:<workflow>:<secret>[:<scheme>[:<header>[:<prefix>]]]'

In a config file, each webhook is a YAML object with named fields:

webhooks:
  - route: /hooks/github
    workflow: deploy-on-push
    secret: "@env=WEBHOOK_SECRET"
    scheme: github
  - route: /hooks/custom
    workflow: process-event
    secret: "@file=/run/secrets/webhook"
    scheme: generic
    header: X-Custom-Signature
    prefix: "sha256="

See Webhooks for provider schemes, signature verification, and secret indirection.

Example config file

# .swamp/serve.yaml
port: 8080
host: "0.0.0.0"
grant-reload: auto
trust-proxy: true
hot-reload: true
# detach-runs is deprecated — HA mode is auto-detected from the datastore
heartbeat-interval: "30s"
stale-ttl: "90s"
reconciliation-interval: "60s"
trusted-hosts:
  - host.docker.internal
webhooks:
  - route: /hooks/github
    workflow: deploy-on-push
    secret: "@env=WEBHOOK_SECRET"
    scheme: github

# TLS and auth remain as CLI flags or env vars
swamp serve --auth-mode token --admins 'user:abc-123' \
  --cert-file server.crt --key-file server.key

Environment variables

Authentication modes

none (default — deprecated)

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:

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. The --server flag can be omitted if SWAMP_SERVE_URL is set — the command resolves the URL the same way other remote commands do.

swamp auth server-login --server wss://swamp.example.com \
  --token 'paul-token.<secret>'

# Or, if SWAMP_SERVE_URL is already exported:
swamp auth server-login --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:

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.

Related

• Use a Config File — replace long CLI flag chains with a YAML config file
• Configuration Layers — why the four resolution sources have the precedence they do
• Hot Reload — swamp serve reload subcommand, extension bundle reload, and trust list refresh
• 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
• Load External Grants at Startup — load grants from a file outside the repository