Backup

A Runtime Host's durable state lives entirely under <host-home>. There is no separate database, no system-managed registry, no machine-keyed encryption layer. Backup is "copy the home, skip the volatile bits."

What to back up

Path (relative to <home>)	Content	Back up?
host.json	hand-edited config	yes — the most important file
credentials/	install identity, Device Link records, NATS creds	yes — encrypt at rest
runtimes/<id>/runtime.json	runtime durable records	yes — preserves desired state
packages/global/node_modules/	user-installed packages	yes (or re-install via matrix install)
packages/system/node_modules/	wrapper-seeded defaults	optional — hivecast seed rehydrates this
nats/host-default/ (or nats/service/)	JetStream data, NATS config	yes — Streams + KV state lives here
runtime-env/<id>.environment.json	derived env files	no — Host rewrites on start
host.status.json, host.pid	live status	no — must not be present in a restore target
host.start.lock	startup lock file	no — rebuilt on next start
logs/	logs	optional — usually not worth the volume
bin/nats-server[.exe]	bundled binary	no — hivecast install redrops it

Stopping or live snapshot

Two reasonable strategies:

Stop-the-world snapshot (safer)

sudo systemctl stop hivecast-host.service hivecast-nats.service
sudo tar -C / -czf hivecast-backup-$(date +%Y%m%d).tar.gz \
  --exclude='var/lib/hivecast/host.status.json' \
  --exclude='var/lib/hivecast/host.pid' \
  --exclude='var/lib/hivecast/host.start.lock' \
  --exclude='var/lib/hivecast/runtime-env' \
  --exclude='var/lib/hivecast/logs' \
  --exclude='var/lib/hivecast/bin/nats-server' \
  var/lib/hivecast/
sudo systemctl start hivecast-nats.service hivecast-host.service

This guarantees JetStream is quiesced and runtime.json records are not being rewritten.

Live snapshot (faster, slightly riskier)

Atomic writes mean every individual file is consistent at any moment. But a live snapshot is not transactionally consistent across files — JetStream may be mid-write to its on-disk store. For NATS in particular this can leave a backup that fails to mount. If you need consistency: stop NATS or use filesystem-level snapshotting (LVM, ZFS, btrfs).

# Live filesystem-level snapshot (Linux LVM example).
sudo lvcreate --size 5G --snapshot --name hivecast-snap /dev/vg0/hivecast
sudo mount -o ro /dev/vg0/hivecast-snap /mnt/hivecast-snap
tar -czf hivecast-backup-$(date +%Y%m%d).tar.gz -C /mnt/hivecast-snap .
sudo umount /mnt/hivecast-snap
sudo lvremove -f /dev/vg0/hivecast-snap

Wrapper installs

For per-user installs (no systemd), the equivalent is:

hivecast stop --home "$HOST_HOME"
tar -czf hivecast-backup-$(date +%Y%m%d).tar.gz \
  --exclude="$HOST_HOME/host.status.json" \
  --exclude="$HOST_HOME/host.pid" \
  --exclude="$HOST_HOME/host.start.lock" \
  --exclude="$HOST_HOME/runtime-env" \
  --exclude="$HOST_HOME/logs" \
  --exclude="$HOST_HOME/bin/nats-server" \
  -C "$(dirname "$HOST_HOME")" "$(basename "$HOST_HOME")"
hivecast start --home "$HOST_HOME"

Backing up credentials separately

The credentials/ directory contains:

• hivecast-install.json — the per-install identity. Must survive reinstalls so the same Host stays the same Host across upgrades.
• hivecast-link.json — the Device Link, only present after pairing.
• NATS credentials referenced by credentialsRef in host.json.
• Anything system.factotum has stashed (Anthropic OAuth tokens, Codex tokens, etc.).

Treat this directory as secret material. Always encrypt the backup at rest. Per repo CLAUDE.md Rule 4, these credentials must never leave the local machine in plaintext form.

Verifying a backup

tar -tzf hivecast-backup-...tar.gz | grep host.json   # config present?
tar -tzf hivecast-backup-...tar.gz | grep credentials/hivecast-install.json
tar -tzf hivecast-backup-...tar.gz | wc -l            # rough sanity check

For a deeper check, do a Restore into a scratch directory and confirm hivecast doctor --home <scratch> is healthy before committing to the real restore target.

See also

• Restore
• Filesystem layout
• Diagnostics