Chapter 3 — Running seeder and booter

Prerequisites: Install and repository layout. Time to read: about seven minutes.

Why there are two processes

The seeder owns the publisher side: it stages the kernel tree into a system Hyperdrive, writes the MBR block that points at drive keys, and stays on the swarm so others can replicate.

The booter owns the consumer side: it looks up peers on the same topic, replicates the system drive, attaches or creates a personal drive, and starts the in-image runtime (/boot/init.js, shell, initd, cron as configured).

You almost always run them as two separate processes (two terminal tabs or windows). The booter needs a live seeder (or an already-replicated drive) to make progress within its boot timeout.

Run with Node (quick path)

Run the seeder from its package directory so kernel/ resolves correctly from the repo layout:

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

In a second terminal, start the booter:

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

Default store paths are under ~/.bare-os/corestore/ for seeder and booter unless you set BARE_OS_SEED_STORE, BARE_OS_BOOT_STORE, or the shared base BARE_OS_HOST_DATA. See each package’s lib/paths.js for how overrides compose.

Run with Pear (recommended for realistic behavior)

From the repository root:

npm run os:seeder

In another terminal:

npm run os:booter

These scripts run scripts/ensure-pear-node-modules.mjs first so Pear sees hoisted workspace dependencies the same way npm ci does at the repo root. Without that step, pear run from inside a package directory can miss modules that live at the root node_modules.

Do not type pear run os:seeder — os:seeder is an npm script name, not a Pear application name.

Pear channels and released keys

After pear stage and pear release, you receive pear://… links that point at released artifacts. Consumers normally run those keys rather than a raw git checkout, unless they use dev mode (pear run --dev .).

Concrete channel names, keys, versioned links, and host-side environment variables (BARE_OS_PEAR_*, HTTP allow lists, TLS pin forwarding, ctx.bare toggles) are documented in PEAR-RUN.md. Keep that file open when you embed the booter in a Pear app or wire OTA reload hooks.

Common mistakes

Booter times out — No peer is serving the bare-os-v1 topic, or the network cannot reach bootstrap nodes. Confirm the seeder is running and check HYPERSWARM_BOOTSTRAP if you use custom bootstraps (Handbook — Chapter 7, troubleshooting).
Missing /bin utilities under Pear — Run npm run build -w bare-os-coreutils (and seed again) so the image contains a fresh /bin build.
Wrong working directory for the seeder — Start the seeder from packages/bare-os-seeder (or use the npm script from root) so kernel paths resolve.

Boot sequence in plain language

Once the booter has replicated enough of the system drive, it mounts the personal drive (creating one if needed), wires the merged VFS, and executes /boot/init.js. The stock kernel prints /etc/os-release, optional motd, runs /etc/bare-os/rc and sorted snippets under rc.d, then enters the interactive shell unless BARE_OS_SKIP_REPL or onboot lines consume the session. You do not need to memorize every phase to operate the system; when something fails during boot, enable BARE_OS_BOOT_TRACE (see environment appendix) and read the phase lines on stderr.

Choosing Node versus Pear

Node (node index.js in each package) is ideal when you are debugging protocol or seeding logic quickly and want stack traces identical to your host toolchain. Pear tracks production embedding more closely: module layout, pear run --dev, and host BARE_OS_PEAR_* toggles matter. If a bug appears only under Pear, compare with a Node run using the same Corestore paths to isolate runtime differences. PEAR-RUN.md is the channel and environment reference for Pear-specific settings.

Previous: Chapter 2 · Next: Chapter 4 — Shell, PATH, and scripts

5.0 KiB Raw Blame History Unescape Escape