Raven Scott
6f923f72d1
- Hyperswarm connection caps (env + /proc + disk.os replication_operator_sketch) - Protomux operator metrics schema; warm-cache invalidation on replication - ctx.bareOsSyscall nanosleep; socket bridge getsockopt/setsockopt (keepalive/nodelay) - Extension signer pin verification before kernel.ext.d scripts; ctx/DTS updates - Structured seeder logging (BARE_OS_SEED_LOG_*); release-checklist holepunch drift - POSIX profile/matrix/conformance lists + handbook/env appendix/kernel-extensions - Coreutils printf golden tests; sync kernel ↔ seeder parity after bundle
Bare OS — developer guide
Welcome. This guide is the how-to companion for writing software on and for Bare OS: scripts that run inside the replicated system image, utilities under /bin, the session kernel, and—when you need full JavaScript modules—the host Pear packages that implement the booter and seeder.
The documentation home maps every tree plus the shared glossary, FAQ, troubleshooting router, and contributing to docs. The handbook explains why the system is shaped the way it is (Hyperdrive, two drives, swarm boot). The docs/reference inventory lists where every file lives. The user manual helps people run the system before they extend it. This guide focuses on what you actually type: entrypoint signatures, the ctx object, why import does not work in drive-resident scripts, and how the coreutils build turns sources into /bin commands.
This project is experimental research software. APIs described here follow the current code in packages/bare-os-booter and packages/bare-os-coreutils; when in doubt, read the cited paths.
ctx API versions: see packages/bare-os-booter/CHANGELOG.md for bareOsCtxApiVersion history and booter alignment. TypeScript-oriented authors can reference lib/bare-os-ctx.d.ts.
Feature-bit governance: ADR 001 — Kernel feature bit governance.
Capability map: docs/reference/kernel-capabilities-index.md.
Contract checks: changing bareOsCtxApiVersion or stock kernel feature bits should keep scripts/verify-ctx-api-feature-bits.mjs green (invoked from root pretest).
Architecture contract (boundaries): docs/architecture/KERNEL_CONTRACT.md — booter vs guest image, disk.os RPC, boot step IDs.
Kernel source set: docs/reference/kernel-extensions.md — first-party paths (kernel/init.js, kernel/lib/boot, built /bin) vs vendored kernel/lib/bare/bundles (Holepunch IIFEs), CI allowlists, and seeder parity. Hand-authored code must stay free of incomplete markers; bundles are gated by verify-bundle-markers.mjs, verify-bundle-throws.mjs ( new Error messages with not implemented / abstract-base-class semantics — see docs/audit/bundle-throw-allowlist.json), and sanitize-bare-bundles.mjs. Prefer shrinking the throw allowlist via upstream bundle refreshes over silent drift.
Local Holepunch mirror: run npm run audit:holepunch-clones to refresh holepunch-clone-sync-report.json, holepunch-lockfile-drift.json, and NDJSON summaries (manifest names vs clones + workspace lockfile semver vs clone package.json). Root pretest runs verify-holepunch-clone-drift.mjs against basenames listed in docs/audit/holepunch-drift-repos.json (empty repos[] = no-op). Regenerate the maximal npm catalog with node scripts/gen-bare-holepunch-catalog.mjs (or npm run gen:bare-catalog), then npm run sync:bare-manifest — see scripts/README.md.
On this page
Who this is for
- You want to drop a
hello.json your personal drive and run it from the shell without misunderstanding the execution model. - You plan to add or change a
/binutility and need the no-importcontract and build steps. - You are modifying the booter or seeder Pear apps and need to separate “host ESM” from “in-image
AsyncFunction.” - You are debugging
async function run(ctx, argv)orstart(ctx)and need a map ofctx.
Reading order
- 01 — Two runtimes: host vs in-image — Pear/Node packages vs Hyperdrive JS evaluated with
AsyncFunction; trust boundaries. - 02 — The context object (
ctx) —vfs,drive,console, identity hooks,execLine,runBinCommand, … - 03 — Kernel:
/boot/init.js—async function start(ctx); readline loop; calling the shell. - 04 — User scripts and PATH resolution —
run(ctx, argv), shebangs,*.jsin cwd,./paths,/bin. - 05 — Modules and
import— Why ESM does not apply to in-image scripts; bundling and alternatives. - 06 — Extending
/bin(coreutils) —commands.mjs,build.mjs, preamble, man pages. - 07 — Apps beyond the shell — What an “app” means here; initd, cron, git, custom kernels (overview).
- 08 — Testing and debugging —
npm test, Brittle, Pear dev, common failure modes. - 09 — Security and trust — System vs personal drive; eval boundaries.
- 10 — Glossary and FAQ — Quick definitions; frequent questions.
- 11 — Kernel + Pear cookbook — Boot allowlist, timers, socket IPC,
vfs.watch, HDMS hooks, Git-in-Pear, release metadata. - 12 — Bare modules and Pear ecosystem —
ctx.bare, manifest, drive bundles, Holepunchbare-*mirror vs guaranteed keys. - 13 — Privacy, telemetry, and PII — Scrub lists for NDJSON / OTel mirrors; non-secret posture.
- Node → Bare module map — Guest-safe replacements for
node:*built-ins (bare-crypto,bare-module, …). - bare-boot vs kernel phases — Conceptual map: Holepunch
bare-bootstages vs stockkernel/init.js. - Kernel program (governed expansion) — Governance, boot hooks,
/proc/bare_os/kernel_program.json, Bare stack pointers, 200-item roadmap batches. - Naming conventions — First-party vs vendored trees,
ctx/ env / proc naming. - Naming migrations — Legacy aliases and deprecation windows for boot hooks and policy keys.
- Architecture decision records (ADRs) — Contract decisions and templates.
- Kernel doctor / kernel-explain conventions — Structured diagnostic output.
Related docs
- Handbook home
- User manual
- Chapter 4 — Booter runtime
- Chapter 6 — Kernel and binaries
- Chapter 7 — Operations and development
- Chapter 9 — POSIX utilities and shell
- Chapter 11 — Kernel + Pear cookbook
- Chapter 12 — Bare modules and Pear ecosystem
- bare-os-coreutils README
- bare-os-booter README
License: Apache-2.0 — see LICENSE.