Backup & Restore

Chatto provides built-in CLI commands for backing up and restoring all instance data. Backups capture the full state of your NATS JetStream storage — users, spaces, rooms, messages, memberships, assets, and more — into a single .tar.gz archive. Backups can optionally be encrypted with a passphrase using age encryption.

What’s included

Backups contain all persistent JetStream streams, KV buckets, and object stores:

• Instance data — users, spaces, memberships, roles, permissions, notifications
• Per-space data — rooms, messages, threads, reactions, message bodies
• Assets — user avatars, space icons, message attachments

What’s excluded

Certain streams are intentionally excluded:

Stream	Reason
Encryption keys	Security: keeps backup data encrypted at rest. Back up keys separately.
User presence	Ephemeral (memory-only), reconstructed at runtime
Call state	Ephemeral (memory-only), reconstructed by LiveKit webhooks
Link preview cache	Regeneratable on demand
Asset cache	Regeneratable (resized image variants)
Auth tokens	Security: prevents session token leakage via backup files

Caution

Encryption keys are excluded from backups by design. Chatto always encrypts message bodies, so the encrypted content in the backup cannot be decrypted without the keys. See Encryption key backup below.

Creating a backup

Run chatto backup while your Chatto instance is running. The command connects to NATS via the client configuration in chatto.toml.

# Default: saves to backups/<timestamp>.tar.gz
chatto backup -c chatto.toml

# Custom output path
chatto backup -c chatto.toml -o /mnt/backups/chatto-daily.tar.gz

Encrypted backups

Use --encrypt to protect the backup archive with a passphrase. You’ll be prompted to enter and confirm the passphrase:

chatto backup -c chatto.toml --encrypt

Encrypted backups use .tar.gz.age as the file extension. The encryption format is age — a modern, audited file encryption tool. This means you can also inspect or decrypt your backups using the standalone age CLI if needed (see Using the age CLI below).

For scripted or automated backups, pass the passphrase via flag or pipe it from stdin:

chatto backup -c chatto.toml --encrypt --passphrase "$BACKUP_PASSPHRASE"

# Or pipe from a secrets manager
vault kv get -field=passphrase secret/chatto | chatto backup -c chatto.toml --encrypt

Restoring a backup

Caution

Make sure Chatto is not running before restoring. For embedded NATS setups, the restore command starts its own temporary NATS server. For external NATS, stop the Chatto application but keep NATS running.

1. Stop the Chatto server

   Ensure no other process is accessing the NATS data directory.

2. Run the restore command

   chatto restore backup.tar.gz -c chatto.toml

   For encrypted backups, encryption is auto-detected — you’ll be prompted for the passphrase:

   chatto restore backup.tar.gz.age -c chatto.toml

   You can also pass the passphrase via flag:

   chatto restore backup.tar.gz.age -c chatto.toml --passphrase "$BACKUP_PASSPHRASE"

3. Start Chatto normally

   chatto start -c chatto.toml

Conflict handling

By default, restore fails if any stream already exists. Use --conflict to change this:

Flag	Behavior	Use case
--conflict=error	Fail if any stream exists (default)	Fresh instance restore
--conflict=skip	Skip existing streams	Partial restore / merge
--conflict=overwrite	Delete and recreate existing streams	Full restore over existing data

# Restore missing streams only, keep existing data
chatto restore backup.tar.gz -c chatto.toml --conflict=skip

# Full overwrite (destructive!)
chatto restore backup.tar.gz -c chatto.toml --conflict=overwrite

Encryption key backup

Encryption keys are excluded from data backups by design — since Chatto always encrypts message bodies, this ensures that a leaked backup archive doesn’t expose message content. To fully restore messages, you need to export the keys separately.

Exporting keys

chatto keys export -c chatto.toml -o keys.backup

You’ll be prompted for a passphrase. The export file is encrypted using age, so it’s safe to store — but use a strong passphrase.

For scripted/automated backups, pass the passphrase via flag or pipe it from stdin:

chatto keys export -c chatto.toml -o keys.backup --passphrase "$KEY_BACKUP_PASSPHRASE"

# Or pipe from a secrets manager
vault kv get -field=passphrase secret/chatto | chatto keys export -c chatto.toml -o keys.backup

Importing keys

After restoring a data backup, import the encryption keys:

chatto keys import keys.backup -c chatto.toml

Existing keys are never overwritten — only keys for users that don’t already have one are imported. This makes it safe to re-run.

Complete disaster recovery

For a full restore with encrypted message recovery:

1. Restore the data backup

   chatto restore backup.tar.gz.age -c chatto.toml

2. Import the encryption keys

   chatto keys import keys.backup -c chatto.toml

3. Start the server

   chatto start -c chatto.toml

Tip

Without the key import step, the instance will function normally — users can log in, browse spaces, and send new messages. Only previously encrypted message bodies will appear as unavailable.

Automated backup script

Here’s a complete example backup script suitable for a cron job:

#!/bin/bash
set -euo pipefail

CONFIG="/etc/chatto/chatto.toml"
BACKUP_DIR="/mnt/backups/chatto"
PASSPHRASE_FILE="/etc/chatto/backup-passphrase"  # chmod 600
RETENTION_DAYS=14

# Read passphrase from file
PASSPHRASE=$(cat "$PASSPHRASE_FILE")

# Create timestamped backup
TIMESTAMP=$(date -u +%Y-%m-%dT%H-%M-%SZ)
BACKUP_FILE="$BACKUP_DIR/$TIMESTAMP.tar.gz.age"

chatto backup -c "$CONFIG" --encrypt --passphrase "$PASSPHRASE" -o "$BACKUP_FILE"
chatto keys export -c "$CONFIG" -o "$BACKUP_DIR/$TIMESTAMP-keys.age" --passphrase "$PASSPHRASE"

# Remove backups older than retention period
find "$BACKUP_DIR" -name "*.age" -mtime +$RETENTION_DAYS -delete

echo "Backup complete: $BACKUP_FILE"

Using the age CLI

All Chatto encrypted files (backups and key exports) use the standard age format. This means you can work with them using the age CLI tool, which is useful for verification, key rotation, or emergency access.

Installing age

# macOS
brew install age

# Debian/Ubuntu
apt install age

# From source
go install filippo.io/age/cmd/...@latest

Decrypting a backup manually

If you need to access a backup without chatto restore — for example, to inspect the manifest or extract specific files:

# Decrypt the archive (prompts for passphrase)
age -d backup.tar.gz.age > backup.tar.gz

# Then extract normally
tar xzf backup.tar.gz

# Inspect the manifest
cat backup/manifest.json | jq .

Decrypting a key export manually

# Decrypt the key export (prompts for passphrase)
age -d keys.backup > keys.json

# View the exported keys (careful — contains sensitive data!)
cat keys.json | jq .

Re-encrypting with a different passphrase

# Decrypt with the old passphrase
age -d backup.tar.gz.age > backup.tar.gz

# Re-encrypt with a new passphrase
age -p backup.tar.gz > backup-new.tar.gz.age

# Clean up the unencrypted file
rm backup.tar.gz

Caution

When decrypting files manually, the unencrypted data is temporarily on disk. Make sure to securely delete the plaintext files when you’re done — especially key exports, which contain the raw encryption keys.

Backup strategy recommendations

Frequency: Schedule backups based on your tolerance for data loss. For active instances, daily backups are a reasonable starting point.

Retention: Keep multiple backup archives. A common pattern is daily backups retained for 14 days, plus weekly backups retained for 8 weeks.

Storage: Store backups on a different volume or remote storage (S3, GCS) from the NATS data directory. A backup on the same disk as the data doesn’t protect against disk failure.

Encryption: Always use --encrypt for backups stored on shared or remote storage. Even though message bodies are already encrypted, backups contain sensitive metadata (user info, space structure, membership lists).

Key separation: Store key exports separately from data backups when possible. The two files together unlock everything — keeping them in different locations adds defense in depth.

Testing: Periodically test restores to a separate instance to verify your backups are valid and your passphrase works.