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
  • 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.

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

What's next

← PreviousStoring SecretsNext →Models, Workflows, and Data