# Bare operating system

[License](LICENSE)
[Node](package.json)

> [!CAUTION]
> **Experimental research software** — not a production OS. Peers, keys, vault data, and network exposure deserve the same caution you would give any crypto-heavy prototype.

**Bare OS** is a **P2P-first** system image: the operating tree lives on a **Hyperdrive** replicated over **Hyperswarm** and **Protomux**, not a single HTTP mirror. A **seeder** stages the kernel and **`/bin`** into the system drive and publishes the **MBR**; a **booter** discovers peers, replicates the image, attaches a **personal** drive for identity and mutable state, and runs **`/boot/init.js`**. After a successful boot, eligible booters can also mirror the same block `0` MBR and captured seed RPC hints for cold joiners (peer-assisted seeding; see the environment appendix and handbook chapter 3). The stack targets **decentralized distribution** alongside Holepunch-style runtimes (**Bare** / **Pear**).

**New here?** Read **[Get started](docs/get-started.md)** (one page: clone → two terminals → what “success” looks like), then skim **[Concepts — Two drives](docs/concepts/two-drive-model.md)**.

**Prerequisites (before first run)**

- **Node.js ≥ 20** and **`npm ci`** at the repository root.
- **Bare CLI** (`npm i -g bare`) for **`npm run os:seeder`** / **`npm run os:booter`**, or download **rolling** binaries from Gitea (see [BINARY-RELEASE.md](docs/BINARY-RELEASE.md)).
- **Network:** the booter must find a peer on the **`bare-os-v1`** swarm topic within **`BARE_OS_BOOT_TIMEOUT_MS`** (default **60000** ms).

**Canonical remote:** `https://git.ssh.surf/snxraven/bare-operating-system.git`



**60-second mental model**

- **System drive** — replicated image: **`/boot`**, **`/bin`**, stock kernel, read-only policy for most tree.
- **Personal drive** — **`$HOME`**, **`/.bare`**, vault material, per-node history.
- **Dev workflow** — almost always **two processes**: seeder (canonical publisher) + booter (consumer, and optional helper for later cold joiners).
- **Two runtimes** — the **host** (Bare standalone / Node) implements **`ctx`** and the VFS; **scripts on the drive** run under the in-image eval model (not Node ESM on-disk). See [Developer guide §1 — Two runtimes](developer-guide/01-two-runtimes-host-vs-image.md).



## Try it

**One-line installer** (downloads rolling binaries from Gitea):

```bash
curl -fsSL https://install.bare-os.live | bash
# or from Gitea raw:
# curl -fsSL https://git.ssh.surf/snxraven/bare-operating-system/raw/branch/main/scripts/install.sh | bash
```

Non-interactive:

```bash
curl -fsSL https://install.bare-os.live | bash -s -- --both --yes
```

Or unpack a release tarball / `pear install`:

```bash
tar -xzf bare-os-booter-0.1.0-linux-x64.tar.gz
./bare-os-booter --no-updates
```

```bash
pear install pear://khtauzttriz8dpgrphj79rfy98iwoatqm59fnogtsdqk5f1kg6ao
```

From this repository:

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

**Terminal A — seeder** (publishes the canonical drive + MBR):

```bash
npm run os:seeder
```

**Terminal B — booter** (boots from peers; later may mirror block `0` when eligible):

```bash
npm run os:booter
```

> [!TIP]
> **`npm run os:seeder`** and **`npm run os:booter`** run **`pear run --dev`** after linking hoisted workspace dependencies.

> **Tip**  
> For a **Node-only** path (no Pear), see [User manual — Chapter 3](users-manual/03-running-seeder-and-booter.md).

Full operations, environment variables, and troubleshooting: [Handbook — Chapter 7](handbook/07-operations-and-development.md) and [Environment appendix](docs/reference/environment-and-posix-appendix.md).

## Documentation


| Start here                                   | Role                                                                   |
| -------------------------------------------- | ---------------------------------------------------------------------- |
| **[Get started](docs/get-started.md)**       | Zero-to-prompt path with prerequisites and failure table               |
| **[Documentation home](docs/README.md)**     | Role-based map, contract spine, POSIX + P2P dashboard                  |
| **[Documentation sitemap](docs/sitemap.md)** | How user manual, handbook, developer guide, and reference fit together |
| **[Concepts](docs/concepts/README.md)**      | Short evergreen pages: two drives, boot, swarm, identity, POSIX stance |


**Legacy router:** [DOCUMENTATION.md](DOCUMENTATION.md) maps the old monolith sections to `docs/reference/`.

**On this page:** [What you get](#what-you-get) · [User manual](#user-manual) · [Handbook](#handbook) · [Developer guide](#developer-guide) · [Reference](#reference-and-contracts) · [POSIX surface](#posix-surface) · [Protocol](#protocol-snapshot) · [Kernel parity](#kernel-image-and-pear-seeder-parity) · [Contributing](#contributing--ci)

### What you get

- **Two-drive model** — read-only **system** image + writable **personal** namespace; VFS routes **`$HOME`** and **`/.bare/`** to the personal drive.
- **Tier-1 `/bin`** — **186** POSIX-oriented utilities (authoritative list: **`COREUTILS_COMMANDS`** in [packages/bare-os-coreutils/lib/commands.mjs](packages/bare-os-coreutils/lib/commands.mjs); **`verify-man-coverage`** in **`pretest`** keeps **`man.json`** in sync), line shell with pipelines and redirects, **`sed`**/**`awk`**, **`man`** backed by merged JSON handbook + coreutils pages.
- **Identity** — Ed25519 account on the personal drive, guest vs unlocked session, encrypted vault snapshot (`savevault` / `logout --save`).
- **Boot plumbing** — initd/cron **themes**, synthetic **`/proc`** / **`/run`** / **`/sys`**, optional **`ctx.bare`** bundles from **`/lib/bare`** (Holepunch catalog workflow at repo root).
- **Personal site (HTTP)** — Initd **`bare-os-www`** serves static files from **`~/.www`** on **`127.0.0.1:8088`** by default; managed **Holesail** can expose `**bare-www-<port>`** when enabled. [Handbook — Chapter 4](handbook/04-the-booter-runtime.md#bare-os-www-static-http-for-www).
- **SSH in the booter** — Initd unit **`bare-openssh`** runs an SSH-2 server (**`bare-ssh2`**, vendored in `[packages/bare-os-openssh](packages/bare-os-openssh)`) bound to **`127.0.0.1`** by default; **`/bin/sshd`** delegates to **`ctx.bareOsRunSshdCli`**. Host keys live on the **personal** drive under `**~/.config/bare-os/ssh/host/**` (see **`man sshd`** / **`sshd_config`**). Set **`BARE_OS_SSH_BIND_ALL=1`** on the host to widen **`ListenAddress`** when **`sshd_config`** still says **`127.0.0.1`**; use **`BARE_OS_SSH_LISTEN_PORT`** to override the listen port (including **`0`** for an ephemeral port in tests).
- **Protocol** — Swarm topic + Protomux **`bare-os-v1`**, 512-byte **MBR** with Hyperdrive keys (`BIOS` magic). Seeder is the canonical source; eligible booted peers can mirror the same MBR for availability. Details: [Handbook — Chapter 3](handbook/03-protocol-and-disk.md) and [Protocol reference](docs/reference/package-bare-os-protocol.md).

**Verifier-backed docs:** root **`npm test`** runs **`pretest`**, which checks kernel/seeder parity, doc links, man coverage, POSIX profile triplet, compatibility-matrix strings, and more — see [scripts/README.md](scripts/README.md).

### Agent system — Markdown brain at `~/.agent/workspace`

The in-image **`/bin/agent`** loads a Markdown workspace from `**~/.agent/workspace/**` on the **personal Hyperdrive** (canonical soul files: **`SOUL.md`**, **`AGENTS.md`**, **`IDENTITY.md`**, …). Defaults ship under **`/share/agent-workspace/`** on the system image; on first run, if `**~/.agent/workspace/SOUL.md`** is missing, the agent **seeds** that tree from the share so every home gets a portable, git-friendly brain.

- **Templates in git:** [packages/bare-os-coreutils/share/agent-workspace/](packages/bare-os-coreutils/share/agent-workspace/) — copied to **`kernel/share/agent-workspace/`** by **`npm run build -w bare-os-coreutils`**.
- **Host sample prompt:** **`npm run sample:agent-workspace`** — prints a concatenated preview from the repo share (no booter required).
- **Skills:** modular **`SKILL.md`** trees under **`~/.agent/workspace/skills/`** (optional **`~/.agent/skills/**`); **`/bin/agent`** appends a compact index to the system message and exposes the **`read_skill`** tool for full instructions. Seeded examples include **`bare-os-super-developer`** (**`ctx`**, scripts, small apps).
- **First-time config:** **`agent --setup`** or **`agent --config`** runs a plain TTY wizard (owner name, agent label, API URL/key/model/provider) and seeds **`~/.agent/workspace/`** from **`/share/agent-workspace/`** when **`SOUL.md`** is missing; **`--config`** is an alias for **`--setup`**.
- **Runtime docs:** seeded **`~/.agent/README-agent.md`** after first seed; see also **`man agent`** and [User manual — ch.4](users-manual/04-shell-path-and-scripts.md).

### User manual

For **run and use** without reading full architecture first: [users-manual/README.md](users-manual/README.md) — install, seeder and booter, shell, identity, `man` / `help`, troubleshooting.

### Handbook

Narrative spine — *why* the system is shaped this way: [handbook/README.md](handbook/README.md). Begin with [Preface](handbook/00-preface.md) or [Chapter 7 — Operations](handbook/07-operations-and-development.md) for CI and Pear.

### Developer guide

How-to for **`start(ctx)`** / **`run(ctx, argv)`**, extending **`/bin`**, testing, Pear, telemetry scrubbing: [developer-guide/README.md](developer-guide/README.md).

### Reference and contracts

- **[File-level reference](docs/reference/README.md)** — packages, environment appendix, data flow (legacy map: `[DOCUMENTATION.md](DOCUMENTATION.md)`).
- **[ctx API changelog](packages/bare-os-booter/CHANGELOG.md)** — **`bareOsCtxApiVersion`** history.
- **[Compatibility matrix](docs/reference/compatibility-matrix.md)** — protocol, feature-bits doc, **`ctx`** API, lifecycle/telemetry schema versions.

### Glossary and help

[Glossary](docs/glossary.md) · [FAQ](docs/faq.md) · [Troubleshooting](docs/troubleshooting.md) · [Contributing to docs](docs/CONTRIBUTING-DOCS.md)

### POSIX surface

[Handbook — Chapter 9](handbook/09-posix-utilities-shell-and-vfs.md). Declared profile **`1.0.19`** (**`BARE_OS_POSIX_PROFILE_VERSION`**) with **`ctx`** API **`1.57.0`** — [POSIX declared profile](docs/architecture/POSIX_DECLARED_PROFILE.md) and [compatibility matrix](docs/reference/compatibility-matrix.md). Machine-readable: [docs/reference/posix-compliance-matrix.json](docs/reference/posix-compliance-matrix.json) (verified in **`pretest`**).

## Protocol snapshot

- **Swarm topic** — `crypto.hash(b4a.from('bare-os-v1'))`
- **Protomux channel name** — `bare-os-v1`
- **MBR** — 512 bytes, magic `BIOS`, primary Hyperdrive key at byte offset 8, failover keys at offsets 40 and 72

Full wire layout: [Handbook — Chapter 3](handbook/03-protocol-and-disk.md) and [protocol package reference](docs/reference/package-bare-os-protocol.md).

## Guest identity (short)

Default session is **guest**; **`login`** / **`logout`**, **`/.bare/account`**, guest **`/.bare`** read policy, legacy-root migration (**`BARE_OS_PERSONAL_ROOT_MIGRATE`**), and optional **`BARE_OS_PERSONAL_ACCT_PREFIX`**: [booter reference](docs/reference/package-bare-os-booter.md), [environment appendix](docs/reference/environment-and-posix-appendix.md), [Handbook — Chapter 4](handbook/04-the-booter-runtime.md).

## Kernel image and Pear seeder parity

Canonical tree: **`kernel/`**; **`packages/bare-os-seeder/kernel/`** must stay **byte-identical**.

- **Full maintainer rebuild:** **`npm run maintainer:kernel-image`**
- **Sync only:** **`npm run maintainer:sync-kernel-seeder`** (or **`…:bundle`** to re-bundle **`/boot/init.js`** first)

Details: [Handbook — Chapter 7](handbook/07-operations-and-development.md).

## Contributing / CI

Root **`npm test`** runs workspace tests plus **`pretest`** hooks (kernel/seeder parity, **`verify-ctx-api-feature-bits`**, Pear import policy, doc link and contract checks). Maintainer script inventory: [scripts/README.md](scripts/README.md).

Before a release tag, run **`npm run release-checklist`** (`[scripts/release-checklist.mjs](scripts/release-checklist.mjs)`) — see [docs/release-checklist.md](docs/release-checklist.md).

## Observability (host env)

Optional guest paths **`BARE_OS_TELEMETRY_NDJSON`**, **`BARE_OS_TELEMETRY_OTEL_JSONL`**, and shorthand **`BARE_OS_TELEMETRY_OTEL=1`** (defaults the OTel path) append capped JSON lines; records carry **`lifecycleSchemaVersion`** and **`telemetrySchemaVersion`** aligned with stock **`BARE_OS_LIFECYCLE_SCHEMA_VERSION`** (see [compatibility matrix](docs/reference/compatibility-matrix.md) and [environment appendix](docs/reference/environment-and-posix-appendix.md)). Coalesced metrics: **`/proc/bare_os/metrics_live.json`** (poll **`BARE_OS_PROC_POLL_MS`**). Dev-only **`BARE_OS_DIAGNOSTICS_SUBSCRIBE=1`** enables **`ctx.bareOsDiagnosticsSubscribe`**. [Kernel extensions](docs/reference/kernel-extensions.md) · [JSON Schemas](docs/schemas/).

## License

Apache-2.0 — open source software owned, operated, and engineered by HoneyPeer, LLC, a DeKalb, Georgia limited liability company. See [LICENSE](LICENSE).