@swamp/s3-datastore - Swamp Club Extension

Store data in an Amazon S3 bucket with local cache synchronization. Provides distributed locking via S3 conditional writes and bidirectional sync between a local cache directory and S3.

Authentication

Uses the default AWS credential chain — no credentials in config. Provide credentials via one of:

Environment variables: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY
AWS profile: ~/.aws/credentials
IAM role attached to the instance or task

Required IAM Permissions

s3:HeadBucket
s3:GetObject
s3:PutObject
s3:DeleteObject
s3:ListBucket
s3:HeadObject

Usage

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

S3-Compatible Endpoints

Supports S3-compatible services (MinIO, DigitalOcean Spaces, etc.) via the endpoint and forcePathStyle config options.

Field	Type	Required	Description
bucket	string	yes	S3 bucket name
prefix?	string	no	Key prefix within the bucket
region?	string	no	AWS region (defaults to environment/credentials)
endpoint?	string	no	Custom S3-compatible endpoint URL (e.g., https://nyc3.digitaloceanspaces.com)
forcePathStyle?	boolean	no	Use path-style addressing (bucket in path, not subdomain). Default: false

Field

Type

Description

bucket

string

S3 bucket name

prefix?

string

Key prefix within the bucket

region?

string

AWS region (defaults to environment/credentials)

endpoint?

string

Custom S3-compatible endpoint URL (e.g., https://nyc3.digitaloceanspaces.com)

forcePathStyle?

boolean

Use path-style addressing (bucket in path, not subdomain). Default: false

S3 Datastore

Authentication

Required IAM Permissions

Usage

S3-Compatible Endpoints

Config Fields