# Chapter 3 — Running seeder and booter

**Prerequisites:** [Install and repository layout](02-install-and-repository-layout.md). **Time to read:** about seven minutes.

---

## On this page

- [Why there are two processes](#why-there-are-two-processes)
- [Run with Node (quick path)](#run-with-node-quick-path)
- [Run with Pear (recommended for realistic behavior)](#run-with-pear-recommended-for-realistic-behavior)
- [Pear channels and released keys](#pear-channels-and-released-keys)
- [Common mistakes](#common-mistakes)
- [Boot sequence in plain language](#boot-sequence-in-plain-language)
- [Choosing Node versus Pear](#choosing-node-versus-pear)

---

## 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:

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

In a **second** terminal, start the booter:

```bash
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**:

```bash
npm run os:seeder
```

In another terminal:

```bash
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](../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](../handbook/07-operations-and-development.md#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](../docs/reference/environment-and-posix-appendix.md)) 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](../PEAR-RUN.md) is the channel and environment reference for Pear-specific settings.

---

_Previous: [Chapter 2](02-install-and-repository-layout.md)_ · _Next: [Chapter 4 — Shell, PATH, and scripts](04-shell-path-and-scripts.md)_