Chapter 1 — What this is

Audience: anyone new to Bare OS. Time to read: about five minutes.

The idea in one paragraph

Bare OS is a system image that lives on a Hyperdrive and is meant to be replicated from peers (Hyperswarm and Protomux) rather than downloaded from a single HTTP mirror. A seeder publishes that drive and a small MBR block; a booter joins the swarm, opens the drive, and runs /boot/init.js. Alongside the read-only system image, a separate personal Hyperdrive holds per-machine state: home directories, identity, logs, and optional extra mounts. The design is P2P-first and aligned with Holepunch-style Bare and Pear runtimes.

System drive versus personal drive

The system drive is the replicated OS tree: kernel, /bin, /boot, and the rest of the staged image. Treat it as shared and replaceable from the swarm’s point of view.

The personal drive is yours for that node: guest and user home layouts under controlled prefixes, account material under /.bare/, vault snapshots, HDMS registry data, and similar. The virtual file system routes paths such as $HOME and parts of /.bare/ to this drive so the two namespaces feel like one tree.

For the protocol layout (MBR, keys, swarm topic names), read Handbook — Chapter 3: Protocol and disk.

How you get the image

In development you typically:

Clone the git repository and run npm ci at the root.
Run a seeder that stages kernel/ into the system Hyperdrive and advertises it on the network.
Run a booter in another process that discovers peers and boots into the image.

You can run both sides with plain Node for quick iteration, or with Pear for behavior closer to a released app. The next chapters walk through install and commands; PEAR-RUN.md documents published Pear channels and pear:// links.

What you can do inside

Stock images ship a line-oriented shell with pipelines and redirects, a large set of POSIX-style utilities under /bin, sed and awk, and man backed by merged handbook and coreutils pages. Identity starts as guest; login can unlock an Ed25519-backed account on the personal drive. Optional HDMS can attach more Hyperdrives under /mnt.

The exact surface and intentional POSIX gaps are summarized in Handbook — Chapter 9.

Experimental software

Bare OS is not a production operating system. APIs, disk formats, and network behavior can change. Use it for research, prototyping, and learning. For security and trust boundaries, read Handbook — Preface and Developer guide — Security and trust.

Terminology you will see elsewhere

Holepunch / Pear / Bare — Bare OS targets the Bare JavaScript runtime and often ships as a Pear application. Your host may run Node for development even when the image expects Bare APIs.
System drive vs personal drive — Already introduced above; the handbook calls out routing rules, /.bare/, and mount namespaces in Chapter 5 and Chapter 3.
Stock image — The tree produced from this repository’s kernel/ plus built /bin and man.json, without your custom forks. Capability bits and ctx API versions describe what the stock booter and seeder advertise together; see compatibility matrix.

What Bare OS is not

It is not a Linux distribution, a container runtime, or a full hardware OS. There is no kernel mode, no hardware driver model, and no guarantee that arbitrary npm packages run unchanged inside the guest. Treat the POSIX-like surface as familiar ergonomics backed by JavaScript and Hyperdrive semantics, not as a certification target.

Previous: User manual home · Next: Chapter 2 — Install and repository layout

4.6 KiB Raw Blame History Unescape Escape