# Concept — Boot and init timeline

This is the **happy-path** boot story at a glance. Wire formats and failure modes are in the handbook and protocol reference.

**Text summary (for plain-text / `man` readers — same order as the diagram):** the **seeder** publishes canonical **MBR block 0** and drive blocks onto the **Hyperswarm** topic. The **booter** **discovers peers** and **replicates**, **parses the MBR** to obtain **system Hyperdrive** keys, **opens or creates** the **personal Hyperdrive**, **builds `ctx**`, runs **`/boot/init.js`** (`start(ctx)`), and guest code then uses **`ctx`** and the **VFS** for syscalls and file access. After boot, eligible peers can mirror that same block `0` plus captured seed RPC snapshots for later cold joiners.

```mermaid
sequenceDiagram
  participant Seeder as Seeder
  participant Helper as EligibleBootedPeer
  participant Topic as HyperswarmTopic
  participant Booter as Booter
  participant Sys as SystemHyperdrive
  participant Per as PersonalHyperdrive
  participant Init as boot_init_js
  Seeder->>Topic: publish canonical MBR and blocks
  Helper->>Topic: mirror block 0 and seed RPC snapshots
  Booter->>Topic: discover peers replicate
  Booter->>Sys: open using MBR key material
  Booter->>Per: open or create personal drive
  Booter->>Init: run start(ctx)
  Init->>Booter: guest syscalls via ctx and VFS
```

## Roles

1. **Seeder** — stages `kernel/` into the system drive, writes the canonical **512-byte MBR**, stays online so others can replicate.
2. **Booter** — joins the same swarm topic, opens **system + personal** drives, constructs **`ctx`**, executes **`/boot/init.js`**.
3. **Eligible booted peer** — optionally mirrors the same block `0` and captured seed RPC snapshots for cold joiners.
4. **Stock kernel (`/boot/init.js`)** — brings up initd/cron themes, shell, and guest-visible policy as documented in the kernel contract.

## Block-0 trust assumptions

- Booters trust the first valid block `0` they accept on the `bare-os-v1` topic as the system-drive key envelope.
- Peer-assisted mirrors improve availability, but they do not add cryptographic authority beyond the same swarm trust boundary.
- Operators should pair swarm trust with policy gates (`bare_os.capabilities`, boot policy minimums, allowlists, and release verification) when deciding which peers are allowed to satisfy block `0`.
- A mismatched or malicious block `0` can redirect boot to a different drive; treat MBR provenance as part of your release trust model, not just a transport detail.

## Read next

- **Handbook** — [Chapter 3 — Protocol and disk](../../handbook/03-protocol-and-disk.md) (includes sequence diagram and MBR layout details).
- **Handbook** — [Chapter 4 — Booter runtime](../../handbook/04-the-booter-runtime.md).
- **Security** — [Boot trust model](../security/boot-trust-model.md).
- **Reference** — [KERNEL_CONTRACT.md](../architecture/KERNEL_CONTRACT.md).
- **P2P detail** — [P2P swarm and Protomux](p2p-swarm-and-protomux.md).