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.

Who this is for

You want to drop a hello.js on your personal drive and run it from the shell without misunderstanding the execution model.
You plan to add or change a /bin utility and need the no-import contract 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) or start(ctx) and need a map of ctx.

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, *.js in 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, Holepunch bare-* 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-boot stages vs stock kernel/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.

License: Apache-2.0 — see LICENSE.

README.md

Bare OS — developer guide

On this page

Who this is for

Reading order

Related docs