kernel — system image sources
Files in this directory are read from disk by the seeder (or copied into packages/bare-os-seeder/kernel/ for Pear) and written into the system Hyperdrive with no temporary directory on the host.
This README.md file only documents the tree layout in the repository; the seeder does not install it as **/README.md** on the image (so the guest root directory stays free of repo docs).
Documentation: Concepts — Boot · User manual · Handbook · Kernel image reference · Developer guide.
Staging map (seeder)
**init.js** —/boot/init.js**bin/<name>**—/bin/<name>**etc/...**—/etc/...**share/man/...**—/share/man/...**lib/bare/...**—/lib/bare/...(optional**ctx.bare**bundles; see**bare-os-bare-libs**)- Any other file —
/<relative path> **README.md(this file)** — (skipped — not copied to/README.md)
Contents
**init.js** — Kernel entry: must defineasync function start(ctx). Boot order:**/etc/os-release**→**/etc/motd**→ optional**/etc/bare-os/rc.profile.<profile>**(profile from**BARE_OS_BOOT_PROFILE**or first line of**/etc/bare-os/profile**; the booter mirrors the resolved name in**ctx.env.BARE_OS_BOOT_PROFILE_RESOLVED**and**/run/bare-os/boot_profile**) →**/etc/bare-os/rc**→**/etc/bare-os/rc.d/***(sorted; digit-prefixed names only; skip dotfiles,*~,README*,*.md; optional**BARE_OS_RC_D_SKIP**comma list and**prefix***patterns) → optional**/etc/bare-os/rc.local**→**/etc/bare-os/kernel.d/***(same rules as**rc.d**) → banner → when**BARE_OS_SKIP_REPL**, optional onboot lines from**BARE_OS_ONBOOT** or**/etc/bare-os/onboot**→**readLine/execLine**loop. Boot**execLine**errors in trusted snippets are logged; with**BARE_OS_BOOT_STRICT=1**or**true**, the first throw calls**requestBooterExit(1)**and stops later boot phases. Custom kernels may call**ctx.registerKernelShutdownHook(fn)**before initd disposers; use**ctx.bareOsRuntimeCaps**for limits, pseudo paths, and**features**([developer-guide/02-the-context-object.md](../developer-guide/02-the-context-object.md)).**bin/**— Tier-1 utilities built by bare-os-coreutils plus**sshd** /**bare-sshd**from bare-os-openssh (150 commands in**COREUTILS_COMMANDS**;**sshd**is listed for man/help but its concatenated script is emitted by the openssh package build, not coreutils**src/**). Each file is**runtime.js**+ optional preamble (**lib/md5.js**for**md5sum**,**lib/*-engine.js**for**sed**/**awk**,**jq-engine.js**,**lib/man-render.js**,**lib/edit-*.js**for**edit**/**nano**, lscolors for**ls**/**dircolors**, …) +**async function run(ctx, argv)**(no ESM**import**in**src/**).**/bin/nano**duplicates**/bin/edit**for familiarity; the shell’s default**nano→edit**alias uses the**edit**command name after expansion.**dir**/**vdir**invoke**ls**via**ctx.runBinCommand**.**lib/bare/**— Optional IIFE bundles +**manifest.json**for**ctx.bare**drive merge, built by bare-os-bare-libs. Same trust model as**bin/**(trusted seeded image).**share/man/man.json**— Merged manual database for**/bin/man**(built by**bare-os-coreutils**; see handbook ch.10).**etc/os-release**— Static OS metadata (NAME,VERSION, …).**etc/motd**— Optional message printed after**os-release**(distributors can customize).**etc/bare-os/banner**or**/etc/issue**— If present on the system drive, the default kernel prints one of these instead of the built-in session hint (unless**BARE_OS_SKIP_REPL**shortens the banner). Set**BARE_OS_BOOT_TRACE=1**or**true**for**[boot] phase: Nms**lines on stderr,**json**for**{"phase":"…","ms":n}**per phase, or**ndjson**for machine-readable lines with**sessionId**. Recovery:**BARE_OS_BOOT_MINIMAL**, granular**BARE_OS_BOOT_SKIP**, optional**BARE_OS_KERNEL_SELFTEST**(TAP via**BARE_OS_SELFTEST_FORMAT=tap**; includes**/proc/bare_os_resources**/**/proc/bare_os_features**checks), readiness via**ctx.bareOsPublishBootReady**→**/run/bare-os/ready**and**/run/bare-os/boot.json**(**phases**from the stock kernel plus**booterPhases**from the booter — see developer guide ch.2).**etc/bare-os/rc**— Optional boot snippet: one**execLine**per non-comment line (trusted).**etc/bare-os/rc.d/**— Optional extra snippets (basename must start with a digit), same line rules, run after**rc**in filename order. Human-oriented notes live in**.README**(a dotfile so legacy**init.js**never executes it).
Editing workflow
Do not edit kernel/init.js by hand. It is generated from kernel/lib/boot/*.js (sorted), kernel/lib/init/fragments/*.js (sorted), and kernel/lib/init/init-main.js via npm run bundle:kernel (scripts/bundle-kernel-init.mjs). CI and npm run verify:init-bundle fail when the file drifts. Edit the fragments under lib/boot/, lib/init/fragments/, and lib/init/ only, then bundle and rsync to packages/bare-os-seeder/kernel/ for Pear parity. See lib/init/STRUCTURE.md.
- Change sources under
kernel/orpackages/bare-os-coreutils/src/. - Run
npm run build -w bare-os-coreutilsto refreshkernel/bin/*. - Run
npm run build -w bare-os-bare-libswhen**packages/bare-os-booter/lib/bare-module-manifest.json** or bundle entries change. - Run seeder again to re-stage the drive (or use a fresh Corestore for a clean image).
Host boot perf: when **BARE_OS_BOOT_PERF_DETAIL=1**, the stock booter logs **bare_stdlib_merge_ns** after **maybeMergeBareFromDrive** (monotonic **hrtime** delta in nanoseconds) alongside guest **boot-perf.json** stages.
Pear bundles use the vendored tree under packages/bare-os-seeder/kernel/; keep it in sync by running the same builds before pear stage. Use **npm run maintainer:kernel-image** from the repo root for coreutils + bare-libs + init bundle + extensions index + parity verify (then **rsync -a --delete kernel/ packages/bare-os-seeder/kernel/** if the verifier reports drift). **npm test** runs **scripts/verify-kernel-seeder-parity.mjs**, **scripts/verify-ctx-api-feature-bits.mjs**, and **scripts/validate-example-schemas.mjs** (after **bare-os-coreutils** and **bare-os-bare-libs** builds) so the two trees match byte-for-byte, ctx semver / feature words stay wired, example JSON matches **[docs/schemas/](../docs/schemas/)**, and every **kernel/bin/*** file contains the **BARE_OS_BIN_API** pragma (coreutils **runtime.js** and hand-written stubs such as **systemctl** / **journalctl**).
Optional system image examples: **etc/bare-os/boot.allow.example** (copy to **boot.allow** when using host **BARE_OS_BOOT_ALLOWLIST=1**), **etc/bare-os/boot.policy.example.json** (install as **boot.policy.json** when using **BARE_OS_BOOT_POLICY=1**; v2 fields **maxExecLineDepth**, **denyEnvKeys**, **requireProcNodes**; v3 **requireKernelCapabilitiesExtendedSeedingPlatform**, **requireKernelCapabilitiesRlimitsDelegatesShell**, **allowedPearIpcChannels**, **denyVfsPrefixes**, **maxInitdRestartsPerUnit**; v4 **requireKernelCapabilitiesOfflineNetExtensions**, **denyExecLineBuiltins**, **allowedCtxMethods**; v9 **requireKernelCapabilitiesBareModuleCryptoStaging**, **requirePearRuntimeRange**, **denyBareModuleSpecifierPatterns**, **requireBareCryptoMin**, **denyKernelSyscalls**, **requirePearIpcMin**, **extensionSignerPinsV2**, **offlineLkgManifestMaxAgeSec**, **bootPhasesRequireProcIndexMinSchema**; v10 **requireKernelCapabilitiesPearInspectLoggerTls**, **requireBareBootMin**, **bootPhasesRequireLifecycleMinSchema**, **extensionSignerPinsV3**, …; JSON Schema: [docs/schemas/boot.policy.schema.json](../docs/schemas/boot.policy.schema.json)), **etc/bare-os/kernel.extensions.registry.example.json** (shape for **/proc/bare_os/extensions.json** schema 7), **etc/bare-os/boot-trace-line.example.json** and **etc/bare-os/telemetry-ndjson.example.json** (shape checks for CI), **etc/bare-os/rc.profile.full** (sample full profile referenced from **profile**), **etc/bare-os/crontab.example** (system-wide cron lines merged ahead of user **~/.crontab**), **etc/bare-os/timers/*.timer.example** (copy to **~/.config/bare-os/timers/*.timer** for **OnCalendar=**, **EveryMs=**, or **OnInactiveSec=** jobs). **kernel.ext.d** scripts register into **/proc/bare_os/extensions.json** when the booter provides **ctx.bareOsRegisterKernelExtensionRecord**.