102 lines
6.9 KiB
Markdown
102 lines
6.9 KiB
Markdown
# Chapter 1 — Introduction: what “Bare OS” is
|
||
|
||
**Time to read:** about 8 minutes. **Prerequisites:** none; [Preface](00-preface.md) first if you want the thesis in essay form.
|
||
|
||
**Canonical refs:** [Compatibility matrix](../docs/reference/compatibility-matrix.md) · [Environment appendix](../docs/reference/environment-and-posix-appendix.md) · [Protocol package reference](../docs/reference/package-bare-os-protocol.md).
|
||
|
||
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](02-blueprints.md) will not stick.
|
||
|
||
---
|
||
|
||
## On this page
|
||
|
||
- [From git clone to a first prompt](#from-git-clone-to-a-first-prompt-story-not-a-runbook)
|
||
- [The problem this project explores](#the-problem-this-project-explores)
|
||
- [Key vocabulary](#key-vocabulary)
|
||
- [Why Hyperdrive and Hyperswarm](#why-hyperdrive-and-hyperswarm)
|
||
- [Relationship to Pear and Bare](#relationship-to-pear-and-bare)
|
||
- [Where to go next](#where-to-go-next)
|
||
|
||
---
|
||
|
||
## 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](07-operations-and-development.md) and the root [README.md](../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:
|
||
|
||
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
|
||
|
||
- **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](00-preface.md)
|
||
- 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)
|
||
|
||
---
|
||
|
||
**Next:** [Chapter 2 — Blueprints](02-blueprints.md)
|
||
|
||
**Related:** [Documentation home](../docs/README.md) · [Glossary](../docs/glossary.md) · [Handbook home](README.md) · [Kernel extensions](../docs/reference/kernel-extensions.md) · [CHANGELOG — ctx API](../packages/bare-os-booter/CHANGELOG.md)
|
||
|
||
_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](../LICENSE)._
|