76 lines
4.6 KiB
Markdown
76 lines
4.6 KiB
Markdown
# Chapter 1 — What this is
|
||
|
||
**Audience:** anyone new to Bare OS. **Time to read:** about five minutes.
|
||
|
||
---
|
||
|
||
## On this page
|
||
|
||
- [The idea in one paragraph](#the-idea-in-one-paragraph)
|
||
- [System drive versus personal drive](#system-drive-versus-personal-drive)
|
||
- [How you get the image](#how-you-get-the-image)
|
||
- [What you can do inside](#what-you-can-do-inside)
|
||
- [Experimental software](#experimental-software)
|
||
- [Terminology you will see elsewhere](#terminology-you-will-see-elsewhere)
|
||
- [What Bare OS is not](#what-bare-os-is-not)
|
||
|
||
---
|
||
|
||
## 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](../handbook/03-protocol-and-disk.md).
|
||
|
||
---
|
||
|
||
## How you get the image
|
||
|
||
In development you typically:
|
||
|
||
1. Clone the **git repository** and run **`npm ci`** at the root.
|
||
2. Run a **seeder** that stages **`kernel/`** into the system Hyperdrive and advertises it on the network.
|
||
3. 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](../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](../handbook/09-posix-utilities-shell-and-vfs.md).
|
||
|
||
---
|
||
|
||
## 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](../handbook/00-preface.md) and [Developer guide — Security and trust](../developer-guide/09-security-and-trust.md).
|
||
|
||
---
|
||
|
||
## 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](../handbook/05-identity-vault-and-hdms.md) and [Chapter 3](../handbook/03-protocol-and-disk.md).
|
||
- **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](../docs/reference/compatibility-matrix.md).
|
||
|
||
---
|
||
|
||
## 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](README.md)_ · _Next: [Chapter 2 — Install and repository layout](02-install-and-repository-layout.md)_
|