Raven Scott
faaf5f13d8
- Add sixth capability word (bits6), STOCK_V6, FEATURE6_* in bare-os-protocol; seed caps, channel.js, seed-rpc-methods registry, replication/handshake fields - Booter: Wave 6 /proc JSON surfaces, ctx 1.15.0, Pear/DHT hooks, subprocess snapshot v3, audit v3, extension registry v3 edges, hrpc stub, worker/sandbox - Kernel: boot.policy v6 enforcement (requireFeatureBits6, booter semver, ctx min, extension deny/hash pins, offline LKG strict); example policy + seeder kernel sync - Schemas: boot.policy v6, OTel JSONL v3 + example; validate-example-schemas pairs - CI: verify-kernel-roadmap-wave6 (100 rows), verify-pear-no-static-node-import, extend wave3/compat-matrix/ctx verifiers; pretest wiring - Docs: ADR 001 v6, kernel-capabilities-index Word 6, kernel-extensions, feature-roadmap Wave 6 table, compatibility matrix, handbook ch.11, developer-guide (privacy, bare-boot alignment, bare-fetch), http-curl, scripts/README, DOCUMENTATION - Tests: booter /proc readdir expectations for new bare_os_* nodes
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 |
| 11 — Roadmap and research | Pear/Bare/holepunch context, feature waves, non-goals |
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
/binutilities plus the mergedman.jsondatabase. - bare-os-bare-libs — Builds optional
/lib/barebundles merged intoctx.barewhen 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.