|
| 1 | +# AI Backup Runbook (`ai-backup`) |
| 2 | + |
| 3 | +One-shot compressed backup/restore of AI-assistant state (Claude Code, |
| 4 | +OpenCode, Engram) as a single `.tar.zst` archive, with consistent SQLite |
| 5 | +snapshots taken on the source host. |
| 6 | + |
| 7 | +Binary: `pkgs/nixos-scripts/cmd/ai-backup` (Go; the backup logics are |
| 8 | +POSIX-sh payloads embedded in that source, executed via `/bin/sh -s` on |
| 9 | +the source host — including macOS). |
| 10 | + |
| 11 | +> ## ⚠️ Security warning — read before sharing |
| 12 | +> |
| 13 | +> The archive contains **`~/.local/share/opencode/auth.json`** (OpenCode |
| 14 | +> API credentials) and **`~/.claude.json`**, which **may contain OAuth |
| 15 | +> tokens** for Claude. Anyone who can read the archive can use your AI |
| 16 | +> subscriptions. The default destination is a private Samba share that |
| 17 | +> is LAN-reachable with guest-ok semantics; treat the destination host |
| 18 | +> and LAN as part of the threat model. Keep share permissions private |
| 19 | +> (per-user share, no world access) and do not copy archives out of it. |
| 20 | +> To rotate after a suspected leak: log out/in and re-auth OpenCode |
| 21 | +> (`opencode auth login`). |
| 22 | +
|
| 23 | +## Commands |
| 24 | + |
| 25 | +``` |
| 26 | +ai-backup backup [TARGET] # default target mact2 |
| 27 | +ai-backup list |
| 28 | +ai-backup restore ARCHIVE [--to TARGET] [--dry-run] |
| 29 | +``` |
| 30 | + |
| 31 | +Examples: |
| 32 | + |
| 33 | +```bash |
| 34 | +# Backup the default source (mact2) to the default destination. |
| 35 | +ai-backup backup |
| 36 | + |
| 37 | +# Local snapshot of this host, dry-run inspection only. |
| 38 | +ai-backup restore /run/media/stuff/samba/backup/ai/mact2/ai-backup-mact2-YYYYMMDD-HHMMSS.tar.zst --dry-run |
| 39 | + |
| 40 | +# Inspect an archive without decompressing to disk: |
| 41 | +zstd -dc ARCHIVE | tar -tf - | less |
| 42 | + |
| 43 | +# Verify a published checksum sidecar: |
| 44 | +cd /run/media/stuff/samba/backup/ai/mact2 && sha256sum -c ai-backup-mact2-*.sha256 |
| 45 | + |
| 46 | +# Restore locally, keeping pre-restore copies of everything replaced: |
| 47 | +ai-backup restore ARCHIVE --to local |
| 48 | + |
| 49 | +# Restore onto another host over ssh. |
| 50 | +ai-backup restore ARCHIVE --to t14 |
| 51 | +``` |
| 52 | + |
| 53 | +A backup publishes `<dest>/<label>/ai-backup-<label>-<ts>.tar.zst` |
| 54 | +atomically (`.part` removed on failure, renamed only when complete) plus |
| 55 | +a `.sha256` sidecar. Dry-run and `list` never modify data. |
| 56 | + |
| 57 | +## What is included / skipped |
| 58 | + |
| 59 | +| Family | Archived | Skipped (regenerable or live) | Why | |
| 60 | +|---|---|---|---| |
| 61 | +| Claude state | `~/.claude/{projects/,history.jsonl,plans/,todos/,keybindings.json}` and the nested `~/.claude/.claude/` tree, sibling `~/.claude.json`[^claude] | settings, `CLAUDE.md`, skills, commands, agents, caches, shell-snapshots, telemetry, plugin caches, Keychain/`.credentials.json` | Sessions and history are irreplaceable state; settings, caches and credentials are regenerable (config ownership belongs to the dotfile system) | |
| 62 | +| OpenCode state | `~/.local/share/opencode/{storage/,auth.json,opencode-multimodal.json}` + snapshot of every channel-dependent `opencode-<channel>.db`[^opencode] | `bin/`, `log/`, `snapshot/`, `tool-output/`, `node_modules`, live `*.db`, `-wal`/`-shm` sidecars, `.config/opencode/` | live DBs snapshot via `sqlite3 .backup` (safe under WAL); the rest is runtime/provisioned state[^opencode2] | |
| 63 | +| Engram | global `~/.engram/engram.db` as `…/engram.db.snapshot` only; project dirs opt-in via `AI_BACKUP_EXTRA`[^engram] | live `~/.engram/` tree, `engram.db.before-*`/`pre-cleanup.*` backups, `-wal`/`-shm` | snapshot copy is the consistent moment-in-time copy recommended by SQLite's own backup guide[^sqlite] | |
| 64 | +| Extra project dirs | `AI_BACKUP_EXTRA`, verbatim (see env reference) | — | opt-in only | |
| 65 | + |
| 66 | +[^claude]: `~/.claude.json` may contain OAuth credentials — plain file, |
| 67 | + sibling member, copied to `.claude.json.pre-restore-<ts>` before a |
| 68 | + restore overwrites it. Source: <https://code.claude.com/docs/en/claude-directory>. |
| 69 | +[^opencode]: DB names are channel-dependent (`opencode-main.db` etc.); |
| 70 | + symlinks are resolved before snapshotting and the staged name is |
| 71 | + `<real-basename>.db.snapshot`. Source: |
| 72 | + <https://github.com/sst/opencode/issues/13654>. |
| 73 | +[^opencode2]: Verified against OpenCode's data-layout troubleshooting |
| 74 | + guide: <https://opencode.ai/docs/troubleshooting>. |
| 75 | +[^engram]: Snapshot semantics follow the store's own backup path in |
| 76 | + <https://github.com/Gentleman-Programming/engram> (`store.go`). |
| 77 | +[^sqlite]: <https://www.sqlite.org/backup.html>. |
| 78 | + |
| 79 | +## After restore |
| 80 | + |
| 81 | +1. **Claude re-login** — Keychain and `.credentials.json` are excluded, |
| 82 | + so Claude Code asks you to authenticate again on the target host; the |
| 83 | + `.claude.json` from the archive is preserved as |
| 84 | + `.claude.json.pre-restore-<ts>` first (`keep old .claude.json` in |
| 85 | + the output). Same for OpenCode if `auth.json` was absent from the |
| 86 | + archive (`opencode auth login`). |
| 87 | +2. **Snapshot integrity** — the restore payload runs `PRAGMA |
| 88 | + integrity_check` on every restored DB and the command exits nonzero |
| 89 | + if any output is not exactly `ok`. Verify manually: |
| 90 | + ```bash |
| 91 | + sqlite3 ~/.local/share/opencode/opencode-main-stable.db 'PRAGMA integrity_check;' |
| 92 | + ``` |
| 93 | +3. **Legacy session count** — OpenCode migrated its store out of the |
| 94 | + legacy `storage/` directory; the count from the archived machine |
| 95 | + must match the count after restore: |
| 96 | + ```bash |
| 97 | + find ~/.local/share/opencode/storage -type f | wc -l |
| 98 | + ``` |
| 99 | + Zero or a lower count than expected means the storage member did not |
| 100 | + survive the round-trip — re-inspect the archive before deleting |
| 101 | + anything. |
| 102 | + |
| 103 | +## Restoring snapshots (payload behaviour) |
| 104 | + |
| 105 | +Snapshot members live under `home-snap/…` in the archive. The restore |
| 106 | +payload, per db: |
| 107 | + |
| 108 | +- strips the `.db.snapshot` suffix and moves the staged snapshot back to |
| 109 | + its live path (realpath basename), |
| 110 | +- **resolves an existing destination symlink first** — it never moves |
| 111 | + onto a symlink (Home-Manager re-created ones, like rog's |
| 112 | + `opencode.db → opencode-stable.db`) and moves onto the resolved file, |
| 113 | +- keeps a timestamped `*.pre-restore-<ts>` copy of every file it |
| 114 | + replaces, |
| 115 | +- integrity-checks every restoration target (including pre-existing |
| 116 | + DBs). |
| 117 | + |
| 118 | +## Environment reference |
| 119 | + |
| 120 | +| Env | Default | Meaning | |
| 121 | +|---|---|---| |
| 122 | +| `AI_BACKUP_DEST` | `/run/media/stuff/samba/backup/ai` | destination root for backup/list | |
| 123 | +| `AI_BACKUP_ZSTD_LEVEL` | `6` | `zstd -T0 -<level>` compression level (1–19) | |
| 124 | +| `AI_BACKUP_SSH_OPTS` | `-o BatchMode=yes -o ConnectTimeout=8` | extra ssh options for the source host | |
| 125 | +| `AI_BACKUP_EXTRA` | *(unset)* | Space-separated list of absolute paths on the source host; only paths that exist are archived, skipped silently when absent. Typically project `.engram/` dirs: their `chunks/`, `manifest.json` and `config.json` members are archived verbatim as `extras/<project>/.engram/...`, and after restore they land in `~/extras/<project>/.engram/` (never over the global `~/.engram`). The live project `engram.db` never enters. Usage example: `AI_BACKUP_EXTRA="/home/glats/dev/gentle-ai/.engram /home/glats/work/notesta/.engram" ai-backup backup mact2` | |
| 126 | + |
| 127 | +## Limitations |
| 128 | + |
| 129 | +- **No transcript path remapping**: Claude stores project transcripts in |
| 130 | + cwd-encoded directory names (`projects/-home-glats-nixos/…`). A |
| 131 | + restore onto a different host/username means those paths refer to a |
| 132 | + machine-local layout and sessions are not re-encoded into the new |
| 133 | + host's session list automatically. |
| 134 | +- **`.claude/.claude` is included whole** (triage-later): its final |
| 135 | + content split is intentionally deferred — it exists in every archive |
| 136 | + for the cost of its bytes. |
| 137 | +- **Multimodal provenance is not interpreted**: `opencode-multimodal.json` |
| 138 | + is archived raw; attachments referenced by storage paths may decay if |
| 139 | + a project's unstaged files changed between backup and restore. |
| 140 | +- **The live Engram tree never rides**: if project `.engram` state must |
| 141 | + ride, name it in `AI_BACKUP_EXTRA` — it is never implicit. |
| 142 | +- sqlite3 must exist on the source host; the payload falls back to |
| 143 | + `/usr/bin/sqlite3` after a PATH probe. |
0 commit comments