Chapter 3 — Protocol, MBR, and SwarmDisk

Here we connect bare-os-protocol to what seeder and booter actually do on the wire and in RAM.

Seeder lifecycle

Resolve kernel root (BARE_OS_KERNEL_ROOT or vendored kernel/).
Optionally rebuild coreutils when running under Node (file: URL) — skipped under Pear.
Open Corestore + Hyperdrive, stageKernelTree:
- init.js → /boot/init.js
- bin/* → /bin/*
- etc/* → /etc/*
Build MBR with buildMbr(drive.key) and store block 0 in a Map (localRAM).
Hyperswarm join(topicKey()) and join(drive.discoveryKey).
On each connection: Protomux + setupSeedChannel, which:
- Answers read index requests from localRAM (index 0 → MBR)
- Attaches drive.replicate(stream)

sequenceDiagram
  participant S as Seeder
  participant W as Hyperswarm
  participant B as Booter
  S->>W: join topic + discoveryKey
  B->>W: join topic
  B->>S: mux connection
  Note over B,S: Protomux bare-os-v1
  B->>S: read block 0
  S-->>B: MBR 512 bytes
  B->>S: hyperdrive replicate

Booter: from peers to Hyperdrive

SwarmDisk (booter) mirrors the seeder’s channel handlers:

read(index) — if not local RAM, broadcast msg 0 to peers, await msg 1 (timeout).
addPeer — open channel, replicate system (and later personal) drives on the mux stream.

Boot path:

Wait until disk.peers.size > 0 or boot timeout.
parseMbr(await disk.read(0)) → list of 32-byte keys.
For each key, try Hyperdrive(store, key) + replicate until /boot/init.js exists.
Initialize personal drive namespace and join its discovery key.
Hand off to executeKernel.

There is intentionally no “use my checkout’s kernel/ if the network fails” path—the project forces you to think about availability of the swarm.

Message IDs (reference)

Aligned with packages/bare-os-protocol/lib/channel.js and swarm-disk.js:

ID	Direction	Purpose
0	Client → peers	Read block by index
1	Peer → client	Data payload
2	Gossip stub	Bitfield buffer
3 / 4	Search req/res	Stub (empty matches)
5 / 6	RPC req/res	`bare_os.version` implemented; other methods return “not implemented”

The important path for boot is 0/1 + Hyperdrive replication on the same socket.

Personal drive replication

SwarmDisk.initPersonalDrive creates a separate Hyperdrive under a stable Corestore namespace and swarm.join(personalDrive.discoveryKey). Your $HOME tree can therefore sync across your devices if peers share that discovery key—orthogonal to the system image key from the MBR.

Failure modes you will see in the wild

Boot timeout — no peer answered the topic (seeder not running, firewall, wrong network).
Invalid MBR — corrupt block 0 or wrong magic; parseMbr throws.
Drive never completes — replication stalled; check peer count and discovery key joins.

← Blueprints · Handbook home · Next: Booter runtime →

3.3 KiB Raw Blame History Unescape Escape