56 lines
3.1 KiB
Markdown
56 lines
3.1 KiB
Markdown
# bare-os-seeder
|
||
|
||
**Pear / Bare application** that owns the **canonical system Hyperdrive**: it walks a kernel tree on disk, writes `/boot/init.js`, `/bin/*`, `/etc/*` into the drive (no host temp dirs), builds a **512-byte MBR** with the drive key, joins **Hyperswarm** on `bare-os-v1`, and serves MBR block reads + **Protomux** `bare-os-v1` replication to peers.
|
||
|
||
**When to use:** run the seeder when you want to **publish** the canonical system image for booters to replicate (typical dev: one terminal with **`npm run os:seeder`**). Eligible already-booted peers can later mirror block `0`, but the seeder remains the trust anchor for initial publication.
|
||
|
||
**Documentation:** [Concepts — Boot](../../docs/concepts/boot-and-init-timeline.md) · [Seeder reference](../../docs/reference/package-bare-os-seeder.md) · [User manual ch.3](../../users-manual/03-running-seeder-and-booter.md) · [Protocol reference](../../docs/reference/package-bare-os-protocol.md).
|
||
|
||
## Run
|
||
|
||
From package directory (after `npm ci` at repo root):
|
||
|
||
```bash
|
||
node index.js
|
||
```
|
||
|
||
Or with Bare/Pear:
|
||
|
||
```bash
|
||
npm run pear:dev
|
||
```
|
||
|
||
From **repo root** (recommended — fixes workspace `node_modules` for Pear):
|
||
|
||
```bash
|
||
npm run os:seeder
|
||
```
|
||
|
||
## Environment
|
||
|
||
- **`BARE_OS_KERNEL_ROOT`** — Absolute path to kernel tree to stage (default: package `kernel/` vendored copy, or repo `kernel/` under Node `file:` URL)
|
||
- **`BARE_OS_HOST_DATA`** — Base directory for host state (default `~/.bare-os`)
|
||
- **`BARE_OS_SEED_STORE`** — Corestore directory (default `~/.bare-os/corestore/seeder`)
|
||
- **`BARE_OS_SEED_CAPABILITY_ATTESTATION_JSON`** — Optional JSON string for seed RPC **`bare_os.capability_attestation`** (operators verify on host; guest does not crypto-verify)
|
||
|
||
## Pear vs Node
|
||
|
||
- **`import.meta.url` is `file:`** — seeder may **dynamically import** `bare-os-coreutils/build.mjs` and **`bare-os-bare-libs/build.mjs`**, rebuilding `/bin` and **`kernel/lib/bare`** before staging.
|
||
- **`pear:` bundle** — coreutils and **`/lib/bare`** bundles must be **pre-built** into `kernel/`; run `npm run build -w bare-os-coreutils` and `npm run build -w bare-os-bare-libs` before `pear run` (root **`npm run os:seeder`** does both).
|
||
|
||
## Layout
|
||
|
||
- **`index.js`** — Entry: Corestore, Hyperdrive, `stageKernelTree`, swarm, `setupSeedChannel` (RPCs include optional **`bare_os.snapshot_hints`** and **`bare_os.peer_firewall_stats`** when implemented)
|
||
- **`lib/paths.js`** — `packageRootDir`, kernel root, Corestore path (Pear RTI–aware)
|
||
- **`kernel/`** — Vendored mirror of repo `kernel/` for Pear staging — must match **`kernel/`** byte-for-byte (`npm test` **`pretest`** runs `scripts/verify-kernel-seeder-parity.mjs`)
|
||
|
||
## Dependencies
|
||
|
||
`bare-os-protocol` (workspace), `hyperdrive` **13.3.3**, `corestore` **7.12** (ctor **`treeCache`** via **`lib/corestore-opts.js`**), `hyperswarm`, `protomux` **3.11**, `b4a`, `compact-encoding` **3**, `safety-catch`, `bare-os` **3.9**, `bare-fs` **4.8**, `bare-subprocess` **6**.
|
||
|
||
## See also
|
||
|
||
- [bare-os-protocol](../bare-os-protocol/README.md)
|
||
- [Handbook — Seeder path](../../handbook/03-protocol-and-disk.md#seeder-lifecycle)
|
||
- Root [README.md](../../README.md)
|