swamp serve has a growing list of CLI flags: --port, --host, --detach-runs, --auth-mode, --webhook, --no-schedule, --hot-reload, --cert-file, --key-file, --trust-proxy, --trusted-hosts, --admins, --allowed-collectives, --allowed-users, --verify-on-enroll, --restricted-model-types, and more. Operators running serve in production (ASG, Kubernetes, systemd) configure these via launch scripts, ExecStart lines, or container entrypoints — long, fragile command lines that are hard to review and easy to get wrong.

There's no way to version-control the serve configuration alongside the repo. Every deploy copies the same flags from a wiki page or a Terraform template. A change to the webhook secret or auth mode means updating the deployment config, not the repo.

Desired Outcome

Operators can define their serve configuration in a YAML file, commit it to the repo, and start serve with just swamp serve (or swamp serve --config path/to/config.yaml). The config file is the single source of truth for how serve runs. CLI flags override config file values when both are present.

Design

Config file location

Default: .swamp/serve.yaml in the repo root. Override with --config .

If no config file exists and no --config is specified, serve uses CLI flags only — existing behavior unchanged.

Config file format

port: 9090
host: 0.0.0.0

auth:
  mode: token
  admins:
    - "user:admin-token-name"
  allowed-collectives:
    - "engineering"
  restricted-model-types:
    - "command/shell"

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

webhooks:
  - route: /hooks/ci
    workflow: deploy-pipeline
    secret: "@env=WEBHOOK_SECRET"
  - route: /hooks/linear
    workflow: triage
    secret: "@env=LINEAR_SECRET"
    scheme: linear

schedule: true
hot-reload: false
detach-runs: true

trust-proxy: false
trusted-hosts:
  - host.[HOST-1]

default-vault: production

Resolution priority

CLI flags take precedence over config file values. This lets operators override a single value without editing the config file:

swamp serve --port 8080 # overrides config file's port: 9090

Resolution order (highest wins):

CLI flag
Config file
Default value

Webhook config format

Today webhooks are a colon-delimited string: --webhook "/hooks/ci:deploy:@env=SECRET:github"

In the config file, webhooks are structured YAML — easier to read and less error-prone:

webhooks:
  - route: /hooks/ci
    workflow: deploy-pipeline
    secret: "@env=WEBHOOK_SECRET"
    scheme: github          # optional, default: github
    header: X-Signature     # required for generic scheme
    prefix: "sha256="       # optional for generic scheme

The config file parser converts these to the same internal WebhookEndpoint objects that parseWebhookFlag produces. Both formats are supported — CLI flags use the colon string, config file uses structured YAML.

What goes in the config file vs .swamp.yaml

.swamp.yaml is the repo marker — it has the swamp version, datastore config, and namespace. These are repo-level settings that affect all commands, not just serve.

serve.yaml is serve-specific — port, auth, webhooks, TLS, scheduling. These only matter when running swamp serve.

The two files are complementary, not overlapping. serve.yaml never contains datastore or vault config.

Implementation

Define a ServeConfig Zod schema that mirrors the CLI flags
Load and parse .swamp/serve.yaml (or --config path) at serve startup
Merge config file values with CLI flags (flags win)
Pass the merged config to the existing serve setup code
Validation: report clear errors for invalid config (unknown keys, wrong types, invalid webhook format)

Error handling

Config file not found when --config is specified: hard error, refuse to start
Config file not found at default location (.swamp/serve.yaml): silently continue with CLI flags only
Config file has invalid YAML: hard error with parse error details
Config file has unknown keys: warn but continue (forward compat)
Config file has invalid values (e.g. port out of range): hard error with field-level error message

Files to modify

src/cli/commands/serve.ts — config loading, merging with CLI flags
New: src/serve/serve_config.ts — ServeConfig schema, loader, merger
New: src/serve/serve_config_test.ts — parsing, merging, validation tests

Testing

Unit test: parse valid config file with all fields
Unit test: parse config file with minimal fields (just port)
Unit test: CLI flags override config file values
Unit test: missing config file at default location is not an error
Unit test: missing config file with --config is an error
Unit test: invalid YAML produces clear error
Unit test: unknown keys produce warning
Unit test: webhook structured format parsed correctly
Unit test: webhook structured format with scheme/header/prefix
Binary test: serve starts with config file, verify port and auth mode applied
Binary test: serve with config file + CLI flag override, verify flag wins

What this does NOT include

Moving datastore/vault config into serve.yaml (stays in .swamp.yaml)
Environment variable interpolation in config values (secrets already use @env= syntax in webhook config)
Config file hot-reload (serve reads config once at startup)
Any behavior changes — this is purely a new way to provide the same configuration

Parent issue: #1448

02Bog Flow

Shipped

8/3/2026, 9:04:19 PM

Click a lifecycle step above to view its details.

03Sludge Pulse

stack72 assigned stack728/3/2026, 6:02:08 PM

Document --restricted-commands flag for swamp serve

vault put: pass tags through to extension provider CreateSecret/setSecret calls

Docs: update manual for 23 new --server commands

Update VaultProvider interface in @systeminit/swamp-testing to support optional tags in put()

Docs: document --grants-file flag for swamp serve

Docs: document --server support for serve reload

Docs: add --tag flag to vault put reference

Docs: update manual for --detach-runs deprecation and HA auto-detection

Document the Codex plugin in swamp docs

Add --server support to CLI commands missing it

Document the swamp Claude Code plugin in the swamp documentation

Make --server a global CLI option

Add --server support to model cancel (server-side run cancellation)

Load grants from external source on swamp serve startup

swamp vault put should support tags for secret governance

Improve hot reload of the deamon, include extension source/bundle changes

Authenticated users must re-login after swamp serve restart

Add --server support to serve reload

Harden queue claim semantics: atomic claims + status-guarded markDelivered/markFailed across app queues

Auto-detect HA mode and deprecate --detach-runs flag

version-drift check (from #236) is a raw string-inequality, false-positives on multi-model manifests and metadata-only bumps

Resend newsletter audience sync: contacts, segments, backfill, unsubscribe sync-back

Move per-login token secrets from vault to encrypted control-plane store

Docs: document macOS TLS trust limitation and SSL_CERT_FILE workaround

Validate swamp serve deployment stack on startup

Docs: serve config file (.swamp/serve.yaml) and --config flag

Serve config file — read swamp serve configuration from YAML

Deno runtime does not trust ISRG Root YR — extensions fail with valid Let's Encrypt certs

Docs: update hot-reload reference to include trust list refresh

Cross-instance client re-attach for multi-instance swamp serve

vercel codegen: inline rawSyncResult in non-unwrap sync path

vercel codegen: unused listAll import blocks extension publish for 4 models

vercel codegen: add round-trip idempotency test for the pipeline

Operatives button on Collectives page does nothing

Track active runs in the control-plane store for cross-instance visibility

validateGlobalArgInputRefs checks step-level inputs but step schema rejects 'inputs' key

Docs: document continuous reconciliation and multi-instance serve flags

Docs: update workflow guard skip output to include guardExpression and guardResult

Make it aware hot reload on the deamon does not take into account trust list changes, or do take into account the trust list for the hot reload.

workflow validate: new 'GlobalArgument input references' check resolves model-definition ${{ inputs.* }} against workflow inputs, false-failing steps that supply the input

Continuous reconciliation for multi-instance swamp serve

Split the score-read circuit breaker so leaderboard pressure can't blank profile scores

oauth_sign_in telemetry records provider as the literal ":id" for every event

Ghost profile bypasses the score-read seam and 500s on a slow ledger

Profile score section blocks the render on a ClickHouse read

Council: set the scoring balance — command tiers, farm-decay parameters, cross-category ratio

Scoring coverage gaps: instrument drop-off, score ripples/mentions, reward invite-converts

Push down the two cheap leaderboard scans: ghost-gate dictionary and eventCounts owner filter

Materialize an active-days-by-id table for the streak board

score-rollup-projector: O(all-time ledger) closure + per-pod fan-out saturates prod ClickHouse CPU

Startup cache hydration for swamp serve instance replacement

Output a log line for steps skipped due to guards

extension quality scorer misreads a template-literal import specifier in generated code as an unresolvable bare import, hard-erroring the whole extension as UNSCORABLE

Add @swamp/kubernetes/statefulset model type

Docs: access token commands reference says plaintext is 'shown once'

Document --restricted-model-types flag for swamp serve

swamp auth server-login ignores SWAMP_SERVE_URL

s3-datastore extension: pullChanged writes namespace-stripped paths to local cache

serve oauth: an unrecognized device-token error kills the whole serve process instead of the bootstrap

s3-datastore: bidirectional sync pull writes namespace-stripped copies to cache root, wedging push with no supported recovery

CLI reports 'HTTP/2 not supported by this client' when the server actually returned 401 — masks auth failures as a transport error

access token mint: allow reusing a revoked token name

extension quality --json exits 1 with 'rubric factors missing' even when a full score was computed (unearned factor, not uncomputable)

serve oauth: startDeviceGrant discards the OAuth error field, making device-code failures undiagnosable

access token rotate: add --vault flag to override inherited vault

Extensions without a repository can't receive issues — including the issue asking them to add one

serve oauth bootstrap: device flow rate-limited to a 45-second window by validateClient counter, shared globally across tenants

workflow edit: after saving an invalid workflow, re-running edit reports "Workflow not found"

Authentication via Google Broken

Plus-addressed emails stripped on invite acceptance, breaking collective join and quest reward

Profile edit broken on Safari

Configurable write paths for object-creating commands (repo-relative swamp root)

Docs: document rollbackOnFailure with safety guidance for external-dependency models

Remote execution tutorial: sample runner output is missing the stdout line that #1462 restored

seadex-latent-bugs: latent product bugs pinned by the wave-2b test backfill

Remote step stdout is not streamed to the workflow runner (log artifact is transferred correctly)

Redactor false positives: HH:MM:SS timestamps masked as IPs, SHA-256 digests masked as secrets (both inside code fences)

Remote execution tutorial: worker token list output and inline workflow-summary block no longer match CLI output

Add rollbackOnFailure for method-level write atomicity

docs: working-with-data tutorial uses removed depends_on step key, blocking the tutorial