bare-operating-system/users-manual

Bare OS — user manual

This manual is for people who want to run and use Bare OS: clone the repo, start a seeder and booter, work in the shell, and understand where your files and identity live. It is written in plain language and points to deeper material when you need it.

Short evergreen explainers (two drives, boot, swarm, identity, POSIX stance): docs/concepts/README.md.

Bare OS is experimental research software, not a production operating system. It is licensed under Apache-2.0 (LICENSE).

Tip

If a term is unfamiliar, check the canonical glossary first, then jump back here.

---

On this page

• Who should read this
• Three paths through the docs
• Chapters
• How this relates to other documentation

---

Who should read this

You are in the right place if you want to:

• understand what Bare OS is without reading the full architecture story first;
• install dependencies, run the seeder and booter, and know which terminal does what;
• use the line shell, home directory, and guest versus logged-in sessions at a practical level;
• find man pages and know where handbook, developer guide, and reference docs live.

If you are changing /bin, the booter, or the kernel image, use the developer guide after skimming this manual.

---

Three paths through the docs

I only want to try it. Use Get started for the shortest copy-paste path, or read What this is then Running seeder and booter with the root README.

I use it regularly. Add Shell, PATH, and scripts, Home, identity, and vault, and Help, man, and the documentation map.

I need to debug or operate it. Use Troubleshooting and operations, the docs troubleshooting router, and the handbook chapter on operations (Chapter 7 — Operations and development). For POSIX terminology vs guest /proc / ctx mappings, see POSIX Issue 7 traceability and the compatibility matrix.

---

Chapters

1. What this is — P2P image, two drives, why it exists, experimental status.
2. Install and repository layout — clone, npm ci, workspaces at a glance.
3. Running seeder and booter — Node versus Pear, two terminals, npm scripts.
4. Shell, PATH, and scripts — how commands run without diving into the full ctx API.
5. Home, identity, and vault — guest session, login, vault snapshots, HDMS in brief. Deeper trust notes: Vault threat model.
6. Help, man, and the documentation map — man, help, and where each doc tree fits.
7. Troubleshooting and operations — common failures, environment variables, where to read next.
8. Further reading — curated links into the handbook and reference.

---

How this relates to other documentation

• Handbook tells the story: architecture, protocol, booter runtime, identity, POSIX surface, and roadmap. Start with the Preface if you want the full narrative.
• Developer guide explains how to build and extend software on the image: run(ctx, argv), coreutils, testing, Pear integration.

Pear OTA snapshot: host Pear channels pair with BARE_OS_PEAR_CHANNEL / BARE_OS_PEAR_RELEASE and optional ctx.bareOsPearUpdaterDelegate() (async) when BARE_OS_PEAR_UPDATER_SNAPSHOT_JSON or BARE_OS_PEAR_UPDATER_MODULE is set; ctx.bareOsSystemRevision and boot policy markers govern rollback. See developer-guide ch.11 — Pear workflows.

• docs/README.md is the documentation home: maps every tree, glossary, FAQ, troubleshooting router, ADRs, and release checklist.
• docs/reference is the file-level reference: packages, environment variables, data flow, compatibility. Capability bit masks are defined in packages/bare-os-protocol/lib/kernel-feature-bits.js and summarized in kernel capabilities index.
• Boot budget dashboard: the guest writes /run/bare-os/boot-budget-summary.json each boot; the stock booter mirrors it to /proc/bare_os/boot_budget_summary.json. Stable violation codes (BARE_OS_BOOT_BUDGET_*) are listed in that JSON. JSON Schema: docs/schemas/boot-budget-summary.schema.json.
• PEAR-RUN.md lists Pear channels, versioned pear:// links, and host environment notes for embedded Pear apps.

When this manual and another doc disagree on a detail, treat the handbook or reference as authoritative and open an issue if something is stale.

---

Validating what you read

Repository CI runs npm run pretest before tests: it checks kernel/seeder parity, capability contracts, relative .md links under docs/ (including docs/PEAR-RUN.md), handbook/, developer-guide/, scripts/, users-manual/, packages/, kernel/, and root README.md, DOCUMENTATION.md, man coverage, compatibility-matrix strings, the POSIX dashboard / compliance matrix / declared-profile triplet scripts (see scripts/README.md), and more. The link checker skips packages/bare-os-seeder/kernel/** (a byte-identical copy of kernel/**) and the packages/bare-os-bare-libs/README.kernel-lib-bare.md template whose links are validated after copy into kernel/lib/bare/README.md. Boot regression tests cover sensitive /.bare guest visibility (including optional BARE_OS_GUEST_BARE_READ_ALL for harnesses). If you are about to trust a path or script name from the docs, grepping the repo or running pretest locally is the fastest sanity check.

---

Next: Chapter 1 — What this is