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.

Resource limits

At startup, swamp serve automatically raises the process's open-file soft limit to 8192 using setrlimit. Each connected client, worker WebSocket, and datastore handle consumes a file descriptor, so the stock macOS soft limit of 256 is too low for most server workloads.

No user action is needed on stock macOS, where the soft limit is 256 and the hard limit is unlimited — the server fixes it automatically. When the hard limit is also restricted (some container runtimes and hardened Linux hosts), raise it before starting the server:

# Shell session (applies to the current shell and its children)
ulimit -Sn 8192

# systemd unit (permanent)
# Add to the [Service] section of the unit file:
LimitNOFILE=8192

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. Most flags are available in the config file, including authentication and TLS settings via the auth: and tls: nested blocks.

Top-level keys

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

auth: block

Authentication settings are nested under auth:. In the config file, list-valued keys use YAML sequences; on the CLI the same flags accept comma-separated strings.

No environment variable exists for auth.mode, auth.admins, auth.allowed-collectives, auth.allowed-users, auth.oauth-provider, or auth.oauth-client-id. These must be set via the config file or CLI flags.

auth:
  mode: token
  admins:
    - "user:abc-123"
    - "user:def-456"
  restricted-model-types:
    - command/shell

tls: block

TLS certificate paths are nested under tls:.

tls:
  cert-file: /etc/certs/server.crt
  key-file: /etc/certs/server.key

triggers: block

Trigger overrides define or override scheduled execution for workflows. Each key is a workflow name; the value is an object with schedule (a cron expression) and/or inputs (a mapping of input values).

Trigger overrides can also be managed on a running server via swamp workflow trigger set and swamp workflow trigger remove with --server (see Hot Reload).

triggers:
  nightly-backup:
    schedule: "0 2 * * *"
  hourly-sync:
    schedule: "0 * * * *"
    inputs:
      target: production
      dry-run: false

Flags not available in the config file

The following flags are CLI-only and are not recognized in the YAML config file:

• --config — identifies the config file itself
• --repo-dir — sets the repository directory that the config file resolves relative to
• --no-schedule — use schedule: false in the config file instead

The global flags --no-telemetry and --log-level are also CLI-only.

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"

auth:
  mode: token
  admins:
    - "user:abc-123"

tls:
  cert-file: /etc/certs/server.crt
  key-file: /etc/certs/server.key

grant-reload: auto
trust-proxy: true
hot-reload: true
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

triggers:
  nightly-report:
    schedule: "0 6 * * *"

# All settings are in the config file — start with no extra flags
swamp serve

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, jira, 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'
swamp serve --webhook '/hooks/github:deploy:@vault=prod-secrets:webhook-key'

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