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.

Canonical refs: Compatibility matrix · Environment appendix · Protocol package reference.

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. Eligible already-booted peers can later mirror the same block 0 and seed RPC snapshots for cold joiners.

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. Once up, that booter can also help cold joiners by mirroring the same block 0 and captured seed RPC hints when eligibility passes. 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

System drive — Hyperdrive containing /boot/init.js, /bin, /etc; replicated from the seeder image.
Personal drive — Separate Hyperdrive (Corestore namespace) for $HOME, /.bare, cron, and logs.
MBR — 512 bytes: magic BIOS plus embedded Hyperdrive public keys (primary and optional failover slots).
Kernel — /boot/init.js with async function start(ctx); a session loop, not a hardware microkernel.
/bin — Small JavaScript programs (async function run(ctx, argv)) built from bare-os-coreutils, including a TTY editor (edit, nano) and usual POSIX-style tools.
VFS — Booter-provided path layer: routes paths under $HOME to the personal drive, otherwise the system drive.
ctx — Context object passed to kernel and commands: vfs, console, execLine, identity hooks, and many optional bridges.
Guest — Default session before login: predictable HOME=/home/guest, no Ed25519 identity material exposed.
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-v1 channel 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 (pear field in package.json) and can run under node index.js for 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

Experimental research software, not a production OS. Open source under Apache-2.0. Owned, operated, and engineered by HoneyPeer, LLC, a DeKalb, Georgia limited liability company — LICENSE.

6.9 KiB Raw Blame History Unescape Escape