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 handbook explains why the system is shaped the way it is (Hyperdrive, two drives, swarm boot). The DOCUMENTATION.md inventory lists where every file lives. 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.
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
| Chapter | Topic |
|---|---|
| 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 |
Related docs
- Handbook home
- Chapter 4 — Booter runtime
- Chapter 6 — Kernel and binaries
- Chapter 7 — Operations and development
- Chapter 9 — POSIX utilities and shell
- bare-os-coreutils README
- bare-os-booter README
License: Apache-2.0 — see LICENSE.