bare-operating-system/docs

Bare OS — documentation home

Bare OS is an experimental, P2P-first system image: the operating tree lives on a replicated Hyperdrive, distributed via Hyperswarm and Protomux, with a separate personal drive for identity and mutable state. This page is the navigation hub for every documentation tree in the repository.

Caution

Experimental research software — not a production operating system. Trust boundaries and security limits matter.

Important

Same message on forges that do not render GitHub-style alerts: this project is research software, not a production OS. Full framing: handbook preface.

First run: Get started · Doc map: Sitemap · Evergreen explainers: Concepts.

On this page

• Get started · Sitemap
• Pick your depth
• Architecture snapshot
• Two-drive and swarm path
• Boot sequence logical order
• POSIX + P2P reading order
• Contract spine
• POSIX + P2P consolidated dashboard
• Documentation map
• Topic index
• Contract bump checklist

Pick your depth

Time	Goal	Path
5 min	See it run	Get started → User manual — ch.3
30 min	Two drives + P2P boot	Concepts → Handbook ch.3
2 h	Extend /bin or kernel	Developer guide §1–6 + KERNEL_CONTRACT
Release	Avoid CI surprises	scripts/README.md + Release checklist

Architecture snapshot

End-to-end data path from swarm connection to guest syscalls (canonical overview; details in the handbook, concepts — P2P, and kernel contract):

flowchart TB
  subgraph swarmLayer [P2P transport]
    HS[Hyperswarm topic]
    MUX[Protomux on encrypted stream]
    CH1["Channel bare-os-v1"]
    CH2["Optional bare-os-app-v1"]
  end
  subgraph booterHost [Pear or Node booter]
    DISK[SwarmDisk + Corestore]
    CTX["ctx: vfs IPC syscall swarm hooks"]
  end
  subgraph guestImage [Hyperdrive system image]
    INIT["/boot/init.js stock kernel"]
    BIN["/bin coreutils"]
  end
  HS --> MUX
  MUX --> CH1
  MUX --> CH2
  CH1 --> DISK
  DISK --> CTX
  INIT --> CTX
  BIN --> CTX

Two-drive and swarm path

How the personal drive sits beside the system image and how the booter reaches both after swarm replication (narrative: concepts — Two drives, concepts — Boot):

flowchart TB
  subgraph p2p [Swarm]
    T[Hyperswarm topic]
    M[Protomux bare-os-v1]
  end
  subgraph booter [Booter host]
    SD[SwarmDisk Corestore]
    VFS[VFS router]
  end
  subgraph drives [Hyperdrives]
    SYS[System drive read policy]
    PER[Personal drive home and .bare]
  end
  T --> M
  M --> SD
  SD --> SYS
  SD --> PER
  SYS --> VFS
  PER --> VFS
  VFS --> SH[Shell and /bin]

Boot sequence (logical order)

High-level order only — not every Protomux message or RPC. Text fallback (for man ingest and plain-text readers): the seeder publishes MBR block 0 and drive blocks on the swarm; the booter discovers peers, reads the MBR, opens and replicates the system Hyperdrive, opens or creates the personal Hyperdrive, builds ctx, then runs /boot/init.js. For bytes and message IDs, read Handbook ch.3 and the protocol reference.

sequenceDiagram
  participant Seeder
  participant Swarm as Hyperswarm_topic
  participant Booter
  participant Sys as System_Hyperdrive
  participant Per as Personal_Hyperdrive
  Seeder->>Swarm: publish_MBR_and_blocks
  Booter->>Swarm: discover_and_replicate
  Swarm-->>Booter: MBR_block_0
  Booter->>Sys: open_and_replicate
  Booter->>Per: open_or_create
  Booter->>Booter: build_ctx_and_run_boot_init

POSIX + P2P reading order

Read once in this order when you need the full contract picture; then use the consolidated dashboard as your bookmark.

Step	Focus	Human doc	Machine / generated
1	Declared stance	POSIX declared profile	posix-compliance-matrix.json
2	Dashboard	POSIX compliance dashboard	pretest → gen-posix-dashboard.mjs
3	Utilities + shell	Handbook ch.9	syscalls.example.json
4	Syscall facade	POSIX syscall facade map	bare-os-syscalls.schema.json
5	P2P vs POSIX boundary	Handbook ch.12	Capability words

Environment variables (full inventory, do not duplicate in prose): Environment and POSIX appendix.

Compared at a glance

	Bare OS	Classic OS image	Container on a host
Distribution	P2P Hyperdrive + swarm	ISO / image mirror	Registry pull
Mutable user state	Personal Hyperdrive	Local disk	Writable layers / volumes
Guest execution	ctx + VFS over drives	Kernel + real HW/VM	Namespaces + host kernel
POSIX	Declared profile + facade	Full kernel	Often libc + syscall pass-through

---

Contract spine (quick cross-links)

Normative and machine-readable contracts that should move together when behavior changes:

Surface	Role
POSIX declared profile	Narrative stance, non-goals, env gates (BARE_OS_POSIX_PROFILE_VERSION).
ctx API version	Guest-visible ctx semver in bare-os-ctx-api.js.
Protocol / feature bits	bare-os-protocol package version, kernel feature words, Protomux channel names.
Telemetry / audit	NDJSON and JSON Schema shards under docs/schemas/; handbook ops ch.7.
/proc and HRPC	Proc JSON schema bumps, disk.os allowlist, replication_operator_sketch versions.

flowchart LR
  P[POSIX profile + syscalls.json] --> M[posix-compliance-matrix.json]
  C[ctx API semver] --> CM[compatibility-matrix.md]
  PR[bare-os-protocol] --> FB[kernel feature bits]
  B["booter /proc builders"] --> HRPC[ctx.bareOsHrpcRequest table]
  K["/boot/init.js boot policy"] --> T[telemetry NDJSON]

Run npm run pretest after contract edits so generated dashboards and parity scripts stay aligned.

---

POSIX + P2P consolidated dashboard

Single entry point for declared POSIX-like behavior, machine-readable matrices, and P2P / capability alignment:

• Declared POSIX profile — normative narrative and non-goals.
• POSIX compliance dashboard — generated summary from posix-compliance-matrix.json (run npm run pretest / gen-posix-dashboard.mjs).
• POSIX Issue 7 traceability index — maps XBD/XSH/XCU to /proc, ctx, and handbook chapters.
• Holepunch lockfile drift dashboard — human table from report-holepunch-lockfile-drift.mjs (also npm run audit:holepunch-clones).
• POSIX utilities matrix (handbook) — Tier-1 /bin catalog and shell semantics.
• Syscall / socket bridge contract — ctx.bareOsSyscall and optional socket FD bridge.
• Capability words and compatibility matrix — ctx API and kernel feature-bit alignment.
• Feature roadmap (canonical JSON) and feature roadmap (human) — planned work vs shipped surfaces.

---

Maintainer quick path (build + parity)

When you change kernel/lib/init/, kernel/lib/boot/, kernel/lib/bare/, or kernel/bin/:

1. Run npm run build -w bare-os-coreutils and npm run build -w bare-os-bare-libs as needed.
2. Run npm run bundle:kernel (or full npm test, which bundles and verifies).
3. Keep packages/bare-os-seeder/kernel/ identical to kernel/ — scripts/verify-kernel-seeder-parity.mjs enforces this in pretest.

Details: scripts/README.md (maintainer build order), developer guide ch.7.

Choose your path

I want to…	Start here
Orient quickly (two drives, boot, P2P, POSIX)	Concepts
Run the seeder and booter and use the shell	User manual
Understand architecture, protocol, and design intent	Handbook
Extend /bin, scripts, Pear apps, or ctx	Developer guide
Look up paths, env vars, wire formats, matrices	Reference hub
Define a term or compare version fields	Glossary · Compatibility matrix
Vault / identity posture (operator)	Vault threat model
Fix a problem quickly	Troubleshooting router · FAQ
Edit docs in this repo	Contributing to documentation

flowchart LR
  subgraph roles [By role]
    Run[Run and use]
    Think[Understand design]
    Build[Extend and ship]
    Spec[Specify and verify]
  end
  subgraph trees [Doc trees]
    UM[users-manual]
    HB[handbook]
    DG[developer-guide]
    RF[docs/reference + architecture]
  end
  Run --> UM
  Think --> HB
  Build --> DG
  Spec --> RF
  HB --> RF
  DG --> RF

---

Documentation map

User manual (users-manual/)

Practical, sequential guide for operators.

Chapter	Topic
README	Paths through the docs, how trees relate
01 — What this is	Two drives, P2P image, experimental status
02 — Install	Clone, npm ci, monorepo layout
03 — Seeder and booter	Node vs Pear, two terminals
04 — Shell and PATH	Commands and scripts without full ctx depth
05 — Home, identity, vault	Guest, login, vault snapshots
06 — Help and man	man, help, where each doc tree lives
07 — Troubleshooting	Common failures, env vars, CI
08 — Further reading	Curated deep links

Handbook (handbook/)

Narrative spine: why and how the system fits together.

Chapter	Topic
00 — Preface	Thesis, security frame, contributors
01 — Introduction	Goals, vocabulary, clone-to-prompt
02 — Blueprints	Layers, trust, boot path
03 — Protocol and disk	MBR, swarm, Protomux, failure modes
04 — Booter runtime	ctx, VFS, shell, bridges
05 — Identity, vault, HDMS	Accounts, vault, mounts
06 — Kernel and binaries	/boot/init.js, coreutils
07 — Operations	CI, Pear, env, troubleshooting
08 — Git on Bare OS	isomorphic-git, HTTP modes
09 — POSIX, shell, VFS	Coverage and divergences
10 — Man pages and help	JSON DB, handbook ingest
11 — Kernel program and research	Roadmap context, capability words
12 — P2P stack vs POSIX	Hypercore, swarm, Protomux vs declared POSIX profile

Developer guide (developer-guide/)

How-to for code inside and around the image.

Doc	Topic
01 — Two runtimes	Host vs in-image execution
02 — ctx	Capability object map
03 — Kernel boot	start(ctx)
04 — User scripts and PATH	run(ctx, argv)
05 — Modules	No ESM on drive
06 — Extending /bin	Coreutils pipeline
07 — Apps beyond shell	initd, cron, delegates
08 — Testing	npm test, Pear dev
09 — Security	Trust boundaries
10 — Glossary and FAQ	Dev-focused Q&A
11 — Pear cookbook	Pear integration patterns
12 — Bare modules	ctx.bare, manifests
13 — Privacy and telemetry	Scrub lists, PII posture
Extras	Phase alignment, kernel program, naming, node→Bare map, ADRs

Reference and contracts (this tree)

Resource	Purpose
Reference README	Topic index (packages, env, data flow)
KERNEL_CONTRACT	Booter vs image, boot steps, ctx API pointer
POSIX_DECLARED_PROFILE	Issue 7–like contract: shell, XCU, VFS, proc “syscall” models
kernel-subsystems	Subsystem boundaries
ADRs	Architecture decisions
Audit baseline	Incomplete surfaces (classified)
OTA and bundles	Release packaging notes
Release checklist	Pre-tag steps
Schemas	Boot policy, telemetry, extension manifests
Themes	Terminal theme packs
Machine-readable data	Roadmap JSON, terminology allowlist
Holepunch catalog	Optional ctx.bare bundle metadata

Topic index (canonical reference per subject)

When updating behavior, edit the canonical row first; handbook, user manual, and developer guide should summarize and link here instead of copying versioned tables or env inventories.

Topic	Canonical spec / reference	Narrative (handbook)	Operator (users manual)	How-to (developer guide)
Environment variables	environment-and-posix-appendix.md	Ch. 7 — Operations	Ch. 7 — Troubleshooting	Ch. 11 — Pear cookbook
ctx / booter runtime	package-bare-os-booter.md, ctx-api-versioning.md, shell-completion-and-repl-editor.md	Ch. 4 — Booter runtime	—	Ch. 2 — ctx
Protocol / MBR / Protomux	package-bare-os-protocol.md	Ch. 3 — Protocol and disk	Ch. 1–3	—
Identity / vault / HDMS	vault-threat-model.md, package-bare-os-booter.md (guest /.bare policy)	Ch. 5	Ch. 5	Ch. 9 — Security
POSIX / syscalls / sockets	POSIX_DECLARED_PROFILE.md, posix-syscall-facade-map.md, syscall-socket-contract.md	Ch. 9	—	Ch. 8 — Testing
Kernel program / capability words	feature-roadmap.md, kernel-capabilities-index.md, kernel-program.md	Ch. 11–12	—	kernel-program.md
Tier-1 /bin / coreutils	package-bare-os-coreutils-and-ci.md, packages/bare-os-coreutils/lib/commands.mjs	Ch. 6–9	Ch. 4	Ch. 6 — Extending /bin

Contract bump checklist

When you change BARE_OS_CTX_API_VERSION, /proc JSON schemas, BARE_OS_PROTOCOL_* / package semver, BARE_OS_POSIX_PROFILE_VERSION, or kernel capability words, update every dependent artifact in one pass:

1. README.md and DOCUMENTATION.md if the version string or install story changes.
2. Handbook chapters touched by behavior (especially ch.3–4, 6, 9).
3. Users manual and Developer guide for operator or extension workflows.
4. docs/reference/compatibility-matrix.md and any affected topic pages under docs/reference/.
5. Package changelogs: packages/bare-os-booter/CHANGELOG.md, packages/bare-os-protocol/CHANGELOG.md when applicable.
6. docs/schemas/ and docs/architecture/POSIX_DECLARED_PROFILE.md when proc, telemetry, or POSIX profiles move.
7. kernel/etc/bare-os/syscalls.example.json and the seeder mirror after kernel contract edits; run node scripts/verify-kernel-seeder-parity.mjs.
8. Regenerate docs/reference/ctx-client-helper.generated.ts via root pretest ( gen-ctx-client-helper.mjs ).

---

Root stubs and Pear

• First run: Get started · Doc map: Sitemap.
• Legacy monolith map: DOCUMENTATION.md (points here and to reference).
• Pear channels and host env: PEAR-RUN.md.
• Repository quick start: README.md.

---

Contributing

Code and automation: scripts/README.md. Documentation style and verifiers: CONTRIBUTING-DOCS.md.