Chapter 2 — Install and repository layout

Prerequisites: Chapter 1 — What this is. Time to read: about six minutes.

What you need on the host

Node.js 20 or newer (see root package.json engines).
Git to clone the repository.
For Pear workflows: Pear CLI installed and configured on your machine. The repo’s npm run os:seeder and npm run os:booter scripts assume Pear when you use those entry points.

Continuous integration also installs Bare globally for tests that touch identity crypto; if you run the full npm test suite locally, match that setup. Details live in Handbook — Chapter 7.

Clone and install

From a terminal:

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

Run npm test when you want to confirm the tree is healthy before you change code. pretest builds coreutils and bare-libs, verifies kernel and seeder parity, and runs several contract and documentation checks. If pretest fails, the handbook’s operations chapter explains the common causes.

Monorepo layout at a glance

The repository is an npm workspace monorepo. These paths matter most when you are running or debugging Bare OS:

kernel/ — Sources that are staged onto the system Hyperdrive by the seeder. A copy is kept under packages/bare-os-seeder/kernel/ for Pear packaging; CI enforces that they stay in sync.
packages/bare-os-protocol — Shared protocol constants: swarm topic, MBR layout, Protomux identifiers, kernel feature bits.
packages/bare-os-seeder — Publishes the OS drive and joins the swarm so booters can replicate.
packages/bare-os-booter — Joins the swarm, opens system and personal drives, constructs the guest runtime, and runs /boot/init.js.
packages/bare-os-coreutils — Sources and build for /bin utilities and the merged man.json database.
packages/bare-os-bare-libs — Optional /lib/bare bundles merged into ctx.bare when enabled.
scripts/ — Automation: Pear node_modules helpers, parity verifiers, catalog generation, release checklist.

Each workspace package has its own README with package-specific commands. For a file-by-file inventory, use docs/reference — Repository layout.

Default Corestore directories for seeder and booter usually live under ~/.bare-os/ unless you override them with environment variables documented in the environment appendix.

Root npm scripts (operators)

From the repository root, the scripts you touch most often are:

npm run os:seeder — Builds coreutils and bare-libs, ensures Pear sees hoisted node_modules, then pear run --dev . inside packages/bare-os-seeder. Use when you want Pear-accurate seeding during app development.
npm run os:booter — Same Pear node_modules preparation for the booter package, then pear run --dev . in packages/bare-os-booter.
npm run pretest — Required gate before npm test: builds artifacts, runs parity and documentation verifiers (see Chapter 7).
npm test — Runs pretest, then npm run test --workspaces --if-present so every workspace package can contribute its own suite.

Maintainers also use npm run gen:bare-catalog, npm run sync:bare-manifest, and npm run release-checklist; see Handbook — Chapter 7 for workflow context.

Disk, caches, and Corestore

Seeder and booter persist Hypercore storage on disk. Default layouts are described in package READMEs and the environment appendix (BARE_OS_SEED_STORE, BARE_OS_BOOT_STORE, BARE_OS_HOST_DATA). If you switch between Node and Pear runs, you usually keep the same store paths so the personal drive and replication state stay consistent. Deleting ~/.bare-os/ is a blunt “factory reset” for local development: you lose replicated drives unless you have keys or snapshots elsewhere.

Where to go next

Run the system: Chapter 3 — Running seeder and booter.
Deeper operations and CI: Handbook — Chapter 7.
Exact env var names: Environment variables and POSIX appendix.

Previous: Chapter 1 · Next: Chapter 3 — Running seeder and booter

5.2 KiB Raw Blame History Unescape Escape