ENABLE MANAGED CONFIG FOR MULTI-INSTANCE SERVE

This guide shows you how to enable managed config so that multiple swamp serve instances share configuration through the datastore. Config changes on one instance — creating a model, pulling an extension, updating a vault — propagate to every other instance automatically.

Prerequisites

• A shared datastore accessible by all instances (e.g., S3 or GCS)
• The datastore extension must support the configRefresh sync capability:
  • @swamp/s3-datastore >= 2026.08.27
  • @swamp/gcs-datastore >= 2026.08.27
• A running multi-instance deployment — see Run a Multi-Instance Deployment

Check your extension version:

$ swamp extension list --json | grep s3-datastore

If the version predates 2026.08.27, update the extension:

$ swamp extension pull @swamp/s3-datastore

1. Run the migration on one instance

Pick one instance and run the config migration. This copies existing config into the datastore and sets managedConfig: true in .swamp.yaml:

$ swamp datastore config migrate

Migrated   config into datastore
           models: 3, workflows: 2, vaults: 1, lockfile: yes, extensions: 4
           Set managedConfig: true in .swamp.yaml

The command is idempotent — running it again detects the migration sentinel and skips the copy:

$ swamp datastore config migrate --json

{
  "migrated": false,
  "reason": "already migrated"
}

2. Configure other instances

Each additional instance needs managedConfig: true in its .swamp.yaml. If the migration set it on the first instance's config file, copy that change to the other instances' .swamp.yaml files:

datastore:
  type: "@swamp/s3-datastore"
  managedConfig: true
  config:
    bucket: my-bucket
    region: us-east-1

The .swamp.yaml file is the one piece of configuration that is not managed in the datastore — it is the bootstrap file and must be distributed to each instance manually (via your deployment pipeline, config management tool, or container image).

3. Restart serve instances

Restart the other swamp serve instances. On startup, each instance performs an early config pull from the datastore before loading extensions, so it starts with the latest shared config:

$ swamp serve \
    --host 0.0.0.0 \
    --auth-mode token \
    --cert-file /etc/swamp/tls/cert.pem \
    --key-file /etc/swamp/tls/key.pem

No additional flags are needed — the ConfigPoller starts automatically when managedConfig: true is set.

4. Verify config propagation

Create a model on one instance and verify it appears on another:

$ swamp model create test-model --server https://instance-a:9090
$ swamp model list --server https://instance-b:9090 --json | grep test-model

The model should appear on instance B within ~30 seconds (the default ConfigPoller interval).

Clean up the test model:

$ swamp model delete test-model --server https://instance-a:9090

How config changes propagate

Once managed config is enabled, config changes flow through two mechanisms:

1. Immediate push. When an operative modifies config through a running instance (model create, extension pull, vault update), that instance pushes the change to the datastore immediately.
2. ConfigPoller. Each instance polls the datastore every 30 seconds for config changes. A commitSeq fast-path skips the full pull when no changes have occurred, keeping the polling cost minimal.

The result is that config changes propagate to all instances within ~30 seconds under normal operation.

What stays local

The following are never stored in the managed config tier:

Related

• Datastore Configuration — Managed Config — reference for the managedConfig field, configRefresh capability, and config migrate command
• swamp serve — Config management — architectural decisions behind ConfigPoller and config propagation
• Run a Multi-Instance Deployment — prerequisite guide for multi-instance HA deployments