bare-operating-system/packages/bare-os-booter

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). After successful boot, eligible nodes can mirror the same block 0 and captured seed RPC snapshots for later cold joiners.

There is no local seed fallback — a running seeder (or another peer with the image, including an eligible booted helper) must be reachable within BARE_OS_BOOT_TIMEOUT_MS.

When to use: run the booter to consume the replicated image and start an interactive session (typical dev: second terminal with npm run os:booter). In peer-assisted mode it can also improve availability for other cold booters after it is up.

Documentation: Concepts — Two drives · Booter reference · Shell completion + Fish REPL · Developer guide §2 — ctx · CHANGELOG (bareOsCtxApiVersion).

Run

# repo root (links node_modules for Pear)
npm run os:booter

Or:

cd packages/bare-os-booter
node index.js

Major subsystems (lib/)

• 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 / bare-module-manifest.data.mjs** — ctx.bare host imports + optional /lib/bare/ drive bundle merge; Pear loads the manifest from generated bare-module-manifest.data.mjs (see PEAR-RUN.md, Developer guide ch.12)
• 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-os-www → bare-holesail default chain
• bare-os-www-initd.js / bare-os-www-holesail.js — Initd unit bare-os-www: static **GET/HEAD** HTTP for **~/.www** (default 127.0.0.1:8088); idempotent managed Holesail row bare-www-<port> in ~/.holesail/state.json ( BARE_OS_HOLESAIL_STATE ) with persisted seed / key (see handbook § bare-holesail)
• bare-os-ssh-holesail.js — After bare-openssh listen, merges **bare-ssh-<port>** into the same managed state.json ( BARE_OS_SSH_HOLESAIL); post-login ensure from bare-user-session-stack.js if sshd started before bare-holesail
• 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
• completion-engine.js — Tab completion context (parseCompletionContext), man/PATH/VFS/proc collectors, ranking, ctx.bareOsRegisterCompleter
• boot-splash.js — Centered TTY boot splash (responsive frame, bar, log); cursor hidden until prepareForKernel()
• fish-readline.js — History, ghost text, Fish-style completion menu / keys
• 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

• 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
• BARE_OS_COMPACT_MENU — 1 / true forces inline tab cycling (no dropdown menu)
• 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_PIPELINE_ABS_MAX_BYTES, BARE_OS_PIPELINE_ABS_MAX_LINES, BARE_OS_SHELL_STREAMING, BARE_OS_SHELL_STREAMING_MULT, BARE_OS_STREAMING_MULTIPLIER, 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_TIMER_BUDGET_MS, BARE_OS_IPC_MAX_BYTES, BARE_OS_IPC_MAX_CHANNELS, BARE_OS_POSIX_MQ_MAX_MSGS, BARE_OS_POSIX_MQ_MSG_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_VFS_MAX_OPEN, BARE_OS_IMAGE_DIGEST, BARE_OS_TELEMETRY_NDJSON, BARE_OS_TELEMETRY_OTEL_JSONL, BARE_OS_TELEMETRY_OTEL, 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.; includes parity of bare-module-manifest.json vs bare-module-manifest.data.mjs
• Root npm run verify:manifest-data — ensures JSON and .data.mjs stay in sync (runs in pretest)

Pear staging

pear.stage.include is node_modules (flat mirror of the repo root hoist under this package, via scripts/ensure-pear-node-modules.mjs) so Bare resolves **node_modules/<pkg>** in released bundles. Run that script from the repo root before pear run (see root README). After changing bare-module-manifest.json or running sync:bare-manifest, confirm npm run verify:manifest-data passes, then **pear stage / pear release** so Pear ships an up-to-date bare-module-manifest.data.mjs.

See also

• Developer guide — Bare modules
• Handbook — Booter runtime
• Booter reference §12 — packages/bare-os-coreutils/lib/commands.mjs is the authoritative /bin name list