Raven Scott
d286ce19b5
test(protocol): add deterministic MBR failover-key coverage docs(protocol): align package-bare-os-protocol version to 0.9.1 test(booter): add MBR corruption and wrong-topic smoke fixtures test(peer-seed): add strict pre-MBR bare_os.capabilities negotiation check feat(seeder): validate BARE_OS_SEED_REQUIRE_MBR_LABELS feat(seeder): validate BARE_OS_SEED_CAPABILITY_ATTESTATION_JSON schema docs(boot-policy): add requireProtocolPackageMin 0.9.1 example test(kernel): cover boot.policy denySeedRpcMethods behavior test(protocol): add app/cap/chat/meshdrop channel compatibility fixture test(swarm-disk): cover duplicate Protomux channel null-return path test(protocol): add 11-word kernelCapabilityWords round-trip fixture docs(schema): add mbr-layout schema and validate seeder examples test(protocol): add topicKey() golden hash fixture docs(trust): document block-0 trust assumptions in boot docs feat(seeder): add discovery.flushed readiness logging feat(booter): record peer discovery timings in boot-perf.json feat(integration): add local testnet mode to integration lab smoke test(booter): add Hyperswarm connection-budget env regression coverage test(booter): add swarm plus Corestore suspend/resume integration coverage feat(booter): mirror swarm ban events into host audit logs feat(booter): add direct-peer boot via BARE_OS_BOOT_JOIN_PEER_HEX feat(seeder): pass BARE_OS_SEED_MAX_PEERS to Hyperswarm feat(seeder): log drive.version and discoveryKey at startup test(booter): add Hyperdrive.checkout read-only boot probe coverage feat(booter): prefetch /boot/init.js before kernel handoff feat(booter): add optional /bin warm replication via downloadDiff feat(seeder): add manifestPaths SHA-256 generation in stage-kernel-tree test(peer-seed): cover helper-served block-0 after seeder exit feat(protocol): add Protomux cork batching for initial channel sends test(boot-graph): compare kernel/init labels with booter graph proc docs(boot-policy): add v9-v11 schema examples feat(release): add requireInitJsSha256 fixture generation step test(vfs): add BARE_OS_VFS_SYSTEM_RO_ALIAS coverage test(vfs): strengthen system-drive write-deny path coverage feat(identity): add personal-drive namespace export/import docs and tests test(booter): add guest-to-login warm cache invalidation regression test(vfs): add guest deny coverage for /.bare sensitive paths test(coreutils): add cross-drive mv failure injection coverage test(vfs): add .bareos_empty round-trip coverage across mkdir/rmdir/cp/git-fs test(vfs): add /dev/shm quota enforcement coverage test(proc): add /proc/bare_os/index.json sortedness and schema checks test(vfs): add warm read cache invalidation on replication growth docs(ctx): document bareOsInvalidateWarmReadCaches(reason) test(kernel): add BARE_OS_BOOT_DRY_RUN behavior coverage docs(posix): add dashboard rows for all COREUTILS_COMMANDS feat(curl): expand -w variables beyond http_code/url_effective/size_download feat(wget): mark -N timestamping as explicit unsupported error feat(curl): plumb mutual TLS cert/key intent to ctx.httpFetch metadata feat(shuf): add deterministic seed mode via BARE_OS_SHUF_SEED docs(sort): document -M month-sort as unsupported feat(grep): add explicit -E and -G mode handling test(sed): add Open Group Issue 7 golden fixtures test(awk): add getline VFS regressions for missing/repeat/boundary cases test(shell): add non-interactive here-doc coverage test(shell): add trap delivery coverage for synthetic PIDs/job IDs test(shell): add set -e compound-body behavior coverage docs(shell): strengthen read builtin opt-in guidance test(env): add Bare-runtime coverage for -S and --env-file docs(man): add examples for pathcap-verify pkg-swarm-index corestorectl test(identity): add account/vault backup-restore smoke coverage feat(audit): add tamper detection verification for audit chain rows test(peer-admission): cover strict empty allowlist deny behavior test(peer-admission): add denylist precedence over allowlist coverage test(peer-admission): add BARE_OS_PEER_REQUIRE_CAPS_JSON metadata checks docs(identity): add trusted-key rotation example for path capabilities feat(schema): tighten extensionSignerPinsV2-V4 hash validation test(delegate): add allowlist negative cases for curl/wget/git/hrpc/systemctl test(proc): extend /proc/self/environ redaction key coverage docs(security): add peer-assisted block-0 mirroring threat-model notes feat(bench): add boot budget trend output from real booter phases test(baretop): align fixture coverage with /proc snapshot key set test(metrics): validate /proc/bare_os/metrics.prom OpenMetrics shape docs(ops): add structured seeder NDJSON examples test(replication): add live stall-hint coverage for no_peers/length_unavailable/ok docs(release): add corestore-snapshot workflow to checklist docs(ops): add mirror-drive experiment utility to maintainer workflow test(booter): add monitor progress coverage for replication live sketch feat(seeder): validate DHT bootstrap address class JSON inputs docs(network): add HYPERSWARM_BOOTSTRAP testnet operator guidance chore(root): add deterministic test:integration script docs(ci): add local CI runbook for no-.github environments docs(release): add npm run test:bare after npm test feat(verify): add protocol docs/package version parity checker feat(verify): enforce feature-roadmap canonical path consistency feat(lockfile-drift): add tier-1 strict fail option for mismatches docs(lockfile-drift): add udx-native and blind-peering upgrade workflow notes docs(cli-parity): add bare-fetch upstream issue tracking row feat(bundle-health): generate per-tier bundle size regression thresholds feat(doc-contracts): verify handbook references to current proc schema versions feat(pretest): add validate-mermaid-syntax gate feat(probe): add bare-runtime top-25 critical command lane docs(protocol): update capability-word prose from bits..bits5 to current words docs(two-drive): document /tmp /var/log and account-prefix routing docs(security): add concise boot trust model page and links docs(dev-guide): add P2P lab cookbook section docs(dev-guide): add how-to for adding seed RPCs docs(dev-guide): add how-to for adding /proc/bare_os nodes docs(dev-guide): add /bin utility checklist for man/posix/build/parity/tests docs(user-manual): add short What BareOS is not section
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
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; - run
agent(OpenAI-compatible HTTPS assistant; config under **~/.agent/**) orchat(swarm / Protomux chat — see Chapter 4 andman agent/man chatin the guest).
If you are changing /bin, the booter, or the kernel image, use the developer guide after skimming this manual.
What Bare OS is not
- Not a hardened general-purpose desktop/server OS replacement.
- Not a guarantee of anonymous or trustless networking by default.
- Not a drop-in POSIX certification target (it is POSIX-like, with explicit gaps).
- Not a managed cloud control plane; operators still own peer admission and release trust policy.
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 (includes agent / chat), 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
- 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;agent/chatassistants and**~/.agent/**. - Home, identity, and vault — guest session,
login, vault snapshots, HDMS in brief. Deeper trust notes: Vault threat model and Boot trust model. - 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. - Boot budget dashboard: the guest writes
/run/bare-os/boot-budget-summary.jsoneach 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