bare-operating-system

Distributed system image in Hyperdrive, discovered over Hyperswarm, with a Bare-first Pear app split into a seeder (publishes the OS drive + MBR) and a booter (joins the swarm, replicates the drive, runs the kernel from /boot/init.js). Mutable per-node state lives on a separate personal Hyperdrive. No host temp directories are used for OS staging or runtime file trees—kernel and /bin files are read from the repo straight into Hyperdrive during seeding.

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

Full codebase reference (every first-party file, protocols, env vars, tests): DOCUMENTATION.md.

Handbook (narrative architecture, diagrams, operations): handbook/README.md. POSIX-style /bin, sed/awk, shell builtins, and intentional gaps: handbook/09-posix-utilities-shell-and-vfs.md.

Developer guide (in-image scripting, ctx, extending coreutils, host vs Hyperdrive code): developer-guide/README.md.

Repository layout

Path	Role
kernel/	Source tree mirrored into the system drive (/boot/init.js, /bin/*, /etc/*)
packages/bare-os-protocol	bare-os-v1 topic, MBR layout, Protomux seed channel helper
packages/bare-os-seeder	Pear app: stage kernel → Hyperdrive, serve MBR block 0, replicate
packages/bare-os-booter	Pear app: peer discovery, MBR, replicate system drive, run kernel
handbook/	Human-readable system handbook (chapters + diagrams)
developer-guide/	How to develop scripts and utilities inside Bare OS vs host Pear packages
kernel/README.md	Staged system image tree
scripts/README.md	Pear node_modules helper

Prerequisites

• Node.js 20+ for installs and tests (npm ci, npm test).
• Bare / Pear for running the apps as intended in production: install Pear per Holepunch docs and use pear run (or bare on the package main).

Install

cd /Users/raven/dev/bare-operating-system
npm ci

Tests

npm test

Runs workspace tests (brittle-node / brittle-bare where configured).

Running locally (Node / data dirs, no temp)

1. Seeder (from repo root so kernel/ resolves):

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

   Optional:

   • BARE_OS_KERNEL_ROOT — absolute path to a kernel tree (defaults to repo kernel/).
   • BARE_OS_SEED_STORE — Corestore directory (default ./data/corestore-seeder).

2. Booter (another terminal):

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

   Optional:

   • BARE_OS_BOOT_TIMEOUT_MS — max ms for peer discovery + loading the kernel from the network (default 60000). The booter does not fall back to a local seed; run the seeder on the same topic.
   • BARE_OS_NO_SPLASH=1 — disable the TTY boot splash.
   • BARE_OS_SKIP_REPL=1 — non-interactive kernel (CI / automation).

Corestore defaults (repo root, not temp dirs): data/corestore-seeder and data/corestore-booter (gitignored). Paths resolve from the monorepo root so you can run node index.js from either app package.

Guest session and identity

The booter starts as guest (USER=guest, HOME=/home/guest, empty BARE_OS_PUBLIC_KEY). Your personal Hyperdrive holds /.bare/account: an Ed25519 public key and passphrase-encrypted private key material (bare-crypto: PBKDF2-SHA256 + ChaCha20-Poly1305; see DOCUMENTATION.md §12.8).

• login --new <passphrase> — create an account and unlock (writes /.bare/account).
• login <passphrase> — unlock an existing account (/bin/login or the shell builtin).
• logout — zero the secret key and return to guest; logout --save first runs the same encrypted vault snapshot as savevault (files under the personal drive copied into /.bare/vault/, excluding /.bare, bin, boot, and REPL history paths).

See DOCUMENTATION.md §12 for module layout (identity-account.js, identity-session.js).

pear:// addresses (after staging)

Distribution uses Pear’s Hyperdrive staging. After you run pear stage (and optionally pear release) in each app package, Pear prints a link of the form:

pear://[<fork>.<length>.]<key>[.<dhash>]<path>?…

Replace the placeholders below with the keys from your own staging output:

App	Placeholder
Seeder	pear://<YOUR_SEEDER_KEY>
Booter	pear://<YOUR_BOOTER_KEY>

Example dev workflow (with Pear CLI installed) — from the repository root:

npm run os:seeder   # build coreutils → vendored kernel/bin, then pear run --dev seeder
npm run os:booter   # links workspace node_modules for Pear, then pear run --dev booter

These are npm scripts. Do not run pear run os:seeder: pear run only accepts a pear://… link or an app path (such as .), and os:seeder is neither, which triggers ERR_INVALID_LINK.

From inside a package you can run Pear directly:

node scripts/ensure-pear-node-modules.mjs packages/bare-os-seeder && cd packages/bare-os-seeder && pear run --dev .
node scripts/ensure-pear-node-modules.mjs packages/bare-os-booter && cd packages/bare-os-booter && pear run --dev .

Protocol

• Swarm topic: crypto.hash(b4a.from('bare-os-v1')) (distinct from legacy swarm-nodeos-v3).
• Protomux protocol name: bare-os-v1.
• MBR: 512 bytes, magic BIOS, primary Hyperdrive key at offset 8, optional failover keys at 40 and 72.

License

Apache-2.0 — see LICENSE.