4.6 KiB
Chapter 5 — Home, identity, and vault
Prerequisites: Shell, PATH, and scripts. Time to read: about seven minutes.
On this page
- Guest session
- Logging in
- Vault snapshots
- HDMS and extra drives
- Where to read the full story
- Where state lives on disk (mental model)
- Passphrases, backups, and data loss
Guest session
On a fresh boot the session is guest: USER and HOME point at guest under /home/guest, and there is no Ed25519 identity material in the environment. You can still read the system image and write guest-scoped areas on the personal Hyperdrive.
Logical $HOME and /var/log map into stable prefixes on the personal drive so guest data and unlocked-user data stay separated. Shared machine metadata (/.bare/account, /.bare/hdms/, vault blobs) lives outside those per-session home prefixes.
Logging in
login prompts for a passphrase. If an account already exists at /.bare/account, the booter decrypts it and derives session keys. login --new creates a new Ed25519 keypair and writes a versioned on-disk blob.
After a successful login, HOME moves under /home/<public-key-prefix>, BARE_OS_PUBLIC_KEY is set, and optional HDMS features become available for managing extra drives. logout clears sensitive state and returns you to guest. logout --save can combine logout with vault snapshotting (see below).
Cryptographic details are implementation-specific; this manual stays at the behavior level. For prose-level crypto and flow diagrams, read Handbook — Chapter 5.
Where state lives on disk (mental model)
Think in two layers:
- Hyperdrive blocks replicated through Corestore — durable bytes identified by keys and discovery topics, not by a traditional host path.
- VFS paths — what you see in the shell (
/home/guest,/.bare/account,/mnt/...) as the booter merges drives and synthetic mounts.
Guests can write under guest HOME and read shared system content. Unlocked users get a different HOME subtree and can manipulate HDMS registry entries that survive across sessions. If you are debugging “where did my file go?”, check both pwd and whether you logged out (which clears in-memory keys even when ciphertext remains on disk).
Passphrases, backups, and data loss
login --new creates keys derived from your passphrase. If you forget the passphrase, ciphertext under /.bare/ is not recoverable by design. If you lose the personal drive replication (new machine, wiped Corestore) without exporting keys or vault snapshots, you also lose access. For operational guidance beyond this overview, read Developer guide — Security and trust and the handbook’s identity chapter.
Vault snapshots
savevault and logout --save can store encrypted snapshots of selected paths under /.bare/vault/. Vault security depends on your passphrase strength, who can replicate your personal drive, and your backup practices. Treat vault blobs as sensitive ciphertext, not as a substitute for off-machine backups if you care about durability.
HDMS and extra drives
HDMS (Hyperdrive management) lets an unlocked user register and mount additional Hyperdrives, exposed under /mnt/<label>. Guests may see mounts that are already open but cannot mutate the registry until login succeeds.
Pairing hints for operators can appear under /proc/bare_os/hdms_hints.json when the host sets BARE_OS_AUTOPASS_INVITE_URL. The guest does not open arbitrary network URLs by itself; automation on the host consumes those hints.
For subcommands and examples, use man hdms after seeding an image with a current man.json build.
Where to read the full story
- Handbook — Chapter 5: Identity, vault, and HDMS
- docs/reference — Booter package (identity-related sections)
- Developer guide — Security and trust
Previous: Chapter 4 · Next: Chapter 6 — Help, man, and documentation map