bare-operating-system/handbook

Bare operating system — handbook

Bare OS is an experimental, P2P-first system image: a Merkle-addressed Hyperdrive you replicate from peers over Hyperswarm, plus a second drive for everything that should stay yours (home, identity, logs). This handbook is the narrative spine—written like a long-form technical article so you can read it cover to cover or jump to a chapter. It explains why the pieces exist, how they connect, and where to look when something breaks.

This project is experimental research software, not a production OS. It is licensed under Apache-2.0 (LICENSE).

---

How this handbook fits the repo

Doc	Role
Preface — why Bare OS	Thesis, comparison to classic images, security limits, outlook, contributor paths
This handbook (handbook/*.md)	Story, architecture, protocol, runtime, identity, POSIX surface, operations
docs/reference/README.md	File-by-file inventory, env vars, data-flow diagram
developer-guide/README.md	How to write run(ctx, argv) / start(ctx), extend /bin, test under Pear
Kernel extensions	Kernel feature bitmask, seed-channel RPC, capability bits

The ctx object is versioned for kernels and scripts that depend on booter behavior. Treat packages/bare-os-booter/CHANGELOG.md as the contract history (bareOsCtxApiVersion / BARE_OS_CTX_API_VERSION). TypeScript authors can use packages/bare-os-booter/lib/bare-os-ctx.d.ts.

---

Who should read what (three paths)

I want to run it. Start at the root README.md, then Chapter 7 — Operations (install, npm test, seeder/booter, Pear). Skim Chapter 1 for vocabulary.

I want to change the image or /bin. Read Preface → Chapter 6 → the developer guide, especially extending coreutils and the ctx object.

I want the architecture and trust model. Read Preface → Chapter 2 — Blueprints → Chapter 3 — Protocol → Chapter 4 — Booter runtime → Chapter 5 — Identity.

---

Chapters

Chapter	Topic
Preface	Whitepaper-style thesis, doc map, security limits, research directions, contributing
01 — Introduction	Goals, vocabulary, Holepunch stack, clone-to-prompt story
02 — Blueprints	Layered architecture, trust, boot-flow diagram
03 — Protocol and disk	MBR, swarm, Protomux, SwarmDisk, failure matrix
04 — The booter runtime	ctx, VFS, shell, kernel, initd, cron, REPL, host bridges
05 — Identity, vault, HDMS	Guest vs user, account blob, vault, extra drives
06 — Kernel and binaries	/boot/init.js, coreutils pipeline, /bin summary
07 — Operations and development	CI, pretest, Pear channels, env vars, troubleshooting
08 — Git on Bare OS	isomorphic-git, VFS adapter, HTTP modes
09 — POSIX utilities, shell, VFS	XCU-style /bin, shell, divergence from Issue 7
10 — Manual pages and online help	man(1), JSON DB, handbook ingest, help vs man

Pear workflows, ctx.bare, drive bundles: developer-guide ch.11 and ch.12.

---

Packages in one sentence each

• bare-os-protocol — Shared topic string, MBR layout, Protomux message IDs, and kernel feature bits used by seeder and booter.
• bare-os-seeder — Stages kernel/ into a system Hyperdrive, publishes the MBR block and joins the swarm so booters can replicate the image.
• bare-os-booter — Joins the swarm, opens system + personal drives, builds ctx, runs /boot/init.js, shell, initd, cron, and delegated tools (git, curl, wget).
• bare-os-coreutils — Sources and build for /bin utilities plus the merged man.json database.
• bare-os-bare-libs — Builds optional /lib/bare bundles merged into ctx.bare when enabled.

The staged tree also includes kernel/README.md (what lands on the system drive) and scripts/README.md (repo automation). Pear release links and host env notes: PEAR-RUN.md.

---

Root README

The top-level README.md is the short runbook (clone, npm ci, seeder/booter commands). Use it when you only need copy-paste steps.

---

License: Apache-2.0 — see LICENSE.