66 lines
4.1 KiB
Markdown
66 lines
4.1 KiB
Markdown
# 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](02-blueprints.md) 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:
|
|
|
|
1. **Discovery** — How does a fresh node find _someone_ who has block 0 (the MBR) and the drive root?
|
|
2. **Separation of concerns** — What is **immutable-ish OS** vs **mutable per-device home**?
|
|
3. **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** (`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
|
|
|
|
- Big picture: [Chapter 2 — Blueprints](02-blueprints.md)
|
|
- Wire protocol: [Chapter 3](03-protocol-and-disk.md)
|
|
- Day-to-day hacking: [Chapter 7](07-operations-and-development.md)
|
|
|
|
---
|
|
|
|
[← Handbook home](README.md) · [Next: Blueprints →](02-blueprints.md)
|