bare-os-hdms Skill

When to use

Use when the user asks about HDMS (Hyperdrive Management): hdms CLI, /.bare/hdms/registry.json, **/mnt/<label>** mounts, invite/pair sharing, ctx.runHdms, ctx.bareOsSubscribeHdmsLifecycle, or how HDMS relates to login / guest mode.

Prerequisites

HDMS activates after identity unlock. Guest sessions can list mounts that are already open; mutating commands (create, add, registry edits, invite, pair, etc.) go through assertLoggedIn: require **ctx.identity.state === 'unlocked'** and an active HDMS controller.
Implementation: packages/bare-os-booter/lib/hdms-manager.js (runHdmsCli, HdmsController), exposed as ctx.runHdms(argv) in packages/bare-os-booter/index.js.

Registry and VFS

Registry path (constant): /.bare/hdms/registry.json on the personal drive (HDMS_REGISTRY_PATH).
Writable mounts: hdms create <label> — new Corestore namespace + Hyperdrive, replicate to swarm.
Read-only by key: hdms add <label> <z32-key> — open an existing drive by key string.
VFS: paths /mnt/<label>/…; writable mounts allow put on those routes.
www label: A mount labeled www at /mnt/www also routes $HOME/.www and /home/<active>/.www in the VFS—the same docroot the stock bare-os-www initd serves by default. See handbook/05-identity-vault-and-hdms.md and handbook/04-the-booter-runtime.md § bare-os-www.

Invite and pair (Autopass / BlindPairing)

High-level behavior (details and caveats in handbook/05-identity-vault-and-hdms.md):

Invite with a drive: hdms invite [--read-only] <label> stores a pending share for the peer. --rw uses a separate Autopass key (pending-share-rw) with signerKey + writerSecretHex so peers do not silently mount read-only when read/write was intended. Anyone who can read the paired Autopass ledger can write the drive — treat --rw as highly sensitive.
hdms invite --read-only on a writable label sets the peer’s Autopass writer row read-only; read-only Autobase writers are not append-capable, so **invite --read-only + pair often fails** with “Not writable” / timeout — for normal HDMS pairing, omit --read-only unless you understand the limitation.
Pair: hdms pair [--persist|--no-persist] <invite> — bounded waits (BARE_OS_HDMS_PAIR_WAIT_MS, BARE_OS_HDMS_PAIR_READY_MS, BARE_OS_HDMS_PAIR_SHARE_WAIT_MS, BARE_OS_HDMS_INVITE_CLEAR_MS — see env appendix / booter). Default persists to registry; --no-persist keeps the mount ephemeral. Inviter must stay online with matching Hyperswarm bootstrap or pairing stalls.
Invite without a label: hdms invite (optional --read-only) only pairs Autopass; pending drive offers are cleared — no automatic /mnt mount for the peer.

Kernel hooks

ctx.bareOsSubscribeHdmsLifecycle(fn) — callback with { kind: 'afterActivate' | 'beforeDeactivate', labels?: string[] } so /boot/init.js can refresh mount-dependent state without forking HDMS.
Stock booter also calls onAfterActivate on the hdms module export when present (see developer-guide/11-kernel-pear-cookbook.md).
After applyUnlockedEnv, the booter’s onIdentityUnlocked path (packages/bare-os-booter/index.js) activates Corestore, swarm, the personal drive, and HDMS with the mount map. Custom /boot/init.js may assign ctx.onIdentityUnlocked for extra post-login hooks (see handbook/05-identity-vault-and-hdms.md).

Execution steps (for the agent)

If the user is guest, explain that mutations require login / login --new first; hdms list may still work for existing mounts.
For subcommands and flags, prefer read_man_page hdms when available; otherwise cite handbook/05-identity-vault-and-hdms.md and packages/bare-os-booter/lib/hdms-manager.js.
For pairing failures, check timeout env vars, bootstrap connectivity, and whether --read-only was used inappropriately on invites.

Constraints

Read-only unless the user explicitly asks to run hdms mutating commands and policy allows.
Do not promise cross-runtime behavior beyond what runHdmsCli and Autopass/Hyperdrive versions in this repo implement.
Treat writer secrets and z32 invite tokens as secrets; do not echo them into logs or chat in full.

4.8 KiB Raw Blame History Unescape Escape