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 (~111 commands), sed/awk, shell lists and pipelines, getconf/xargs, GNU-gap text utilities, 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, Pear workflows): developer-guide/README.md — includes ch.11 — Kernel + Pear cookbook and ch.12 — Bare modules and Pear ecosystem (ctx.bare, drive bundles).
ctx API changelog: packages/bare-os-booter/CHANGELOG.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.