Skip to main content

COLLABORATE IN THE SWAMP

This guide shows you how to take a Swamp repo that works on your machine and make it work for your whole team — shared datastore, shared vaults, and a teammate who can clone and start working immediately.

Tip

Prefer a guided experience? Ask your AI agent to help you share this repo — the share skill walks through the same steps conversationally. The exact messages may differ since the skill is agent-driven, but the underlying commands are the same ones documented here.

Prerequisites

  • A Swamp repo with models and data you want to share
  • An S3 bucket (or shared filesystem path) your team can access
  • swamp auth login completed (if using a collective token, it must include datastore:* and vault:* scopes)
  • AWS credentials configured (environment variables, profile, or IAM role)

Promote your datastore

A fresh repo stores runtime data in .swamp/ — local to one machine. Move it to shared storage so everyone reads and writes the same data.

swamp datastore setup extension @swamp/s3-datastore \
    --config '{"bucket":"my-team-bucket","prefix":"swamp-data","region":"us-east-1"}'

@swamp/s3-datastore installs automatically because @swamp is a trusted collective. The command migrates existing .swamp/ data to the bucket:

INF datastore·setup Migrating data...
Datastore Setup Complete
  Type:     @swamp/s3-datastore
  Bucket:   my-team-bucket
  Prefix:   swamp-data
  Region:   us-east-1
  Files:    18 copied (324.6KB)

Verify the new backend is healthy:

swamp datastore status
Datastore Status
  Type:    @swamp/s3-datastore
  Health:  ● healthy

Teammates need these IAM permissions on the bucket: s3:HeadBucket, s3:GetObject, s3:PutObject, s3:DeleteObject, s3:ListBucket, s3:HeadObject.

See the datastore configuration reference for S3-compatible endpoint support (MinIO, DigitalOcean Spaces, Cloudflare R2).

Migrate your vaults

A local_encryption vault encrypts secrets with a machine-local key — teammates cannot decrypt them. Migrate to a cloud backend so everyone resolves secrets through the same provider.

Tip

If your secrets are personal credentials that each teammate should supply themselves (API tokens, SSH keys), you can skip the migration. The vault definition in vaults/ is git-tracked and shared, but local_encryption secret values in .swamp/secrets/ are never included in datastore sync — each teammate runs swamp vault put to store their own. See the vaults reference for details.

Preview first:

swamp vault migrate my-secrets --to-type @swamp/aws-sm \
    --config '{"region":"us-east-1"}' --dry-run
INF vault·migrate Vault "my-secrets" ("local_encryption") has 1 secret(s).
INF vault·migrate Target: "AWS Secrets Manager" ("@swamp/aws-sm")
INF vault·migrate Dry run — no changes made.

@swamp/aws-sm installs automatically on first use (same trusted collective mechanism). Run the migration:

swamp vault migrate my-secrets --to-type @swamp/aws-sm \
    --config '{"region":"us-east-1"}'

Secrets are copied to the target before the vault config is updated. If the copy fails mid-migration, the source vault is unchanged.

Verify:

swamp vault list-keys my-secrets
INF vault·list-keys Vault "my-secrets" ("@swamp/aws-sm"): 1 key(s)
INF vault·list-keys   - "api-key"
swamp doctor vaults
✓ All models with sensitive outputs have a vault configured

See the vault reference for supported providers (AWS Secrets Manager, Azure Key Vault, 1Password).

Commit and push

Three things to commit:

  1. .swamp.yaml — now contains a datastore: block pointing to S3
  2. vaults/ — vault config updated to the new provider type
  3. extensions/ — lockfile pins @swamp/s3-datastore and @swamp/aws-sm versions so teammates get exactly the same extensions

The .swamp/ directory is excluded by the managed .gitignore — runtime data and secrets never enter version control.

git add .swamp.yaml vaults/ extensions/
git commit -m "promote datastore to S3 and vault to AWS Secrets Manager"
git push

Teammate joins

A teammate clones the repo and runs any Swamp command. The @swamp extensions from the lockfile install automatically, the S3 datastore hydrates, and vault secrets resolve through AWS Secrets Manager using the teammate's own credentials.

No swamp-specific setup needed — just cloud credentials and the CLI.

swamp datastore status
Datastore Status
  Type:    @swamp/s3-datastore
  Health:  ● healthy

Set up a swamp serve instance remotely

If you run a swamp serve instance, you can configure its datastore and vaults from your local machine using --server — no SSH access required.

Install an extension on the remote server:

swamp extension pull @swamp/s3-datastore --server wss://swamp.example.com

Configure the remote datastore:

swamp datastore setup extension @swamp/s3-datastore \
    --config '{"bucket":"my-team-bucket","prefix":"swamp-data","region":"us-east-1"}' \
    --server wss://swamp.example.com

Migrate a remote vault to a cloud backend:

swamp vault migrate my-secrets --to-type @swamp/aws-sm \
    --config '{"region":"us-east-1"}' --yes \
    --server wss://swamp.example.com

--dry-run is not available with --server; --to-type is required.

If you have stored credentials with swamp auth server-login, omit --server and set SWAMP_SERVE_URL instead. Pass --token to authenticate with an inline token.

What's next

← PreviousInstall SwampNext →Models, Workflows, and Data