S3

ClawKeep S3 / R2 Backup Skill

Encrypted backups to any S3-compatible object storage — Cloudflare R2, AWS S3, Backblaze B2, MinIO, Wasabi.

When to Use

• Backing up agent workspaces, memory files, configs to cloud object storage
• Off-site encrypted backups with S3-compatible providers
• Cloudflare R2 (zero egress fees), AWS S3, Backblaze B2, MinIO, Wasabi
• Point-in-time restore from encrypted S3 backups

Prerequisites

1. ClawKeep CLI installed (npm install -g clawkeep)
2. An S3-compatible bucket with access credentials

Quick Setup

# Set your encryption password (once — stores encrypted key material)
clawkeep backup set-password -d /path/to/workspace

# Configure S3-compatible target
clawkeep backup s3 \
  --endpoint https://your-account.r2.cloudflarestorage.com \
  --bucket my-backups \
  --access-key YOUR_ACCESS_KEY \
  --secret-key YOUR_SECRET_KEY \
  --region auto \
  --prefix clawkeep/ \
  -d /path/to/workspace

# Start auto-sync daemon (no password in env needed after set-password!)
clawkeep watch --sync --daemon -d /path/to/workspace

After set-password, the daemon runs without any password in the environment.

Full Setup Flow

1. Initialize ClawKeep

cd /path/to/workspace
clawkeep init

2. Set Encryption Password

clawkeep backup set-password -d /path/to/workspace

This stores encrypted key material locally. You won't need the password in your environment again.

3. Configure S3 Target

Provide credentials inline:

clawkeep backup s3 \
  --endpoint https://your-account.r2.cloudflarestorage.com \
  --bucket my-backups \
  --access-key YOUR_ACCESS_KEY \
  --secret-key YOUR_SECRET_KEY \
  --region auto \
  --prefix clawkeep/ \
  -d /path/to/workspace

Or use environment variables for credentials:

export CLAWKEEP_S3_ACCESS_KEY=your-access-key
export CLAWKEEP_S3_SECRET_KEY=your-secret-key

clawkeep backup s3 \
  --endpoint https://your-account.r2.cloudflarestorage.com \
  --bucket my-backups \
  --region auto \
  --prefix clawkeep/ \
  -d /path/to/workspace

The bucket only receives opaque .enc chunk files — no file names, no metadata, no structure leaked.

4. Test Connection

clawkeep backup test -d /path/to/workspace

5. Start Auto-Sync Daemon

# No CLAWKEEP_PASSWORD needed!
clawkeep watch --sync --daemon -d /path/to/workspace

# Works with PM2, systemd, or any process manager
pm2 start "clawkeep watch --sync -d /path/to/workspace" --name clawkeep-watch
pm2 save

Provider Examples

Cloudflare R2 (Recommended — zero egress fees)

clawkeep backup s3 \
  --endpoint https://<ACCOUNT_ID>.r2.cloudflarestorage.com \
  --bucket my-backups \
  --access-key <R2_ACCESS_KEY> \
  --secret-key <R2_SECRET_KEY> \
  --region auto \
  -d /path/to/workspace

AWS S3

clawkeep backup s3 \
  --endpoint https://s3.<REGION>.amazonaws.com \
  --bucket my-backups \
  --access-key <AWS_ACCESS_KEY_ID> \
  --secret-key <AWS_SECRET_ACCESS_KEY> \
  --region <REGION> \
  -d /path/to/workspace

Backblaze B2

clawkeep backup s3 \
  --endpoint https://s3.<REGION>.backblazeb2.com \
  --bucket my-backups \
  --access-key <B2_KEY_ID> \
  --secret-key <B2_APPLICATION_KEY> \
  --region <REGION> \
  -d /path/to/workspace

MinIO (Self-Hosted)

clawkeep backup s3 \
  --endpoint http://localhost:9000 \
  --bucket my-backups \
  --access-key <MINIO_ACCESS_KEY> \
  --secret-key <MINIO_SECRET_KEY> \
  --region us-east-1 \
  -d /path/to/workspace

Common Operations

Sync

# Manual sync
clawkeep backup sync -d /path/to/workspace

# Check backup status
clawkeep backup status -d /path/to/workspace

Restore from Backup

# Restore from encrypted S3 backup
clawkeep backup restore s3://my-backups/clawkeep/workspace-id/ -d /path/to/workspace

Snapshots

# Manual named snapshot
clawkeep snap -d /path/to/workspace -m "before risky changes"

# View history
clawkeep log -d /path/to/workspace

# Restore to a specific snapshot
clawkeep restore <hash> -d /path/to/workspace

# Restore to N snapshots ago
clawkeep restore HEAD~3 -d /path/to/workspace

Agent Integration

Add to your agent's startup sequence:

# One-time setup (provide S3 credentials)
clawkeep backup set-password -d /path/to/workspace
clawkeep backup s3 \
  --endpoint https://your-account.r2.cloudflarestorage.com \
  --bucket my-backups \
  --access-key $CLAWKEEP_S3_ACCESS_KEY \
  --secret-key $CLAWKEEP_S3_SECRET_KEY \
  --region auto \
  -d /path/to/workspace

# Start auto-backup daemon (no password needed!)
pm2 start "clawkeep watch --sync --interval 10000 -d /path/to/workspace" --name clawkeep-watch
pm2 save

Troubleshooting

"No encrypted key material found"

Run set-password again:

clawkeep backup set-password -d /path/to/workspace

"Access Denied" or "NoSuchBucket"

Verify your credentials and bucket name:

clawkeep backup test -d /path/to/workspace

"Endpoint not reachable"

Check the endpoint URL. Common formats:

• Cloudflare R2: https://<ACCOUNT_ID>.r2.cloudflarestorage.com
• AWS S3: https://s3.<REGION>.amazonaws.com
• MinIO: http://localhost:9000

Watch daemon not syncing

Check PM2 logs:

pm2 logs clawkeep-watch

Security Notes

• AES-256-GCM encryption — All data encrypted before upload
• Zero-knowledge bucket — Object storage only sees numbered .enc chunks
• No metadata leaked — File names, sizes, and directory structure are all encrypted
• Keyless daemon — No password in environment variables after set-password
• Credentials stored locally — S3 credentials saved in .clawkeep/config.json
• Unrecoverable — If you lose your password, your data is unrecoverable