Raven Scott
d286ce19b5
test(protocol): add deterministic MBR failover-key coverage docs(protocol): align package-bare-os-protocol version to 0.9.1 test(booter): add MBR corruption and wrong-topic smoke fixtures test(peer-seed): add strict pre-MBR bare_os.capabilities negotiation check feat(seeder): validate BARE_OS_SEED_REQUIRE_MBR_LABELS feat(seeder): validate BARE_OS_SEED_CAPABILITY_ATTESTATION_JSON schema docs(boot-policy): add requireProtocolPackageMin 0.9.1 example test(kernel): cover boot.policy denySeedRpcMethods behavior test(protocol): add app/cap/chat/meshdrop channel compatibility fixture test(swarm-disk): cover duplicate Protomux channel null-return path test(protocol): add 11-word kernelCapabilityWords round-trip fixture docs(schema): add mbr-layout schema and validate seeder examples test(protocol): add topicKey() golden hash fixture docs(trust): document block-0 trust assumptions in boot docs feat(seeder): add discovery.flushed readiness logging feat(booter): record peer discovery timings in boot-perf.json feat(integration): add local testnet mode to integration lab smoke test(booter): add Hyperswarm connection-budget env regression coverage test(booter): add swarm plus Corestore suspend/resume integration coverage feat(booter): mirror swarm ban events into host audit logs feat(booter): add direct-peer boot via BARE_OS_BOOT_JOIN_PEER_HEX feat(seeder): pass BARE_OS_SEED_MAX_PEERS to Hyperswarm feat(seeder): log drive.version and discoveryKey at startup test(booter): add Hyperdrive.checkout read-only boot probe coverage feat(booter): prefetch /boot/init.js before kernel handoff feat(booter): add optional /bin warm replication via downloadDiff feat(seeder): add manifestPaths SHA-256 generation in stage-kernel-tree test(peer-seed): cover helper-served block-0 after seeder exit feat(protocol): add Protomux cork batching for initial channel sends test(boot-graph): compare kernel/init labels with booter graph proc docs(boot-policy): add v9-v11 schema examples feat(release): add requireInitJsSha256 fixture generation step test(vfs): add BARE_OS_VFS_SYSTEM_RO_ALIAS coverage test(vfs): strengthen system-drive write-deny path coverage feat(identity): add personal-drive namespace export/import docs and tests test(booter): add guest-to-login warm cache invalidation regression test(vfs): add guest deny coverage for /.bare sensitive paths test(coreutils): add cross-drive mv failure injection coverage test(vfs): add .bareos_empty round-trip coverage across mkdir/rmdir/cp/git-fs test(vfs): add /dev/shm quota enforcement coverage test(proc): add /proc/bare_os/index.json sortedness and schema checks test(vfs): add warm read cache invalidation on replication growth docs(ctx): document bareOsInvalidateWarmReadCaches(reason) test(kernel): add BARE_OS_BOOT_DRY_RUN behavior coverage docs(posix): add dashboard rows for all COREUTILS_COMMANDS feat(curl): expand -w variables beyond http_code/url_effective/size_download feat(wget): mark -N timestamping as explicit unsupported error feat(curl): plumb mutual TLS cert/key intent to ctx.httpFetch metadata feat(shuf): add deterministic seed mode via BARE_OS_SHUF_SEED docs(sort): document -M month-sort as unsupported feat(grep): add explicit -E and -G mode handling test(sed): add Open Group Issue 7 golden fixtures test(awk): add getline VFS regressions for missing/repeat/boundary cases test(shell): add non-interactive here-doc coverage test(shell): add trap delivery coverage for synthetic PIDs/job IDs test(shell): add set -e compound-body behavior coverage docs(shell): strengthen read builtin opt-in guidance test(env): add Bare-runtime coverage for -S and --env-file docs(man): add examples for pathcap-verify pkg-swarm-index corestorectl test(identity): add account/vault backup-restore smoke coverage feat(audit): add tamper detection verification for audit chain rows test(peer-admission): cover strict empty allowlist deny behavior test(peer-admission): add denylist precedence over allowlist coverage test(peer-admission): add BARE_OS_PEER_REQUIRE_CAPS_JSON metadata checks docs(identity): add trusted-key rotation example for path capabilities feat(schema): tighten extensionSignerPinsV2-V4 hash validation test(delegate): add allowlist negative cases for curl/wget/git/hrpc/systemctl test(proc): extend /proc/self/environ redaction key coverage docs(security): add peer-assisted block-0 mirroring threat-model notes feat(bench): add boot budget trend output from real booter phases test(baretop): align fixture coverage with /proc snapshot key set test(metrics): validate /proc/bare_os/metrics.prom OpenMetrics shape docs(ops): add structured seeder NDJSON examples test(replication): add live stall-hint coverage for no_peers/length_unavailable/ok docs(release): add corestore-snapshot workflow to checklist docs(ops): add mirror-drive experiment utility to maintainer workflow test(booter): add monitor progress coverage for replication live sketch feat(seeder): validate DHT bootstrap address class JSON inputs docs(network): add HYPERSWARM_BOOTSTRAP testnet operator guidance chore(root): add deterministic test:integration script docs(ci): add local CI runbook for no-.github environments docs(release): add npm run test:bare after npm test feat(verify): add protocol docs/package version parity checker feat(verify): enforce feature-roadmap canonical path consistency feat(lockfile-drift): add tier-1 strict fail option for mismatches docs(lockfile-drift): add udx-native and blind-peering upgrade workflow notes docs(cli-parity): add bare-fetch upstream issue tracking row feat(bundle-health): generate per-tier bundle size regression thresholds feat(doc-contracts): verify handbook references to current proc schema versions feat(pretest): add validate-mermaid-syntax gate feat(probe): add bare-runtime top-25 critical command lane docs(protocol): update capability-word prose from bits..bits5 to current words docs(two-drive): document /tmp /var/log and account-prefix routing docs(security): add concise boot trust model page and links docs(dev-guide): add P2P lab cookbook section docs(dev-guide): add how-to for adding seed RPCs docs(dev-guide): add how-to for adding /proc/bare_os nodes docs(dev-guide): add /bin utility checklist for man/posix/build/parity/tests docs(user-manual): add short What BareOS is not section
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;bareOsReadBareTopSnapshotbatches/proc/bare_os/*reads forbaretopswarm-disk.js— Peer mux, MBR/read RPC, replication hookskernel-runner.js—runKernelFromSource,runBinCommand,resolveBinInPath(PATH on system drive);git/curl/wgetdelegatesvfs.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 includenano→edit**(TTY editor),**top→baretop**and**btop→baretop(session monitor)bare-os-theme-presets.js— Named themes (BARE_OS_THEME),applyBareOsThemeFromEnv,BARE_OS_COLOR_DEPTHdowngrades for REPL colorsbare-os-ipc.js— FIFOs, JSON-RPC (pushJson/takeJson, token + line limits), fan-out pub/sub,statsbare-os-abort.js—raceWithAbortAndTimeoutforexecLine/readLine/ VFS /runBinCommandbare-os-http-policy.js— Optional HTTP allow/deny lists for wrappedctx.httpFetchbare-os-ctx-api.js/bare-os-ctx.d.ts— Semantic version of thectxcontract + optional TypeScript shapesbare-os-runtime-caps.js— Frozen caps: pipeline limits,quotas, pseudo paths,featuresflags- **
bare-os-ctx-bare.js/bare-module-manifest.json/bare-module-manifest.data.mjs**—ctx.barehost imports + optional/lib/bare/drive bundle merge; Pear loads the manifest from generatedbare-module-manifest.data.mjs(see PEAR-RUN.md, Developer guide ch.12) identity-session.js/identity-account.js— Guest vs unlocked user,/.bare/account, vaulthdms-manager.js— Extra Hyperdrives, mounts under/mnt, Autopass pair/invitebare-initd.js— Service registry, unit drop-ins,units.dfragments, 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-holesaildefault chainbare-os-www-initd.js/bare-os-www-holesail.js— Initd unitbare-os-www: static**GET/HEAD**HTTP for**~/.www** (default127.0.0.1:8088); idempotent managed Holesail rowbare-www-<port>in~/.holesail/state.json(BARE_OS_HOLESAIL_STATE) with persistedseed/key(see handbook § bare-holesail)bare-os-ssh-holesail.js— Afterbare-opensshlisten, merges**bare-ssh-<port>**into the same managedstate.json(BARE_OS_SSH_HOLESAIL); post-login ensure frombare-user-session-stack.jsif sshd started beforebare-holesailbare-cron.js—/etc/bare-os/crontab,~/.crontab,~/.config/bare-os/timers/*.timer(OnCalendar=,EveryMs=,**OnInactiveSec=**/**Persistent=**), minute scheduler,ctx.execLinejobsbare-os-delegate-concurrent.js— Optional in-flight caps (BARE_OS_DELEGATE_MAX_CONCURRENT, per-kind**BARE_OS_DELEGATE_*_MAX_CONCURRENT**) around host delegatesrepl-session.js— Fish-style TTY line editor, syncedconsole, cleanup →stopBareInitdcompletion-engine.js— Tab completion context (parseCompletionContext), man/PATH/VFS/proc collectors, ranking,ctx.bareOsRegisterCompleterboot-splash.js— Centered TTY boot splash (responsive frame, bar, log); cursor hidden untilprepareForKernel()fish-readline.js— History, ghost text, Fish-style completion menu / keyscli-readline.js,resolve-stdio.js,debug-repl.js— Stdio and debug toolingpaths.js— Pear-safe package root and Corestore pathbare-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— OverridesdefaultLocalSeedCorestorePath(booter does not local-boot)BARE_OS_BOOT_TIMEOUT_MS— Total time to find peers + load kernel (default60000)BARE_OS_NO_SPLASH— Disable TTY splashBARE_OS_SKIP_REPL— Non-interactive kernel (readLine→ null)BARE_OS_FISH— Set0to disable fish-style editorBARE_OS_COMPACT_MENU—1/trueforces 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 ofbare-module-manifest.jsonvsbare-module-manifest.data.mjs- Root
npm run verify:manifest-data— ensures JSON and.data.mjsstay in sync (runs inpretest)
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.mjsis the authoritative/binname list