Chapter 2 — Blueprints: architecture and trust

Time to read: about 10 minutes. Prerequisites: Chapter 1 vocabulary.

This chapter is the aerial view: boxes, arrows, and what is allowed to trust what. Implementation details live in later chapters.

For a comparison to classic images and security limits, see Preface — Comparison frame and Security.

0. Boot path from seeder to shell

The following is the conceptual ordering (not every substep on the wire). It complements the reference sequence diagram in Architecture: end-to-end data flow.

flowchart LR
  S[Seeder publishes system drive + MBR block 0]
  W[Hyperswarm topic bare-os-v1]
  B[Booter finds peer]
  M[Read MBR parse keys]
  D[Open system Hyperdrive replicate]
  P[Create personal Hyperdrive]
  K[executeKernel load init.js]
  Sh[Shell and /bin]
  S --> W
  W --> B
  B --> M
  M --> D
  D --> P
  P --> K
  K --> Sh

1. Two applications, one protocol

flowchart LR
  subgraph publishers [Publish side]
    Seeder[bare-os-seeder]
    SysImg[System Hyperdrive]
    Seeder --> SysImg
  end
  subgraph network [Hyperswarm]
    Topic[bare-os-v1 topic]
    Disc[Drive discovery keys]
  end
  subgraph consumers [Boot side]
    Booter[bare-os-booter]
    PeerDisk[SwarmDisk MBR + blocks]
    Booter --> PeerDisk
  end
  Seeder --> Topic
  Booter --> Topic
  SysImg --> Disc
  Booter --> Disc

The seeder is the publisher of the OS image (plus MBR in a small RAM map).
The booter is a consumer that refuses to invent a local copy: it must see peers.

2. Two drives on the booter

flowchart TB
  subgraph booterProcess [Booter process]
    VFS[VFS layer]
    Sys[System Hyperdrive]
    Pers[Personal Hyperdrive]
    VFS -->|"paths outside HOME"| Sys
    VFS -->|"HOME and below"| Pers
  end

Trust model (pragmatic):

System drive content is whatever replicated from the swarm matching the MBR keys. In dev you treat the seeder as trusted; in the wild this is “who you peer with.”
Personal drive is your namespace (Corestore bare-os-personal-v1). It holds secrets, cron, dotfiles, HDMS registry, vault snapshots.

3. Protocol, MBR, and discovery

The shared package bare-os-protocol pins:

TOPIC_STRING === 'bare-os-v1'
topicKey() = crypto.hash(b4a.from(TOPIC_STRING))
MBR layout: 512 bytes, magic BIOS, primary key at offset 8, optional failover keys at 40 and 72

MBR layout (512 bytes, see bare-os-protocol/constants.js):

Bytes 0–3: BIOS magic
Bytes 8–39: primary system Hyperdrive public key
Bytes 40–71, 72–103: optional additional keys

Protomux channel bare-os-v1 carries:

Block read requests (MBR and any indexed RAM the seeder exposes)
Hyperdrive replication on the same socket
Gossip bitfield (message 2), manifest search (3/4), and bare_os.* RPC (5/6) on the seed channel (see packages/bare-os-protocol/lib/channel.js; Kernel extensions)

4. Execution stack inside the booter

flowchart TB
  Init[index.js main]
  Splash[Boot splash TTY]
  Swarm[Hyperswarm + SwarmDisk]
  ExecK[executeKernel]
  Repl[Kernel REPL session]
  Init --> Splash
  Init --> Swarm
  Swarm --> ExecK
  ExecK --> Repl
  Repl --> Kernel["runKernelFromSource /boot/init.js"]
  Kernel --> Shell["execLine → execShellLine"]
  Shell --> Bin["runBinCommand / paths / PATH"]

Kernel and /bin scripts are not separate processes. They are AsyncFunction closures in the same JS realm as the booter, with a synthetic ctx instead of syscalls.

5. Services after the console exists

flowchart LR
  Session[createKernelReplSession]
  Console[ctx.console = session.console]
  Initd[startBareInitd]
  Logger[kernel-logger wraps log/error]
  Cron[bare-cron setInterval]
  Session --> Console
  Console --> Initd
  Initd --> Logger
  Initd --> Cron

stopBareInitd() runs from REPL session cleanup so timers do not leak across session restarts.

6. Identity states

Guest and unlocked sessions share the same booter process; the state machine below is about environment and policy, not separate OS processes.

stateDiagram-v2
  [*] --> Guest
  Guest --> Unlocked: login / login --new
  Unlocked --> Guest: logout
  Unlocked --> Unlocked: HDMS active after unlock

Guest: fixed HOME=/home/guest, read-oriented personal tree policy for some operations.
Unlocked: HOME under /home/<pubkey-prefix>, HDMS can attach writable drives, crontab install/remove allowed.

Full story: Chapter 5 — Identity, vault, HDMS.

7. What is not here (boundary)

No hardware kernel, no MMU, no ELF loader for native /bin.
No container cgroup isolation—commands are JS with full host capability of the Pear/Bare process.
Future: stronger isolation would compose Bare workers, Pear runtime isolates, or bare-kit-style embeds; the stock ctx.bareOsSandboxRunScript hook is a documented placeholder until then (see developer guide security chapter).
No global consensus: two booters can diverge if they replicate different forks of the same discovery key (Hyperdrive versioning is a separate concern).

Next: Chapter 3 — Protocol and disk

Related: Preface · Handbook home · Kernel extensions

Experimental research software, not a production OS. Apache-2.0 — LICENSE.

5.7 KiB Raw Blame History Unescape Escape