Raven Scott
7f4279d315
- Unify pear.multisig.json validation via bare-os-protocol + kernel boot fragment - Socket bridge: SCM_RIGHTS path, ancillary handling, TCP half-close/shutdown how, connect tcpRecvQueue + poll/recv EOF and EPIPE-shaped errors - Bin manifest / Hyperbee hints schema 2 + namesDigest; batch-write invalidation - Host booter structured logging; BOOT_PERF_DETAIL bare_stdlib_merge_ns timing - Wasm kernel optional syscall imports; security_posture rotation hints schema 2 - Shell errexit inside compound bodies; expand getconf/_SC_* and bareOsGetconfSysconf - Subprocess bridge snapshot timeoutPolicy; blind-relay protomux backpressure tests - Pear updater minimal delegate example + verify-pear scan; holepunch drift repos - Refresh handbook, kernel-image, syscall-socket-contract, posix matrix, PEAR-RUN Rebuild coreutils/bundles; bundle kernel; keep seeder/kernel parity.
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.
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
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
manpages 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. Read What this is, then Running seeder and booter, using the root README for the shortest copy-paste path.
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).
Chapters
- What this is — P2P image, two drives, why it exists, experimental status.
- Install and repository layout — clone,
npm ci, workspaces at a glance. - Running seeder and booter — Node versus Pear, two terminals, npm scripts.
- Shell, PATH, and scripts — how commands run without diving into the full
ctxAPI. - Home, identity, and vault — guest session,
login, vault snapshots, HDMS in brief. - Help, man, and the documentation map —
man,help, and where each doc tree fits. - Troubleshooting and operations — common failures, environment variables, where to read next.
- 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.jsand summarized in kernel capabilities index. - 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/, handbook/, developer-guide/, scripts/, users-manual/, packages/, kernel/, and root README.md, DOCUMENTATION.md, PEAR-RUN.md, man coverage, compatibility-matrix strings, 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. 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