Raven Scott
9dcfaa8b1d
alias matrix, verify-naming-alias-matrix in pretest - Canonical bareOsRegisterBootStepHook / Invoke / EmitBareBootStepHint with legacy *Phase* wrappers; typings, runtime caps, docs, CHANGELOG - VFS: evaluateBareOsVfsPathPolicy; rename hypercore-pack proc locals; add /proc/bare_os/security_posture.json - Stock kernel: invokeCtxBootHooks, boot txn journal transactionState, extension cycle extId diagnostics, boot snapshot schema 2 + provenance - Offline LKG: BARE_OS_OFFLINE_LKG_ACTIVE / REASON env hints - Protocol: BARE_OS_PROTOMUX_CHANNEL_SCHEMA_VERSION re-exported from channel.js - Stubs: corestore suspend/resume register, swarm snapshot, extension resolver, initd state enum; shell split note; benchmark/SDK script placeholders - Docs: ota-channels, conformance-dashboard, kernel-extensions specs index, data README; handbook/developer-guide/users-manual cross-links - Sync packages/bare-os-seeder/kernel with kernel/init.js and STRUCTURE.md
Bare OS — user manual
This manual is for people who want to run and use Bare OS: clone the repo, start a seeder and booter, work in the shell, and understand where your files and identity live. It is written in plain language and points to deeper material when you need it.
Bare OS is experimental research software, not a production operating system. It is licensed under Apache-2.0 (LICENSE).
On this page
Who should read this
You are in the right place if you want to:
- understand what Bare OS is without reading the full architecture story first;
- install dependencies, run the seeder and booter, and know which terminal does what;
- use the line shell, home directory, and guest versus logged-in sessions at a practical level;
- find
manpages and know where handbook, developer guide, and reference docs live.
If you are changing /bin, the booter, or the kernel image, use the developer guide after skimming this manual.
Three paths through the docs
I only want to try it. Read What this is, then Running seeder and booter, using the root README for the shortest copy-paste path.
I use it regularly. Add Shell, PATH, and scripts, Home, identity, and vault, and Help, man, and the documentation map.
I need to debug or operate it. Use Troubleshooting and operations and the handbook chapter on operations (Chapter 7 — Operations and development).
Chapters
- What this is — P2P image, two drives, why it exists, experimental status.
- Install and repository layout — clone,
npm ci, workspaces at a glance. - Running seeder and booter — Node versus Pear, two terminals, npm scripts.
- Shell, PATH, and scripts — how commands run without diving into the full
ctxAPI. - Home, identity, and vault — guest session,
login, vault snapshots, HDMS in brief. - Help, man, and the documentation map —
man,help, and where each doc tree fits. - Troubleshooting and operations — common failures, environment variables, where to read next.
- Further reading — curated links into the handbook and reference.
How this relates to other documentation
- Handbook tells the story: architecture, protocol, booter runtime, identity, POSIX surface, and roadmap. Start with the Preface if you want the full narrative.
- Developer guide explains how to build and extend software on the image:
run(ctx, argv), coreutils, testing, Pear integration. - docs/reference is the file-level reference: packages, environment variables, data flow, compatibility. Use it when you need exact paths or toggles.
- PEAR-RUN.md lists Pear channels, versioned
pear://links, and host environment notes for embedded Pear apps.
When this manual and another doc disagree on a detail, treat the handbook or reference as authoritative and open an issue if something is stale.
Quick glossary
These terms appear everywhere in the other trees; definitions here are practical, not formal specs.
- Hyperdrive — Content-addressed append-only log exposed as a familiar file tree; Bare OS stages the system image on one drive and keeps personal state on another.
- Seeder — Process that publishes the system drive (and MBR) to Hyperswarm so peers can replicate.
- Booter — Process that joins the swarm, opens drives, builds the guest VFS, and runs
/boot/init.js. - MBR — Small bootstrap block on the system drive that records discovery keys and version hints for the protocol; not a PC BIOS MBR.
- Guest — Unauthenticated session: safe default
HOME, no Ed25519 identity in the environment. ctx— The in-image capability object (VFS, env, subprocess helpers, optional Pear bridges). User manual mentions it lightly; the developer guide is the full map.
Validating what you read
Repository CI runs npm run pretest before tests: it checks kernel/seeder parity, capability contracts, relative .md links under docs/, handbook/, developer-guide/, scripts/, users-manual/, packages/, kernel/, and root README.md, DOCUMENTATION.md, PEAR-RUN.md, man coverage, compatibility-matrix strings, and more. The link checker skips packages/bare-os-seeder/kernel/** (a byte-identical copy of kernel/**) and the packages/bare-os-bare-libs/README.kernel-lib-bare.md template whose links are validated after copy into kernel/lib/bare/README.md. If you are about to trust a path or script name from the docs, grepping the repo or running pretest locally is the fastest sanity check.
Next: Chapter 1 — What this is