Bare operating system

Caution

Experimental research software — not a production OS. Peers, keys, vault data, and network exposure deserve the same caution you would give any crypto-heavy prototype.

Bare OS is a P2P-first system image: the operating tree lives on a Hyperdrive replicated over Hyperswarm and Protomux, not a single HTTP mirror. A seeder stages the kernel and /bin into the system drive and publishes the MBR; a booter discovers peers, replicates the image, attaches a personal drive for identity and mutable state, and runs /boot/init.js. The stack targets decentralized distribution alongside Holepunch-style runtimes (Bare / Pear).

New here? Read Get started (one page: clone → two terminals → what “success” looks like), then skim Concepts — Two drives.

Prerequisites (before first run)

• Node.js ≥ 20 and npm ci at the repository root.
• Pear CLI for npm run os:seeder / npm run os:booter (recommended). Install from the Pear documentation; confirm with pear --version. For a Node-only loop, see User manual — Chapter 3.
• Network: the booter must find a peer on the bare-os-v1 swarm topic within BARE_OS_BOOT_TIMEOUT_MS (default 60000 ms).

Canonical remote: https://git.ssh.surf/snxraven/bare-operating-system.git

60-second mental model

• System drive — replicated image: /boot, /bin, stock kernel, read-only policy for most tree.
• Personal drive — $HOME, /.bare, vault material, per-node history.
• Dev workflow — almost always two processes: seeder (publisher) + booter (consumer) in two terminals.
• Two runtimes — the host (Node / Pear) implements ctx and the VFS; scripts on the drive run under the in-image eval model (not Node ESM on-disk). See Developer guide §1 — Two runtimes.

Try it

To boot a published Pear app without cloning this repository:

npm i pear -g
pear run pear://xc5xw4odfpd7txd1b3xr4u37rfpbjoqtb6zp3xxutgbbmrbtogio

From this repository:

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

Terminal A — seeder (publishes the drive + MBR; npm run os:* uses Pear):

npm run os:seeder

Terminal B — booter:

npm run os:booter

Tip

npm run os:seeder and npm run os:booter run pear run --dev after linking hoisted workspace dependencies.

Tip

For a Node-only path (no Pear), see User manual — Chapter 3.

Full operations, environment variables, and troubleshooting: Handbook — Chapter 7 and Environment appendix.

Documentation

Start here	Role
Get started	Zero-to-prompt path with prerequisites and failure table
Documentation home	Role-based map, contract spine, POSIX + P2P dashboard
Documentation sitemap	How user manual, handbook, developer guide, and reference fit together
Concepts	Short evergreen pages: two drives, boot, swarm, identity, POSIX stance

Legacy router: DOCUMENTATION.md maps the old monolith sections to docs/reference/.

On this page: What you get · User manual · Handbook · Developer guide · Reference · POSIX surface · Protocol · Kernel parity · Contributing

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 — 150 POSIX-oriented utilities (authoritative list: COREUTILS_COMMANDS in packages/bare-os-coreutils/lib/commands.mjs; verify-man-coverage in pretest keeps man.json in sync), line shell with pipelines and redirects, sed/awk, man backed by 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).
• SSH in the booter — Initd unit bare-openssh runs an SSH-2 server (bare-ssh2, vendored in packages/bare-os-openssh) bound to 127.0.0.1 by default; /bin/sshd delegates to ctx.bareOsRunSshdCli. Host keys live on the personal drive under ~/.config/bare-os/ssh/host/ (see man sshd / sshd_config). Set BARE_OS_SSH_BIND_ALL=1 on the host to widen ListenAddress when sshd_config still says 127.0.0.1; use BARE_OS_SSH_LISTEN_PORT to override the listen port (including 0 for an ephemeral port in tests).
• Protocol — Swarm topic + Protomux bare-os-v1, 512-byte MBR with Hyperdrive keys (BIOS magic). Details: Handbook — Chapter 3 and Protocol reference.

Verifier-backed docs: root npm test runs pretest, which checks kernel/seeder parity, doc links, man coverage, POSIX profile triplet, compatibility-matrix strings, and more — see scripts/README.md.

User manual

For run and use without reading full architecture first: users-manual/README.md — install, seeder and booter, shell, identity, man / help, troubleshooting.

Handbook

Narrative spine — why the system is shaped this way: handbook/README.md. Begin with Preface or Chapter 7 — Operations for CI and Pear.

Developer guide

How-to for start(ctx) / run(ctx, argv), extending /bin, testing, Pear, telemetry scrubbing: developer-guide/README.md.

Reference and contracts

• File-level reference — packages, environment appendix, data flow (legacy map: DOCUMENTATION.md).
• ctx API changelog — bareOsCtxApiVersion history.
• Compatibility matrix — protocol, feature-bits doc, ctx API, lifecycle/telemetry schema versions.

Glossary and help

Glossary · FAQ · Troubleshooting · Contributing to docs

POSIX surface

Handbook — Chapter 9. Declared profile 1.0.19 (BARE_OS_POSIX_PROFILE_VERSION) with ctx API 1.54.0 — POSIX declared profile and compatibility matrix. Machine-readable: docs/reference/posix-compliance-matrix.json (verified in pretest).

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: 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: booter reference, environment appendix, Handbook — Chapter 4.

Kernel image and Pear seeder parity

Canonical tree: kernel/; packages/bare-os-seeder/kernel/ must stay byte-identical.

• Full maintainer rebuild: npm run maintainer:kernel-image
• Sync only: npm run maintainer:sync-kernel-seeder (or …:bundle to re-bundle /boot/init.js first)

Details: Handbook — Chapter 7.

Contributing / CI

Root npm test runs workspace tests plus pretest hooks (kernel/seeder parity, verify-ctx-api-feature-bits, Pear import policy, doc link and contract checks). Maintainer script inventory: scripts/README.md.

Before a release tag, run npm run release-checklist (scripts/release-checklist.mjs) — see docs/release-checklist.md.

Observability (host env)

Optional guest paths BARE_OS_TELEMETRY_NDJSON and BARE_OS_TELEMETRY_OTEL_JSONL append capped JSON lines; records carry lifecycleSchemaVersion and telemetrySchemaVersion aligned with stock BARE_OS_LIFECYCLE_SCHEMA_VERSION (see compatibility matrix and environment appendix). Coalesced metrics: /proc/bare_os/metrics_live.json (poll BARE_OS_PROC_POLL_MS). Dev-only BARE_OS_DIAGNOSTICS_SUBSCRIBE=1 enables ctx.bareOsDiagnosticsSubscribe. Kernel extensions · JSON Schemas.

License

Apache-2.0 — see LICENSE.