Documentation

Everything you need to back up your Linux machines with chronicled.

# Quick Start

1. Install the CLI agent:

curl -sSL https://chronicled.sh/install.sh | sh

2. Authenticate:

chr init

Sends a login code to your email. Enter the code to authenticate.

3. Run your first backup:

chr backup

Or create a full system backup for bare-metal recovery:

chr backup --bare-metal

Captures /boot, /usr, /var, /etc, /home, and your disk layout for complete system recovery.

4. Check status:

chr status

# CLI Reference

Command	Description
chr init	Authenticate with email code or --token
chr backup	Create a backup of configured paths
chr backup --full	Full machine snapshot (all standard paths)
chr backup --bare-metal	Full system + disk layout for recovery ISO
chr backup --paths /x,/y	Override backup paths for this run
chr restore <id>	Restore a snapshot to the current machine
chr restore <id> --target /path	Restore to a specific directory
chr restore <id> --to-exe-dev	Restore into a new exe.dev VM
chr snapshots	List all snapshots
chr diff <id1> <id2>	Compare two snapshots
chr status	Account info, storage, plan
chr prune	Remove old snapshots per retention policy
chr version	Print version
chr recovery-iso	Build a bootable recovery ISO (~234 MB)
chr recovery-iso --arch arm64	Build for ARM64 servers (EFI only)
chr recovery-iso --output f.iso	Specify output filename

# Configuration

Config is stored at ~/.config/chronicled/config.toml

[auth]
token = "tok_..."              # Your API token
endpoint = "https://api.chronicled.sh"  # API endpoint

[backup]
mode = "selective"             # "selective" or "full"
paths = ["/home/user", "/etc"]  # Paths to back up
exclude = [                    # Patterns to skip
  "node_modules",
  ".cache",
  "__pycache__",
  ".venv",
  ".nvm",
  "*.sock",
  "*.tmp",
]

[encryption]
enabled = false                # Client-side AES-256-GCM
key = ""                       # Encryption key (hex)

# How It Works

chronicled uses content-defined chunking (FastCDC) to split your files into variable-size chunks. Each chunk is hashed with SHA-256 and only uploaded if the server doesn't already have it.

Chunking

FastCDC with 256KB min, 1MB average, 4MB max chunk sizes.

Deduplication

SHA-256 content addressing. Identical data across files or snapshots is stored once.

Compression

zstd compression on each chunk before upload.

Encryption

Optional AES-256-GCM client-side encryption. Server never sees plaintext.

Backups are incremental by default. After the first backup, only new or changed chunks are uploaded. A typical second backup takes under a second if nothing changed.

# Automatic Backups

The installer can set up a systemd timer that runs every 6 hours. You can also set it up manually:

sudo systemctl enable --now chronicled.timer
systemctl status chronicled.timer
journalctl -u chronicled.service --since today

# Bare-Metal Recovery

Recover a completely dead machine from a bootable USB or ISO.

# Create a bare-metal backup (includes /boot, /usr, /var + disk layout)
chr backup --bare-metal

# Build a recovery ISO (x86_64, BIOS + EFI)
chr recovery-iso --output recovery.iso

# Or build for ARM64 servers (Ampere, Graviton, Hetzner CAX)
chr recovery-iso --arch arm64 --output recovery-arm64.iso

# Write to USB
sudo dd if=recovery.iso of=/dev/sdX bs=4M status=progress

The recovery ISO boots into a guided TUI that handles:

• Network setup and authentication
• Snapshot selection
• Disk partitioning (simple, LUKS, LVM, or LUKS+LVM)
• File restoration from your chronicled.sh account
• GRUB bootloader installation
• initramfs regeneration and fstab fixup

Supports x86_64 (BIOS + EFI) and ARM64 (EFI only), ext4/XFS/Btrfs, software RAID (mdadm), and full disk encryption.

# exe.dev Integration

Restore any snapshot directly into a brand-new exe.dev VM:

# Restore to a new exe.dev VM (auto-named)
chr restore snap_a1b2c3 --to-exe-dev

# Restore with a specific name
chr restore snap_a1b2c3 --to-exe-dev --vm-name my-restored-vm

This creates a new exe.dev VM, copies the chr agent to it, runs the restore remotely, and prints the SSH address when done. Requires: ssh exe.dev ls must work.

# Environment Variables

Variable	Description
CHR_TOKEN	Override API token (skips config file)
CHR_ENDPOINT	Override API endpoint
CHR_ENCRYPTION_KEY	Set encryption key (enables encryption)
CHR_VERSION	Version to install (install script)
CHR_INSTALL_DIR	Install directory (default: /usr/local/bin)
CHR_NO_SYSTEMD	Set to 1 to skip systemd setup

# Storage & Pricing

Free

5 GB storage. Unlimited machines. Perfect for trying it out.

Pro — $5/mo

100 GB storage. Priority support. Longer retention.

Storage is measured after deduplication and compression — your actual usage is typically much less than the raw file sizes. See full pricing →

# FAQ

What Linux distributions are supported?

Any Linux on amd64 or arm64. The agent is a static Go binary with no dependencies.

Where are my backups stored?

Cloudflare R2, a globally distributed object store. Data is stored in the region closest to you.

Is my data encrypted?

All data is encrypted in transit (TLS). Optional client-side AES-256-GCM encryption is available — when enabled, the server never sees your plaintext data.

How much bandwidth does a backup use?

Only new/changed data is uploaded. After the initial backup, incremental backups typically transfer very little. Deduplication means identical files across machines are stored once.

Can I restore to a different machine?

Yes. Use chr restore <id> --target /path on any machine. Or use --to-exe-dev to restore into a fresh exe.dev VM.

What is bare-metal recovery?

Bare-metal recovery lets you rebuild a completely dead machine from a bootable USB. Run chr recovery-iso to create a ~234 MB ISO (or --arch arm64 for ARM64 servers), write it to a USB drive, and boot any x86_64 or ARM64 machine. The guided TUI walks you through authentication, snapshot selection, disk partitioning (including LUKS/LVM), file restoration, and bootloader installation.

# Support

Questions? Email support@chronicled.sh or file an issue on GitHub.