bare-operating-system/kernel

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 define async 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 (153 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/sha224.js** for **sha224sum**, **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.

1. Change sources under kernel/ or packages/bare-os-coreutils/src/.
2. Run npm run build -w bare-os-coreutils to refresh kernel/bin/*.
3. Run npm run build -w bare-os-bare-libs when **packages/bare-os-booter/lib/bare-module-manifest.json** or bundle entries change.
4. 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**.

See also

• Handbook — Kernel and userspace
• Handbook — POSIX utilities, shell, VFS
• Kernel image reference §9