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.

Requires dsh >= 0.1.5-rc.2 — this plugin targets the dsh RC/stable line only (CI and releases resolve the newest of the latest/next dist-tags at runtime). The alpha line is no longer supported.

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

Configuration

All settings live under the top-level vault: section in ~/.dsh/settings.yaml — the same section /vault set writes back to:

vault:
  repo: ""                        # owner/name override; empty = default dsh-backup-<login>
  machineDescription: ""          # human label recorded in the snapshot manifest
  rememberPassphrase: false       # store the passphrase in the macOS keychain on backup

Passphrase sources, in order: inline command argument (never logged) → $DSH_VAULT_PASSPHRASE → the macOS keychain (when rememberPassphrase is on). GitHub credentials come from $GITHUB_TOKEN or a logged-in gh CLI.

The plugin ships a bundled skill (dsh-vault-config): ask the agent to configure backups or run a first backup and the guide loads automatically — it walks the choices interactively (repo, machine description, passphrase memory) and writes the vault: section for you.

Uninstall

dsh plugin --profile tui remove @aiwayds/dsh-vault

The host cleans up the profile automatically: the dsh.profile.bundles entry is spliced and the plugin's patch layer drops. This is a secrets/backup plugin, so be explicit about what outlives the removal — none of it is touched by remove:

1. The macOS Keychain item (service + account dsh-vault) holding a remembered passphrase. Turn it off before uninstalling with /vault set remember-passphrase off, or delete the item afterwards in Keychain Access.
2. The private GitHub repo dsh-backup-<login> holding your encrypted snapshots (auto-created on first backup) — delete it on GitHub if unwanted.
3. ~/.dsh/vault/stash/ — up to 3 pre-restore stashes of the full config, including .credentials.yaml (mode 0600). Purge with rm -r ~/.dsh/vault.
4. The vault: section in ~/.dsh/settings.yaml — remove the lines by hand.

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).