Skip to main content
← Back to list
01Issue
FeatureShippedSwamp ClubPublic
Assigneesstack72

Relationships

#1867 Docs: document managedConfig for multi-instance serve deployments

Opened by stack72 · 8/27/2026· Shipped 8/28/2026

What changed

Issue #1569 (PRs #2288, #2291, #2292) added managedConfig — an opt-in feature that stores model definitions, workflow definitions, vault configs, the extension lockfile, and pulled extension sources in the datastore tier instead of top-level directories. The datastore becomes the single source of truth across serve instances.

Documentation needed

Reference: datastore-configuration.md (swamp-club/swamp-club)

  • New managedConfig field on the datastore config section of .swamp.yaml
  • The config datastore subdirectory and what lives in it
  • The configRefresh sync capability (required for S3/GCS datastores)
  • swamp datastore config migrate command — flags, JSON output shape, idempotency
  • Migration sentinel and one-time-only semantics

Reference: swamp-serve.md (swamp-club/swamp-club)

  • ConfigPoller: what it does, default 30s interval, commitSeq fast-path behavior
  • Multi-instance convergence: how instances share config through the datastore
  • Serve cold start: early config pull before extension loading
  • Serve write handlers: model/vault/extension CRUD pushes immediately

How-to guide (swamp-club/swamp-club)

  • How to enable managed config for multi-instance serve
    1. Ensure datastore extension supports configRefresh (S3 >= 2026.08.27, GCS >= 2026.08.27)
    2. Run swamp datastore config migrate on ONE instance
    3. Add managedConfig: true to other instances' .swamp.yaml (or let the migration set it)
    4. Restart serve instances — they pull config from the datastore automatically
    5. Subsequent config changes (model create, extension pull, etc.) propagate via push + ConfigPoller

What stays local

  • .swamp.yaml (bootstrap)
  • Skills (.claude/skills/ etc.)
  • Extension kind directories (extensions/models/ — user-authored extensions)
  • Bundles (derived artifacts, rebuilt from sources)

Known limitations to document

  • Last-writer-wins on concurrent config writes (config changes are infrequent and operator-initiated)
  • ~30s propagation delay between instances (configurable)
  • Migration should only run once — running on multiple instances can clobber index entries
  • .swamp.yaml distribution is manual per-instance

Automoved by swampadmin from https://github.com/swamp-club/swamp/issues/2293

02Bog Flow
OPENTRIAGEDIN PROGRESSSHIPPED+ 1 MOREASSIGNED+ 2 MOREREVIEW+ 4 MOREPR_MERGED+ 2 MORESESSION_SUMMARIZED

Shipped

8/28/2026, 7:29:14 AM

Click a lifecycle step above to view its details.

03Sludge Pulse
stack72 assigned stack728/28/2026, 12:19:05 AM

Sign in to post a ripple.