Backup & Restore

If you’re reading this calmly, on a Tuesday afternoon, with a cup of coffee — good. You’re doing this right.

If you’re reading this at 3 AM because a disk just made a sound disks should never make — we’re sorry. But this is exactly why this page exists, and past-you was smart enough to set up backups. Unless past-you didn’t, in which case present-you has our deepest condolences.

Daily Backup (on manoir)

Runs automatically at 04:00 via the com.sanctum.backup LaunchAgent — an hour when nothing good or bad is happening, which is precisely the hour you want for the thing standing between you and oblivion.

# Manual run
bash ~/Backups/sanctum-backup.sh

Architecture: restic, content-addressed, dual repo

The daily backup uses restic — a content-addressed deduplicating backup tool that splits files into ~1 MB chunks (Rabin fingerprinting), stores each unique chunk exactly once, and encrypts everything client-side with AES-256 + Poly1305. Two repos receive the same snapshot every day:

Repo	Purpose	Where
T9 (primary)	Local, fast restore, full history	/Volumes/T9/sanctum-restic
Google Drive (offsite)	Disaster recovery, encrypted	rclone:gdrive-sanctum:sanctum-restic

Each daily run only ships changed blocks. Typical delta after the first snapshot is tens of MB, not the 46 GB of raw ~/.sanctum. The first snapshot took 20 minutes; daily increments take seconds.

Tip

3-2-1 backup posture: 3 copies (live system + T9 + cloud), 2 media types (NVMe SSD + cloud object store), 1 offsite (Google Drive in the AI Ultra account, 30 TiB headroom). Anything less is gambling.

What Gets Backed Up

• OpenClaw config (~/.openclaw/)
• Sanctum config (~/.sanctum/)
• Claude Code state (~/.claude/, with cache/telemetry excluded)
• All LaunchAgent plists
• SSH keys and config (the whole repo is encrypted, so private keys live alongside everything else)
• Shell + git config (.zshrc, .zprofile, .gitconfig)
• TTS models and voice files
• Selected project source trees (node_modules, .venv, target, model files excluded — restic dedups, but excluding rebuildables saves scan time)
• Per-run metadata: crontab, Homebrew lists, Docker state, LM Studio model list, tool versions, VM SSH-side configs

Tip

If it took you more than a weekend to configure, it gets backed up. That’s the rule. Weekday-afternoon work is expendable. Weekend work is sacred. Restic dedup means even “back up everything” costs almost nothing past day one.

Encryption

The entire repo — every byte that hits T9 or leaves your machine for Google Drive — is encrypted client-side with AES-256 using a passphrase from macOS Keychain (sanctum-backup-key). Even if someone walked off with T9 or compromised your Drive folder, they would see opaque ciphertext blobs.

Danger

The Keychain entry is the single trust anchor. Lose sanctum-backup-key from both Keychain and 1Password and the data is genuinely unrecoverable — restic has no backdoor, which is exactly the security model you want. Mirror it to 1Password the day you create it. Then test the restore once a quarter so “I have a backup” doesn’t quietly decay into “I had a backup.”

Retention (GFS, enforced by restic forget —prune)

--keep-daily 7    # last 7 daily snapshots
--keep-weekly 4   # one snapshot per week, last 4 weeks
--keep-monthly 12 # one snapshot per month, last year

Runs inline on every backup. Restic’s prune does block-level garbage collection — old snapshots are removed and any chunks no longer referenced by any surviving snapshot are reclaimed. There is no separate retention script; the policy lives in the backup script itself.

Note

Earlier iterations used a custom GFS function in bash that ran weekly via a separate LaunchAgent (com.triptyq.backup-retention). It worked, but split logic between two scripts and used a different host-naming convention. Both have been retired in favor of restic’s built-in policy + a single canonical job.

Why we moved off iCloud full-copy snapshots

Until 2026-04-26 the daily backup was an rsync of ~/.sanctum into a new dated directory under iCloud/Backups/daily/YYYY-MM-DD/. Each snapshot was a full copy. iCloud Drive doesn’t understand hardlinks, so even a --link-dest-based incremental wouldn’t have worked through the Files-app sync layer. The result, observed empirically:

• 15 daily directories on internal SSD: 356 GB
• Each snapshot: ~46 GB of mostly-identical bytes copied fresh
• iCloud was syncing all of that every day in both directions
• Internal SSD hit 95% capacity, triggering this entire migration

The same retention window in restic: 15 GB on disk after seven days, growing by a few hundred MB per week. Reclaimed 357 GB the moment the legacy iCloud tree was deleted.

Caution

iCloud is sync, not backup. Same applies to OneDrive and Google Drive via the Files-app sync client. Cloud backup tools (restic, borg, kopia) talk to cloud object stores via API (rclone, S3 SDK), not via local sync clients — that’s the layer where deduplication, retention, and integrity checking live. If your backups land in ~/Library/Mobile Documents/ or ~/Library/CloudStorage/, you have a sync, not a backup.

VM Snapshot

Weekly automated snapshot (Sundays 3am):

bash ~/Backups/vm-snapshot.sh

Creates compressed copies of the VM disk image and EFI vars:

• iCloud/Backups/VM/qcow2.zst
• iCloud/Backups/VM/efi_vars.fd.zst

Uses live copy (no VM suspend) with SSH sync before snapshot. The VM keeps running. It doesn’t even know it’s being photographed.

Restore

Seven phases. Like grief, but more useful.

1. Homebrew — Restore package list, brew install
2. Dotfiles & SSH — Restore keys, shell config
3. App configs — OpenClaw, Sanctum, HA
4. Projects — Restore git repos
5. LM Studio — Re-download models (not backed up due to size)
6. Docker — Restore container configs
7. LaunchAgents — Restore plists, bootstrap services

bash ~/Backups/sanctum-restore.sh

Note

Phase 5 is a re-download, not a restore. Multi-gigabyte model files don’t back up well to iCloud, and Apple would prefer you not try. Budget an hour and a good internet connection.

Backup Scripts

Script	Purpose
sanctum-backup.sh	Daily restic backup → T9 + Google Drive
sanctum-restore.sh	Multi-phase restore (legacy, predates restic — see “Restoring from restic” below)
vm-snapshot.sh	Weekly VM disk snapshot
rotate-secrets.sh	Monthly secret rotation
backup-sanctum.sh (MBP)	Weekly cross-machine snapshot, pulls ~/.sanctum/ from manoir to MBP — see below

Treat each one with the respect you’d give a fire extinguisher — boring until the day it’s the only thing that matters.

Note

The retired backup-retention.sh and ~/.openclaw/scripts/icloud-backup.sh live in the same dir with .legacy suffixes — kept for forensic value and to make the cron line removal reversible if anything goes sideways during the cut-over. Safe to delete after a couple of clean weeks under restic.

Restoring from restic

export RESTIC_PASSWORD=$(security find-generic-password -a sanctum-backup -s sanctum-backup-key -w)

# List snapshots from either repo
restic -r /Volumes/T9/sanctum-restic snapshots
restic -r rclone:gdrive-sanctum:sanctum-restic snapshots

# Restore everything from the latest snapshot to a target dir
restic -r /Volumes/T9/sanctum-restic restore latest --target /tmp/restore

# Restore one file (mount the repo as a read-only FUSE filesystem and just `cp`)
restic -r /Volumes/T9/sanctum-restic mount /tmp/restic-mount    # (Linux only; on macOS use `restore --include`)
restic -r /Volumes/T9/sanctum-restic restore latest \
  --target /tmp/restore \
  --include /Users/neo/.sanctum/instance.yaml

# Verify a repo end-to-end (run quarterly)
restic -r /Volumes/T9/sanctum-restic check
restic -r rclone:gdrive-sanctum:sanctum-restic check

Tip

“Untested backups aren’t backups.” Schedule a quarterly drill where you pick a random snapshot, restore it to /tmp/restore-test, and diff it against live state. The drill is the only thing that proves the strategy still works.

Disk-Pressure Tripwire

The 2026-04-26 incident — internal SSD at 95% capacity from full-copy iCloud snapshots — exposed a missing layer: there was no early signal. The /status endpoint of the Navigator Sidecar (navigator-sidecar.js, port 3344) now emits a disk block:

{
  "disk": {
    "path": "/System/Volumes/Data",
    "status": "OPERATIONAL",
    "usedPct": 55,
    "usedGb": 476,
    "freeGb": 400,
    "totalGb": 926,
    "thresholds": { "warn": 85, "fail": 90 },
    "message": "55% used"
  }
}

Status flips to DEGRADED at 85% (warn) and FAILED at 90% (page). Disk health folds into the aggregate sidecar status, so a Holocron tile turning yellow now means either a project monitor flagged degradation or the disk is filling. Configurable via NAVIGATOR_DISK_PATH, NAVIGATOR_DISK_WARN_PCT, NAVIGATOR_DISK_FAIL_PCT.

Note

This is a tripwire, not a janitor. It tells you the disk is filling; it doesn’t try to fix it. Auto-deleting things on disk pressure is exactly the kind of “helpful” behavior that loses data — every cleanup must be a deliberate, reviewable action.

Weekly Cross-Machine Snapshot (MBP pulls from manoir)

The daily backup lives on the Mini. If the Mini itself is compromised — disk failure, filesystem corruption, malicious actor — that backup is gone with it. The weekly snapshot is the second dimension: pulled from manoir to the MBP every Saturday 04:30, SHA256-pinned, rotated to last 8.

# Manual run from MBP
~/Documents/Claude_Code/tools/backup-sanctum.sh
# ...or the deployed copy that the LaunchAgent invokes:
~/.local/bin/backup-sanctum.sh

Pipeline

• tools/backup-sanctum.sh tars ~/.sanctum/{scripts,services,state,docs,bin,boot,instance.yaml} plus critical LaunchAgent plists on manoir via SSH.
• ~/.sanctum/secrets/ is excluded — secrets live in keychain / 1Password / SOPS, not this tarball.
• ~/.sanctum/logs/ is excluded — too large, not load-bearing.
• The tarball is pulled to ~/Backups/sanctum-mini/sanctum-mini-<timestamp>.tgz.
• A .sha256 trailer is written alongside. shasum -a 256 -c <file>.sha256 verifies integrity.
• Rotation keeps the newest 8 snapshots (≈2 months of weekly history).

Caution

The script is installed at two locations: the source of truth lives in the repo at ~/Documents/Claude_Code/tools/backup-sanctum.sh, and a deployed copy lives at ~/.local/bin/backup-sanctum.sh. The LaunchAgent invokes the ~/.local/bin/ copy because macOS TCC (Transparency, Consent, Control) blocks launchd-spawned bash from reading or writing under ~/Documents/. After editing the repo copy, run cp tools/backup-sanctum.sh ~/.local/bin/ to sync. Same reason the backup destination is ~/Backups/sanctum-mini/ and not ~/Documents/....

Schedule

~/Library/LaunchAgents/com.sanctum.backup.plist (template in-repo at Claude_Code/tools/launchagents/):

<key>StartCalendarInterval</key>
<dict>
    <key>Weekday</key>   <integer>6</integer>  <!-- Saturday -->
    <key>Hour</key>      <integer>4</integer>
    <key>Minute</key>    <integer>30</integer>
</dict>

Activate with:

launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.sanctum.backup.plist
launchctl enable gui/$(id -u)/com.sanctum.backup

Verify a snapshot

cd ~/Backups/sanctum-mini
shasum -a 256 -c sanctum-mini-20260418-111502.tgz.sha256   # expect: OK

# See what's inside
tar -tzf sanctum-mini-20260417-222652.tgz | head

# Restore a single file onto manoir
tar -xzf sanctum-mini-20260417-222652.tgz \
    Users/neo/.sanctum/services/council-mlx.yaml \
  -O | ssh neo@100.0.0.25 'cat > /Users/neo/.sanctum/services/council-mlx.yaml'

Caution

The tarball stores paths as Users/neo/... (no leading slash). Extract to / if you want the filesystem layout restored in place, or extract to a staging directory and rsync selectively. Never tar -xzf into / without reading the contents first — the snapshot includes LaunchAgent plists that will start services on next load.