Raven Scott
d286ce19b5
test(protocol): add deterministic MBR failover-key coverage docs(protocol): align package-bare-os-protocol version to 0.9.1 test(booter): add MBR corruption and wrong-topic smoke fixtures test(peer-seed): add strict pre-MBR bare_os.capabilities negotiation check feat(seeder): validate BARE_OS_SEED_REQUIRE_MBR_LABELS feat(seeder): validate BARE_OS_SEED_CAPABILITY_ATTESTATION_JSON schema docs(boot-policy): add requireProtocolPackageMin 0.9.1 example test(kernel): cover boot.policy denySeedRpcMethods behavior test(protocol): add app/cap/chat/meshdrop channel compatibility fixture test(swarm-disk): cover duplicate Protomux channel null-return path test(protocol): add 11-word kernelCapabilityWords round-trip fixture docs(schema): add mbr-layout schema and validate seeder examples test(protocol): add topicKey() golden hash fixture docs(trust): document block-0 trust assumptions in boot docs feat(seeder): add discovery.flushed readiness logging feat(booter): record peer discovery timings in boot-perf.json feat(integration): add local testnet mode to integration lab smoke test(booter): add Hyperswarm connection-budget env regression coverage test(booter): add swarm plus Corestore suspend/resume integration coverage feat(booter): mirror swarm ban events into host audit logs feat(booter): add direct-peer boot via BARE_OS_BOOT_JOIN_PEER_HEX feat(seeder): pass BARE_OS_SEED_MAX_PEERS to Hyperswarm feat(seeder): log drive.version and discoveryKey at startup test(booter): add Hyperdrive.checkout read-only boot probe coverage feat(booter): prefetch /boot/init.js before kernel handoff feat(booter): add optional /bin warm replication via downloadDiff feat(seeder): add manifestPaths SHA-256 generation in stage-kernel-tree test(peer-seed): cover helper-served block-0 after seeder exit feat(protocol): add Protomux cork batching for initial channel sends test(boot-graph): compare kernel/init labels with booter graph proc docs(boot-policy): add v9-v11 schema examples feat(release): add requireInitJsSha256 fixture generation step test(vfs): add BARE_OS_VFS_SYSTEM_RO_ALIAS coverage test(vfs): strengthen system-drive write-deny path coverage feat(identity): add personal-drive namespace export/import docs and tests test(booter): add guest-to-login warm cache invalidation regression test(vfs): add guest deny coverage for /.bare sensitive paths test(coreutils): add cross-drive mv failure injection coverage test(vfs): add .bareos_empty round-trip coverage across mkdir/rmdir/cp/git-fs test(vfs): add /dev/shm quota enforcement coverage test(proc): add /proc/bare_os/index.json sortedness and schema checks test(vfs): add warm read cache invalidation on replication growth docs(ctx): document bareOsInvalidateWarmReadCaches(reason) test(kernel): add BARE_OS_BOOT_DRY_RUN behavior coverage docs(posix): add dashboard rows for all COREUTILS_COMMANDS feat(curl): expand -w variables beyond http_code/url_effective/size_download feat(wget): mark -N timestamping as explicit unsupported error feat(curl): plumb mutual TLS cert/key intent to ctx.httpFetch metadata feat(shuf): add deterministic seed mode via BARE_OS_SHUF_SEED docs(sort): document -M month-sort as unsupported feat(grep): add explicit -E and -G mode handling test(sed): add Open Group Issue 7 golden fixtures test(awk): add getline VFS regressions for missing/repeat/boundary cases test(shell): add non-interactive here-doc coverage test(shell): add trap delivery coverage for synthetic PIDs/job IDs test(shell): add set -e compound-body behavior coverage docs(shell): strengthen read builtin opt-in guidance test(env): add Bare-runtime coverage for -S and --env-file docs(man): add examples for pathcap-verify pkg-swarm-index corestorectl test(identity): add account/vault backup-restore smoke coverage feat(audit): add tamper detection verification for audit chain rows test(peer-admission): cover strict empty allowlist deny behavior test(peer-admission): add denylist precedence over allowlist coverage test(peer-admission): add BARE_OS_PEER_REQUIRE_CAPS_JSON metadata checks docs(identity): add trusted-key rotation example for path capabilities feat(schema): tighten extensionSignerPinsV2-V4 hash validation test(delegate): add allowlist negative cases for curl/wget/git/hrpc/systemctl test(proc): extend /proc/self/environ redaction key coverage docs(security): add peer-assisted block-0 mirroring threat-model notes feat(bench): add boot budget trend output from real booter phases test(baretop): align fixture coverage with /proc snapshot key set test(metrics): validate /proc/bare_os/metrics.prom OpenMetrics shape docs(ops): add structured seeder NDJSON examples test(replication): add live stall-hint coverage for no_peers/length_unavailable/ok docs(release): add corestore-snapshot workflow to checklist docs(ops): add mirror-drive experiment utility to maintainer workflow test(booter): add monitor progress coverage for replication live sketch feat(seeder): validate DHT bootstrap address class JSON inputs docs(network): add HYPERSWARM_BOOTSTRAP testnet operator guidance chore(root): add deterministic test:integration script docs(ci): add local CI runbook for no-.github environments docs(release): add npm run test:bare after npm test feat(verify): add protocol docs/package version parity checker feat(verify): enforce feature-roadmap canonical path consistency feat(lockfile-drift): add tier-1 strict fail option for mismatches docs(lockfile-drift): add udx-native and blind-peering upgrade workflow notes docs(cli-parity): add bare-fetch upstream issue tracking row feat(bundle-health): generate per-tier bundle size regression thresholds feat(doc-contracts): verify handbook references to current proc schema versions feat(pretest): add validate-mermaid-syntax gate feat(probe): add bare-runtime top-25 critical command lane docs(protocol): update capability-word prose from bits..bits5 to current words docs(two-drive): document /tmp /var/log and account-prefix routing docs(security): add concise boot trust model page and links docs(dev-guide): add P2P lab cookbook section docs(dev-guide): add how-to for adding seed RPCs docs(dev-guide): add how-to for adding /proc/bare_os nodes docs(dev-guide): add /bin utility checklist for man/posix/build/parity/tests docs(user-manual): add short What BareOS is not section
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).
On this page
- How this handbook fits the repo
- Who should read what
- Chapters
- Packages in one sentence each
- Root README
How this handbook fits the repo
Documentation home — Single map of every tree: user manual, this handbook, developer guide, reference, concepts (evergreen), glossary, FAQ, troubleshooting router, contributing to docs.
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, and research directions.
User manual — Short operator-oriented path: clone, run seeder and booter, use the shell and identity features, find man and troubleshooting without reading cover to cover.
docs/reference/README.md — File-by-file inventory, environment variables, data-flow diagram.
docs/architecture/KERNEL_CONTRACT.md — Single-page contract: subsystems, boot steps, ctx semver, typed errors.
Boot trust model — Concise operator checklist for block-0 provenance and swarm trust boundaries.
developer-guide/README.md — How to write run(ctx, argv) / start(ctx), extend /bin, and test under Pear.
Kernel extensions — Kernel feature bitmask, seed-channel RPC, and 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 user manual or 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
- Preface — Whitepaper-style thesis, documentation 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, peer-assisted block
0mirroring, 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,/binsummary. - 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,helpvsman. - 11 — Kernel program and research — Pear/Bare/holepunch context, capability words, non-goals.
- 12 — P2P stack vs POSIX boundaries — Hypercore replication, swarm, Protomux, and how they relate to the declared POSIX profile and 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 canonical 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); eligible booted peers may mirror block0and seed RPC snapshots. - 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.