A P2P-first system image: the OS lives in a Hyperdrive that peers replicate from the swarm (Hyperswarm + Protomux), not from a single HTTP mirror. A Bare/Pear seeder stages the kernel and /bin straight from the repo into the drive; a booter discovers peers, reads the MBR, opens the system drive, and runs /boot/init.js. A separate personal Hyperdrive holds per-node state (identity, history, vault). The stack is built for decentralized distribution of the image alongside Holepunch-style runtimes.

This project is experimental research software, not a production OS.

What you get

Two-drive model — read-only system image + writable personal namespace; VFS routes $HOME and /.bare/ to the personal drive.
Tier-1 /bin — ~113 POSIX-oriented utilities, line shell with pipelines and redirects, sed/awk, man backed by a merged JSON handbook + coreutils pages.
Identity — Ed25519 account on the personal drive, guest vs unlocked session, encrypted vault snapshot (savevault / logout --save).
Boot plumbing — initd/cron themes, synthetic /proc / /run / /sys, optional ctx.bare bundles from /lib/bare (Holepunch catalog workflow at repo root).
Protocol — Swarm topic + Protomux bare-os-v1, 512-byte MBR with Hyperdrive keys (BIOS magic). Details: handbook chapter 3 and protocol reference.

Documentation

Start here: Documentation home — role-based map of every tree (user manual, handbook, developer guide, reference), including an architecture snapshot diagram for the swarm → booter → image path.

On this page: User manual · Handbook · Developer guide · Reference and contracts · Glossary and help · POSIX surface

User manual

Start here if you want to run and use Bare OS without reading the full architecture first: users-manual/README.md. It covers install, seeder and booter, shell basics, identity and vault at a practical level, man / help, troubleshooting, and links into deeper docs.

Handbook

The handbook is the narrative spine—why the system is shaped this way, how the protocol and booter fit together, and what to expect from POSIX-like behavior. Begin with the Preface for thesis and contributor paths, or jump to Chapter 7 — Operations when you only care about CI, Pear, and env vars.

Developer guide

The developer guide is the how-to for start(ctx) / run(ctx, argv), extending /bin, testing, Pear integration, telemetry scrubbing, and security boundaries.

Reference and contracts

Documentation hub — full navigation map, themes, Holepunch catalog, ADRs, release checklist.
File-level reference — package paths, environment appendix, data-flow diagram (legacy map: DOCUMENTATION.md).
ctx API changelog — bareOsCtxApiVersion history for kernels and scripts that depend on booter behavior.
Compatibility matrix — protocol, feature-bits doc, ctx API, and telemetry schema versions in one place.

Glossary and help

Glossary — canonical definitions used across all trees.
FAQ — cross-cutting questions with pointers to deep docs.
Troubleshooting — symptom → doc router.
Contributing to docs — style, Mermaid, link checks, terminology rules.

POSIX surface

Intentional coverage and gaps for utilities, shell, and VFS: handbook — Chapter 9. Machine-readable summary: docs/reference/posix-compliance-matrix.json (verified in pretest).

Quick start

git clone https://git.ssh.surf/snxraven/bare-operating-system.git
cd bare-operating-system
npm ci

Seeder (publishes the drive + MBR; run from repo root so kernel/ resolves):

cd packages/bare-os-seeder && node index.js

Booter (joins the swarm, boots the image — use another terminal):

cd packages/bare-os-booter && node index.js

With Pear installed, from the repo root: npm run os:seeder and npm run os:booter link workspace node_modules then pear run --dev each app. Full operations, env vars, and troubleshooting: handbook ch.7 and environment reference.

Protocol snapshot

Swarm topic — crypto.hash(b4a.from('bare-os-v1'))
Protomux channel name — bare-os-v1
MBR — 512 bytes, magic BIOS, primary Hyperdrive key at byte offset 8, failover keys at offsets 40 and 72

Full wire layout and replication behavior: handbook — Chapter 3 and protocol package reference.

Guest identity (short)

Default session is guest; login / logout, /.bare/account, guest /.bare read policy, legacy-root migration (BARE_OS_PERSONAL_ROOT_MIGRATE), and optional BARE_OS_PERSONAL_ACCT_PREFIX are documented in the booter reference (§§12.8–12.9), environment appendix, and handbook ch.4.

Contributing / CI

Root npm test runs scripts/verify-kernel-seeder-parity.mjs, scripts/verify-pear-no-static-node-import.mjs (no bare fs/path imports in booter/seeder sources), and scripts/verify-ctx-api-feature-bits.mjs (after workspace builds) so kernel/ stays mirrored in the seeder package and bareOsCtxApiVersion stays aligned with advertised kernel feature bits. See scripts/README.md.

Observability (host env)

Optional guest paths BARE_OS_TELEMETRY_NDJSON and BARE_OS_TELEMETRY_OTEL_JSONL append capped JSON lines for boot and var-log mirrors (lifecycleSchemaVersion / telemetrySchemaVersion 3). Coalesced session metrics are available at /proc/bare_os/metrics_live.json (poll interval BARE_OS_PROC_POLL_MS). Dev-only BARE_OS_DIAGNOSTICS_SUBSCRIBE=1 enables ctx.bareOsDiagnosticsSubscribe for structured booter diagnostics. Details: kernel extensions, environment appendix, JSON Schemas.

License

Apache-2.0 — see LICENSE.

README.md Unescape Escape

Bare operating system