4.1 KiB
Chapter 1 — Introduction: what “Bare OS” is
If you have only a minute: Bare operating system is a tiny Unix-flavored environment whose root filesystem is a Hyperdrive replicated from peers. A seeder publishes that drive and a 512-byte MBR over Hyperswarm; a booter joins the swarm, downloads the image, mounts a second Hyperdrive for per-user mutable state, and runs JavaScript “kernel” and /bin scripts inside a Bare or Node runtime.
The rest of this chapter sets vocabulary straight—without it, the architecture diagrams in Chapter 2 will not stick.
The problem this project explores
Traditional OS images live on block devices or tarball layers. Here, the image is a Merkle tree you can address by key and replicate live. Peers do not hand you a .iso; they help you fill in the same Hyperdrive from the same discovery key.
That raises three design questions this repo answers in code:
- Discovery — How does a fresh node find someone who has block 0 (the MBR) and the drive root?
- Separation of concerns — What is immutable-ish OS vs mutable per-device home?
- Execution model — What runs in the host process vs what is “inside” the simulated POSIX surface?
Bare OS picks: one swarm topic for the project, Protomux channels for control + replication, two Hyperdrives (system + personal), and AsyncFunction-loaded JS for kernel and utilities.
Key vocabulary
| Term | Meaning here |
|---|---|
| System drive | Hyperdrive containing /boot/init.js, /bin, /etc — replicated from the seeder image |
| Personal drive | Separate Hyperdrive (Corestore namespace) for $HOME, /.bare, cron, logs |
| MBR | 512 bytes: magic BIOS + embedded Hyperdrive public keys (primary + optional failover) |
| Kernel | /boot/init.js — async function start(ctx); not a microkernel, a session loop |
| /bin | Small JS programs (async function run(ctx, argv)) built from bare-os-coreutils |
| VFS | Booter-provided path layer: routes paths under $HOME to the personal drive, else system |
| ctx | Context object passed to kernel and commands: vfs, console, execLine, identity hooks, etc. |
| Guest | Default session before login — predictable HOME=/home/guest, no Ed25519 identity |
| HDMS | “Hyperdrive management” — optional extra drives mounted under /mnt after unlock |
Why Hyperdrive and Hyperswarm
Hyperdrive gives you a single-writer (per key) log-backed filesystem with deterministic reads and sparse replication—good for an OS tree that many nodes can share.
Hyperswarm gives you topic-based and discovery-key-based peer finding. The seeder joins both the bare-os-v1 topic (so booters find some peer) and the drive discovery key (so Hyperdrive replication completes).
You do not need to agree with every product choice to read the code: the handbook describes what the repo does, not whether it is the only way to build a P2P OS.
Relationship to Pear and Bare
- Bare is a minimal JavaScript runtime used by Pear apps.
- Both seeder and booter are Pear applications (
pearfield inpackage.json) and can run undernode index.jsfor development. - brittle-bare vs brittle-node split in tests reflects native addons (e.g. identity crypto) that only load on Bare.
Where to go next
- Big picture: Chapter 2 — Blueprints
- Wire protocol: Chapter 3
- Day-to-day hacking: Chapter 7