# Chapter 2 — Install and repository layout

**Prerequisites:** [Chapter 1 — What this is](01-what-this-is.md). **Time to read:** about six minutes.

---

## On this page

- [What you need on the host](#what-you-need-on-the-host)
- [Clone and install](#clone-and-install)
- [Monorepo layout at a glance](#monorepo-layout-at-a-glance)
- [Where to go next](#where-to-go-next)
- [Root npm scripts (operators)](#root-npm-scripts-operators)
- [Disk, caches, and Corestore](#disk-caches-and-corestore)

---

## What you need on the host

- **Node.js 20 or newer** (see root `package.json` `engines`).
- **Git** to clone the repository.
- For Pear workflows: **Pear CLI** installed and configured on your machine. The repo’s **`npm run os:seeder`** and **`npm run os:booter`** scripts assume Pear when you use those entry points.

Continuous integration also installs **Bare** globally for tests that touch identity crypto; if you run the full **`npm test`** suite locally, match that setup. Details live in [Handbook — Chapter 7](../handbook/07-operations-and-development.md#continuous-integration-github-actions).

---

## Clone and install

From a terminal:

```bash
git clone https://git.ssh.surf/snxraven/bare-operating-system.git
cd bare-operating-system
npm ci
```

Run **`npm test`** when you want to confirm the tree is healthy before you change code. **`pretest`** builds coreutils and bare-libs, verifies kernel and seeder parity, and runs several contract and documentation checks. If **`pretest`** fails, the handbook’s operations chapter explains the common causes.

---

## Monorepo layout at a glance

The repository is an **npm workspace** monorepo. These paths matter most when you are running or debugging Bare OS:

- **`kernel/`** — Sources that are staged onto the **system** Hyperdrive by the seeder. A copy is kept under **`packages/bare-os-seeder/kernel/`** for Pear packaging; CI enforces that they stay in sync.
- **`packages/bare-os-protocol`** — Shared protocol constants: swarm topic, MBR layout, Protomux identifiers, kernel feature bits.
- **`packages/bare-os-seeder`** — Publishes the OS drive and joins the swarm so booters can replicate.
- **`packages/bare-os-booter`** — Joins the swarm, opens system and personal drives, constructs the guest runtime, and runs **`/boot/init.js`**.
- **`packages/bare-os-coreutils`** — Sources and build for **`/bin`** utilities and the merged **`man.json`** database.
- **`packages/bare-os-bare-libs`** — Optional **`/lib/bare`** bundles merged into **`ctx.bare`** when enabled.
- **`scripts/`** — Automation: Pear `node_modules` helpers, parity verifiers, catalog generation, release checklist.

Each workspace package has its own **README** with package-specific commands. For a file-by-file inventory, use [docs/reference — Repository layout](../docs/reference/repo-layout-and-root.md).

Default **Corestore** directories for seeder and booter usually live under **`~/.bare-os/`** unless you override them with environment variables documented in the [environment appendix](../docs/reference/environment-and-posix-appendix.md).

---

## Root npm scripts (operators)

From the **repository root**, the scripts you touch most often are:

- **`npm run os:seeder`** — Builds **coreutils** and **bare-libs**, ensures Pear sees hoisted **`node_modules`**, then **`pear run --dev .`** inside **`packages/bare-os-seeder`**. Use when you want Pear-accurate seeding during app development.
- **`npm run os:booter`** — Same Pear **`node_modules`** preparation for the booter package, then **`pear run --dev .`** in **`packages/bare-os-booter`**.
- **`npm run pretest`** — Required gate before **`npm test`**: builds artifacts, runs parity and documentation verifiers (see [Chapter 7](07-troubleshooting-and-operations.md)).
- **`npm test`** — Runs **`pretest`**, then **`npm run test --workspaces --if-present`** so every workspace package can contribute its own suite.

Maintainers also use **`npm run gen:bare-catalog`**, **`npm run sync:bare-manifest`**, and **`npm run release-checklist`**; see [Handbook — Chapter 7](../handbook/07-operations-and-development.md) for workflow context.

---

## Disk, caches, and Corestore

Seeder and booter persist Hypercore storage on disk. Default layouts are described in package READMEs and the [environment appendix](../docs/reference/environment-and-posix-appendix.md) (**`BARE_OS_SEED_STORE`**, **`BARE_OS_BOOT_STORE`**, **`BARE_OS_HOST_DATA`**). If you switch between **Node** and **Pear** runs, you usually keep the **same** store paths so the personal drive and replication state stay consistent. Deleting **`~/.bare-os/`** is a blunt “factory reset” for local development: you lose replicated drives unless you have keys or snapshots elsewhere.

---

## Where to go next

- **Run the system:** [Chapter 3 — Running seeder and booter](03-running-seeder-and-booter.md).
- **Deeper operations and CI:** [Handbook — Chapter 7](../handbook/07-operations-and-development.md).
- **Exact env var names:** [Environment variables and POSIX appendix](../docs/reference/environment-and-posix-appendix.md).

---

_Previous: [Chapter 1](01-what-this-is.md)_ · _Next: [Chapter 3 — Running seeder and booter](03-running-seeder-and-booter.md)_