dsh-vault

English | 中文

A dsh plugin that backs up your dsh home config — encrypted — to your own private GitHub repo, and pulls it flat onto a new machine with one command: restore the config, reinstall plugins from the manifest. Cross-machine restore doubles as migration.

Zero npm dependencies: encryption uses only Node's built-in crypto (scrypt + AES-256-GCM); GitHub transfer goes through the REST API.

Commands

/vault backup [passphrase]        Back up and push (creates the private repo if missing)
/vault list                       Table of every machine's backup in the vault
                                  (machine / description / snapshot time / file count / size, ← this machine)
/vault restore [machine] [--yes] [passphrase]
                                  No machine name = list snapshots
                                  Picking another machine = migration; --yes actually executes
/vault config                     Show current settings
/vault set repo <owner/name>      Override the default vault repo name
/vault set machine-desc <desc>    Machine description (recorded in the snapshot manifest,
                                  for identification when picking across machines)
/vault set remember-passphrase on|off
                                  When on, the next backup with a passphrase stores it in
                                  the macOS keychain for automatic reuse

Backup set

In: settings.yaml, .credentials.yaml (API keys), APPEND_SYSTEM.md, agents/, each profile's manifest four-pack (package.json / pnpm-lock.yaml / pnpm-workspace.yaml / cordis.patch.yml), the home-level cordis.patch.yml, and models-store.json.

Out: sessions/, storages/, every node_modules (reinstalled from the manifest), cordis.yml (unconditionally rewritten by the host at startup), .anonymous-user-id, usage stats.

Security model

• Snapshots are encrypted whole before leaving the machine: passphrase → scrypt-derived key → AES-256-GCM (vault format v1; the header carries its KDF parameters and a version).
• The private repo is only the first door (token leakage); encryption is the data door. A lost passphrase means the snapshot is unrecoverable — the plugin offers no recovery.
• Three ways to supply the passphrase: inline in the command (recordInput: false, never lands in session logs) → the $DSH_VAULT_PASSPHRASE env var → the macOS keychain (stored automatically when remember-passphrase on).
• Before backup, an encrypt-then-decrypt self-check ensures a bad snapshot never replaces a good one; before restore, the current config is stashed to ~/.dsh/vault/stash/ (last 3 kept).
• GitHub credentials: reuses $GITHUB_TOKEN or a logged-in gh CLI; login is not this plugin's job.

Vault layout

dsh-backup-<github username>/          ← private; override with /vault set repo
└── machines/<hostname>/
    ├── snapshot.enc               ← encrypted snapshot (latest only, overwrite by design)
    └── manifest.json              ← plaintext metadata (machine / description / time / file
                                       list — no key material)

Known limitations

• file: absolute-path deps in a profile manifest (locally linked plugins) are invalid on another machine; restore warns about them and you handle those manually.
• .env and storages/ (machine-absolute paths) don't migrate; session history doesn't migrate.
• Only the latest snapshot per machine is kept (deliberate, see ADR 0003) — adding history would be a format-level change.
• Restore's plugin reinstall needs the dsh CLI and pnpm on PATH.

Development

pnpm install && pnpm build && pnpm test   # unit tests (24)
node scripts/smoke-boot.mjs               # real-host boot smoke (scratch profile)
node scripts/e2e-host.mjs                 # real GitHub round-trip (sandbox home + scratch repo)
./e2e/run-e2e.sh                          # podman container e2e (isolated ~/.dsh)

Design docs: CONTEXT.md (glossary) and docs/adr/ (backup-set boundary, encryption scheme, overwrite snapshots, single-repo multi-machine layout).