Bare operating system — handbook
Welcome. This handbook is the narrative companion to the repo: it explains why the pieces exist, how they connect, and what to run when things go wrong. For an exhaustive file-by-file inventory, keep DOCUMENTATION.md open alongside—it is the closest thing to a generated map of every source path.
This project is experimental research software: a distributed system image living in Hyperdrive, discovered over Hyperswarm, executed by Bare/Pear apps. It is not a production OS.
Who this is for
- You want a mental model of seeder vs booter vs kernel vs
/bin. - You need diagrams of data flow and trust boundaries.
- You are extending coreutils, VFS, identity, HDMS, or initd services.
Reading order
| Chapter | Topic |
|---|---|
| 01 — Introduction | Goals, vocabulary, Holepunch stack |
| 02 — Blueprints | Layered architecture, trust, diagrams |
| 03 — Protocol and disk | MBR, swarm, Protomux, SwarmDisk |
| 04 — The booter runtime | ctx, VFS, shell, kernel runner, initd, cron, REPL |
| 05 — Identity, vault, HDMS | Guest vs user, /.bare/account, extra drives |
| 06 — Kernel and binaries | /boot/init.js, coreutils catalog |
| 07 — Operations and development | Env vars, npm scripts, CI, Pear, troubleshooting |
| 08 — Git on Bare OS | isomorphic-git, VFS fs adapter, HTTP modes |
| 09 — POSIX utilities, shell, VFS | XCU-style /bin, sed/awk, builtins, mkdir, stubs, divergence from Issue 7 |
| 10 — Manual pages and online help | man(1), /share/man/man.json, schema, build, relationship to help |
Companion — developer guide (how to write run(ctx, argv) / start(ctx), extend /bin, testing): developer-guide/README.md.
Package READMEs (quick links)
Root README
The top-level README.md is the short runbook (install, test, pear run, guest identity). Start there if you only need commands.
License: Apache-2.0 — see LICENSE.