SERVE FLAGS

Flags

Duration flags that drive a timer (--heartbeat-interval, --reconciliation-interval, --group-refresh-interval, --hydration-timeout, --datastore-poll-interval, --token-gc-interval and --max-run-duration) reject values above 2147483647 ms, about 24.8 days:

Error: --token-gc-interval (30d) exceeds the maximum safe timer duration (~24.8 days)

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.

A --trusted-hosts entry is a hostname or host:port. Each entry applies to three checks:

Dashboard sign-in needs no entry when the browser origin matches the scheme and authority of the request serve receives (with --trust-proxy, the forwarded scheme and host). An entry is for a proxy that rewrites them.

When a proxy publishes the dashboard on a port other than 443, list the public address as host:port. For example, behind tailscale serve --https=9443 the browser origin is https://<public-host>:9443, and the one entry <public-host>:9443 passes both the WebSocket and dashboard sign-in checks; a bare <public-host> passes the WebSocket check but not sign-in.

Dispatch environment

Serve ships a snapshot of its environment with every step it dispatches to a worker. dispatch-env-allow limits the snapshot to the names it lists.

• Names match case-insensitively.

• The denylist always applies: HOME, PATH, SWAMP_*, DENO_*, XDG_*, OTEL_* and the other process-identity and host-runtime variables never ship.

• The flag needs a value. To ship nothing, use the config file or the empty environment variable.

• In serve.yaml, a blank entry or an entry containing a comma stops serve from starting:

  Error: Invalid dispatch-env-allow in /srv/repo/.swamp/serve.yaml: expected array of environment variable names

At startup, serve logs the scope and warns about any listed name the denylist drops:

system │ dispatch-env-allow: only these environment variables ship to workers: "DEPLOY_ENV, AWS_REGION, HOME"
system │ dispatch-env-allow lists "HOME", which never ships to workers

A name left off the list keeps the worker's own value. See Remote Execution.

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.

Auto-resume

A run that passes a manual_approval gate stays suspended until it is resumed. With --auto-resume, serve resumes the run itself when an approval made through serve decides the run's last pending gate. An approval made with a local swamp workflow approve (no --server) never triggers it.

Whether a run is resumed automatically depends on the workflow's top-level autoResume field and whether it declares inputs:

An automatic resume supplies no new inputs.

When serve resumes the run, swamp workflow approve --server prints Serve is resuming run <id> automatically and its JSON output carries autoResumed: true. A resume that is refused or fails is logged, recorded as a workflow.auto_resume_failed audit event, and leaves the run awaiting a manual resume. A started resume is recorded as workflow.auto_resume.

Datastore polling

With a remote datastore, three pollers pull changes that peer instances pushed: config (ConfigPoller), access data such as grants and groups (AccessDataPoller), and runtime data (RuntimeDataPoller). --datastore-poll-interval sets all three, and how often serve checks the managed config extension lockfile for changes. On a v2 filesystem datastore it sets how often serve checks the shared grant and group data for changes another process made; see Multiple instances. It has no effect on a v3 datastore. Serve logs a warning when the flag is set on any filesystem datastore without managed config, even though the v2 check uses it.

Token garbage collection

Serve deletes revoked and expired server tokens in every auth mode. The first sweep runs just after boot, then one runs every --token-gc-interval.

• A revoked token is deleted at the next sweep.
• An expired token is deleted once --token-gc-grace-period has passed since its expiry.
• A collected token is removed entirely: its secret, its OAuth access token, its definition and its data. It no longer appears in swamp access token list.
• Each serve replica sweeps on its own. With a remote datastore, deletions are pushed to the datastore.
• A sweep collects at most 100 tokens, counting tokens it collected and tokens it failed to collect. A larger backlog drains over later sweeps — for example, the first sweep after an upgrade on a long-running deployment, which finds every revoked or expired token ever minted. Tokens that failed in the previous sweep are tried after the others.
• Revoked and expired tokens are refused at authentication whether or not they have been collected. A backlog only keeps them in swamp access token list longer.

In serve.yaml, quote these values: token-gc-interval: "0", not token-gc-interval: 0. See Supported keys.

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.

Quote a duration that is only digits. YAML reads an unquoted 0 or 3600 as a number, and serve refuses to start:

token-gc-interval: "0"
token-gc-grace-period: "3600"

Error: Invalid token-gc-interval in /path/to/repo/.swamp/serve.yaml: expected string, got number; quote the value, e.g. "0"

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, or auth.oauth-provider. These must be set via the config file or CLI flags.

auth.oauth-client-id takes its value from --oauth-client-id, then SWAMP_OAUTH_CLIENT_ID, then the config file.

swamp serve check-config accepts --oauth-client-id and --oauth-client-secret-file, as passed to swamp serve. It reports a secret file it cannot read, a secret with no client ID, and both secret environment variables set together, as swamp serve would refuse to start. It does not report a client ID with no secret.

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

Checking restriction entries

Serve and swamp serve check-config check restricted-model-types and restricted-commands entries, from flags and the config file:

check-config does not load extension types, so it checks an entry without a leading @ against the built-in behavior types only, and warns with the reason unknown-type when the entry is not one of them. Serve checks the same entry against every registered type at startup. Write an extension type with a leading @: neither serve nor check-config checks an entry with a leading @, because an extension type can be installed after startup.

Restriction warnings:
  ! restricted-model-types entry "command/shel" is not a built-in model type — check the spelling; if it names an extension type, write it as @command/shel
  ! restricted-commands entry "extension.instal" is not a server command and restricts nothing — command names match exactly

An entry that names no type fails the check:

✗ swamp serve would refuse to start:
  Invalid restricted-model-types entry "::": it names no model type
...
Result: FAILED (swamp serve would refuse to start)

Unknown usernames

In oauth mode, serve resolves each username in admins and allowed-users on the OAuth provider and records the result in its resolved-admins cache. Startup looks up only names the cache has no record of.

• A resolved name is pinned to its account. Startup never looks it up again, including when the list is edited. To point a name at a different account, remove it, restart serve, then add it back.
• A username the provider reports as not found is skipped with an ERROR log, and stays skipped until it is removed from the list.
• Each entry must be a plain username, with an optional user: prefix. An entry that contains a colon after that prefix, such as allowed:bob, group:eng, or idp-group:eng, is skipped with an ERROR and is never looked up. Groups are not supported in admins or allowed-users with --auth-mode oauth.
• Looking up a name needs a credential that can look up users: a login token, or a collective API token with the oauth:manage scope (see Deploy with Headless OAuth). Startup needs one only when a name is added. A refused lookup (401 or 403) stops startup with an error that names the oauth:manage scope.
• Any other lookup error stops startup.
• Serve refuses to start if no admin resolves, or if every entry in allowed-users is unknown and no allowed-collectives are set.

swamp serve check-config reports unknown usernames before a deploy. An admin who cannot log in after a deploy is often listed under a username that did not resolve: search the serve log for the ERROR line that names it, correct the entry, and restart serve.

tls: block

TLS certificate paths are nested under tls:.

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

token-secrets: block

Server token secrets are stored in the _token-secrets control-plane vault, encrypted with an AES-256-GCM key. By default that key is stored in the datastore beside the secrets it encrypts, so read access to the datastore decrypts every token. The token-secrets: block keeps the key in a vault outside the datastore instead.

token-secrets:
  vault: prod-secrets
  key: swamp-token-secrets-key

• The key is 32 bytes, hex- or base64-encoded, generated by the operative with a CSPRNG, for example openssl rand -base64 32. Swamp never generates it. A key with the same value in every byte is rejected.
• The block has no CLI flag or environment variable. Serve reads it from its config file once at startup; changing it requires a restart.
• swamp access token mint, rotate and reveal, and swamp worker token create, read the block from .swamp/serve.yaml when run locally. Once serve has moved the control plane to an external key, they refuse to run without it.
• swamp serve check-config reports whether the key is usable, without printing it.
• There is no way back to a key stored in the datastore.

See Keep the token secrets key outside the datastore to enable it on an existing deployment.

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
• --oauth-client-secret-file — use SWAMP_OAUTH_CLIENT_SECRET_FILE to set it without a flag

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"
datastore-poll-interval: "30s"

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.

Token authentication failures

A connection without a token is rejected with 401 Unauthorized: token required. A presented token that fails authentication is rejected with 401 Unauthorized: <reason>, and the server logs the reason with the token name:

On a 401 or 403, the CLI reports Authentication failed — run: swamp auth server-login --server <url>. On a 5xx it reports Server error (HTTP <status>) while connecting to <url> — check the server log for the cause.

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