6.1 KiB
Chapter 1 — Introduction: what “Bare OS” is
Time to read: about 8 minutes. Prerequisites: none; Preface first if you want the thesis in essay form.
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.
From git clone to a first prompt (story, not a runbook)
Imagine two terminals on the same machine. In one you run the seeder: it loads the kernel/ tree into a system Hyperdrive, writes a 512-byte MBR (magic BIOS, embedded public keys), and joins Hyperswarm on the project topic plus the drive’s discovery key. In the other you run the booter: it joins the topic, finds a peer, opens a Protomux channel, reads block 0, parses the MBR, opens the system drive by key, creates your personal drive, and hands off to /boot/init.js. You see a line prompt; everything “POSIX” after that is the booter’s VFS and shell simulating a machine.
Exact commands, env vars, and Pear workflows live in Chapter 7 — Operations and the root README.md. This paragraph is only the narrative spine.
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 — includes a TTY editor (edit, nano) and usual POSIX-style tools |
| 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 |
Holepunch stack (first-use definitions)
Use these names consistently across docs:
- Hyperdrive — Append-only, sparse-friendly filesystem identified by a public key; good for a shared OS tree.
- Hyperswarm — DHT-style peer discovery; Bare OS uses a topic (
bare-os-v1) and drive discovery keys. - Protomux — Multiplexes logical channels on one encrypted stream; the
bare-os-v1channel carries MBR reads and replication. - Corestore — Storage backend that holds Hyperdrive cores; seeder and booter use separate store paths.
- Bare — Minimal JavaScript runtime; Pear wraps Bare for distributable apps (the seeder and booter are Pear apps).
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
- Essay-length thesis: Preface
- Big picture: Chapter 2 — Blueprints
- Wire protocol: Chapter 3
- Day-to-day hacking: Chapter 7
Next: Chapter 2 — Blueprints
Related: Handbook home · Kernel extensions · CHANGELOG — ctx API
Experimental research software, not a production OS. Apache-2.0 — LICENSE.