bare-os-booter
Pear / Bare application that boots from the network only: joins the same Hyperswarm topic as the seeder, reads MBR block 0 from peers, opens the system Hyperdrive (and a personal namespaced drive), replicates, then runs /boot/init.js with a rich ctx (VFS, shell, identity, HDMS, initd services).
There is no local seed fallback — a running seeder (or another peer with the image) must be reachable within BARE_OS_BOOT_TIMEOUT_MS.
Run
# repo root (links node_modules for Pear)
npm run os:booter
Or:
cd packages/bare-os-booter
node index.js
Major subsystems (lib/)
| Module | Role |
|---|---|
index.js |
Swarm, SwarmDisk, boot timeout, executeKernel, ctx assembly, boot/audit/env passthrough; bareOsReadBareTopSnapshot batches /proc/bare_os/* reads for baretop |
swarm-disk.js |
Peer mux, MBR/read RPC, replication hooks |
kernel-runner.js |
runKernelFromSource, runBinCommand, resolveBinInPath (PATH on system drive); git / curl / wget delegates |
vfs.js |
Two-drive routing; mkdir/rmdir (.bareos_empty), chmod, symlink, pseudo /proc//sys, watch, … |
shell.js |
Tokenize, pipelines, redirections, builtins (barerc, unset, readonly, umask, command, type, …), execShellLine, loadBarerc; default aliases include nano → edit (TTY editor), top → baretop and btop → baretop (session monitor) |
bare-os-theme-presets.js |
Named themes (BARE_OS_THEME), applyBareOsThemeFromEnv, BARE_OS_COLOR_DEPTH downgrades for REPL colors |
bare-os-ipc.js |
FIFOs, JSON-RPC (pushJson/takeJson, token + line limits), fan-out pub/sub, stats |
bare-os-abort.js |
raceWithAbortAndTimeout for execLine / readLine / VFS / runBinCommand |
bare-os-http-policy.js |
Optional HTTP allow/deny lists for wrapped ctx.httpFetch |
bare-os-ctx-api.js / bare-os-ctx.d.ts |
Semantic version of the ctx contract + optional TypeScript shapes |
bare-os-runtime-caps.js |
Frozen caps: pipeline limits, quotas, pseudo paths, features flags |
bare-os-ctx-bare.js / bare-module-manifest.json |
ctx.bare host imports + optional /lib/bare/ drive bundle merge |
identity-session.js / identity-account.js |
Guest vs unlocked user, /.bare/account, vault |
hdms-manager.js |
Extra Hyperdrives, mounts under /mnt, Autopass pair/invite |
bare-initd.js |
Service registry, unit drop-ins, units.d fragments, socket-activation, IdleSec= idle stop, ConditionPathExists= / AssertPathExists=, ReadinessPath / exec: polling, DAG snapshot /proc/bare_os/initd_graph.json, mobile suspend/resume order, startBareInitd, kernel-logger |
bare-cron.js |
/etc/bare-os/crontab, ~/.crontab, ~/.config/bare-os/timers/*.timer (OnCalendar=, EveryMs=, OnInactiveSec= / Persistent=), minute scheduler, ctx.execLine jobs |
bare-os-delegate-concurrent.js |
Optional in-flight caps (BARE_OS_DELEGATE_MAX_CONCURRENT, per-kind BARE_OS_DELEGATE_*_MAX_CONCURRENT) around host delegates |
repl-session.js |
Fish-style TTY line editor, synced console, cleanup → stopBareInitd |
boot-splash.js |
TTY boot progress UI |
fish-readline.js |
History, completion helpers |
cli-readline.js, resolve-stdio.js, debug-repl.js |
Stdio and debug tooling |
paths.js |
Pear-safe package root and Corestore path |
bare-os-pear-ipc-registry.js |
Well-known Pear IPC channel names; JSON at /proc/bare_os/pear_ipc.json |
Environment
| Variable | Meaning |
|---|---|
BARE_OS_HOST_DATA |
Base directory for host state (default ~/.bare-os) |
BARE_OS_BOOT_STORE |
Corestore directory (default ~/.bare-os/corestore/booter) |
BARE_OS_LOCAL_SEED |
Overrides defaultLocalSeedCorestorePath (booter does not local-boot) |
BARE_OS_BOOT_TIMEOUT_MS |
Total time to find peers + load kernel (default 60000) |
BARE_OS_NO_SPLASH |
Disable TTY splash |
BARE_OS_SKIP_REPL |
Non-interactive kernel (readLine → null) |
BARE_OS_FISH |
Set 0 to disable fish-style editor |
HYPERSWARM_BOOTSTRAP |
Optional comma-separated bootstrap nodes (HDMS / replication) |
Copied from host into the guest session when set (non-exhaustive; see environment variables reference and CHANGELOG.md): BARE_OS_PIPELINE_MAX_STAGES, BARE_OS_PIPELINE_MAX_BYTES, BARE_OS_PIPELINE_MAX_LINES, BARE_OS_SHELL_PARAM_EXPANSION, BARE_OS_BOOT_PROFILE, BARE_OS_ONBOOT, BARE_OS_BOOT_STRICT, BARE_OS_RC_D_SKIP, BARE_OS_BOOT_MINIMAL, BARE_OS_BOOT_SKIP, BARE_OS_BOOT_TRACE, BARE_OS_KERNEL_SELFTEST, BARE_OS_SELFTEST_FORMAT, BARE_OS_AUDIT, BARE_OS_AUDIT_JSON, BARE_OS_AUDIT_REDACT, BARE_OS_BOOT_ALLOWLIST, BARE_OS_EXEC_MAX_DEPTH, BARE_OS_EXEC_LINE_BUDGET_MS, BARE_OS_IPC_MAX_BYTES, BARE_OS_IPC_RPC_TOKEN, BARE_OS_IPC_FANOUT, BARE_OS_IPC_JSON_MAX_BYTES, BARE_OS_HTTP_ALLOWLIST, BARE_OS_HTTP_DENYLIST, BARE_OS_TLS_PIN_SHA256, BARE_OS_VFS_WATCH, BARE_OS_IMAGE_DIGEST, BARE_OS_TELEMETRY_NDJSON, BARE_OS_TELEMETRY_OTEL_JSONL, BARE_OS_PROC_POLL_MS, BARE_OS_DELEGATE_MAX_PER_MIN, BARE_OS_DELEGATE_AUDIT_ONLY, BARE_OS_PEAR_CHANNEL, BARE_OS_PEAR_RELEASE, BARE_OS_BARE_MODULES, BARE_OS_BARE_DRIVE_BUNDLES, TERM, COLORTERM, PEAR_CHANNEL.
Tests
npm test -w bare-os-booter
brittle-bare test.identity.js— crypto account codec (Bare)brittle-node test.js— Hyperdrive, VFS, shell, kernel runner, cron matchers, etc.
Pear staging
pear.stage includes hoisted ../../node_modules. Run scripts/ensure-pear-node-modules.mjs from the repo root before pear run so the app package sees symlinked deps (see root README).
See also
- Developer guide — Bare modules
- Handbook — Booter runtime
- Booter reference §12 —
packages/bare-os-coreutils/lib/commands.mjsis the authoritative/binname list