Raven Scott
44355f6924
- Add shell-glob.js (fnmatch, brace expansion gate, GLOB_* / DOTGLOB / STRICT_POSIX) - Tokenizer tracks u/s/d quote segments; expand argv, redirects, and `for … in` - Builtin `set -f` / `set +f`; richer `case` patterns via bareOsFnmatch - CI: verify-bundle-throws.mjs + bundle-throw-allowlist.json in pretest - VFS: symlink cycle detection (ELOOP); stat follow depth 64 - ctx.bareOsPathconf + bareOsSyscall pathconf; syscalls.json schemaVersion 2 + errnoHints - getconf: pathconf in BARE_OS_SYSCALL_OPS; _PC_*, _POSIX_THREAD_ATTR_STACKSIZE - Docs: handbook ch.9, environment appendix, user manual ch.4, release-checklist, scripts README - Tests: tokenize/glob cases in bare-os-booter test.js Keep posix-conformance-matrix.json bareOsSyscallOps in sync with getconf (add pathconf).
Bare OS — user manual
This manual is for people who want to run and use Bare OS: clone the repo, start a seeder and booter, work in the shell, and understand where your files and identity live. It is written in plain language and points to deeper material when you need it.
Bare OS is experimental research software, not a production operating system. It is licensed under Apache-2.0 (LICENSE).
On this page
Who should read this
You are in the right place if you want to:
- understand what Bare OS is without reading the full architecture story first;
- install dependencies, run the seeder and booter, and know which terminal does what;
- use the line shell, home directory, and guest versus logged-in sessions at a practical level;
- find
manpages and know where handbook, developer guide, and reference docs live.
If you are changing /bin, the booter, or the kernel image, use the developer guide after skimming this manual.
Three paths through the docs
I only want to try it. Read What this is, then Running seeder and booter, using the root README for the shortest copy-paste path.
I use it regularly. Add Shell, PATH, and scripts, Home, identity, and vault, and Help, man, and the documentation map.
I need to debug or operate it. Use Troubleshooting and operations and the handbook chapter on operations (Chapter 7 — Operations and development).
Chapters
- What this is — P2P image, two drives, why it exists, experimental status.
- Install and repository layout — clone,
npm ci, workspaces at a glance. - Running seeder and booter — Node versus Pear, two terminals, npm scripts.
- Shell, PATH, and scripts — how commands run without diving into the full
ctxAPI. - Home, identity, and vault — guest session,
login, vault snapshots, HDMS in brief. - Help, man, and the documentation map —
man,help, and where each doc tree fits. - Troubleshooting and operations — common failures, environment variables, where to read next.
- Further reading — curated links into the handbook and reference.
How this relates to other documentation
- Handbook tells the story: architecture, protocol, booter runtime, identity, POSIX surface, and roadmap. Start with the Preface if you want the full narrative.
- Developer guide explains how to build and extend software on the image:
run(ctx, argv), coreutils, testing, Pear integration. - docs/reference is the file-level reference: packages, environment variables, data flow, compatibility. Use it when you need exact paths or toggles.
- PEAR-RUN.md lists Pear channels, versioned
pear://links, and host environment notes for embedded Pear apps.
When this manual and another doc disagree on a detail, treat the handbook or reference as authoritative and open an issue if something is stale.
Quick glossary
These terms appear everywhere in the other trees; definitions here are practical, not formal specs.
- Hyperdrive — Content-addressed append-only log exposed as a familiar file tree; Bare OS stages the system image on one drive and keeps personal state on another.
- Seeder — Process that publishes the system drive (and MBR) to Hyperswarm so peers can replicate.
- Booter — Process that joins the swarm, opens drives, builds the guest VFS, and runs
/boot/init.js. - MBR — Small bootstrap block on the system drive that records discovery keys and version hints for the protocol; not a PC BIOS MBR.
- Guest — Unauthenticated session: safe default
HOME, no Ed25519 identity in the environment. ctx— The in-image capability object (VFS, env, subprocess helpers, optional Pear bridges). User manual mentions it lightly; the developer guide is the full map.
Validating what you read
Repository CI runs npm run pretest before tests: it checks kernel/seeder parity, capability contracts, relative .md links under docs/, handbook/, developer-guide/, scripts/, users-manual/, packages/, kernel/, and root README.md, DOCUMENTATION.md, PEAR-RUN.md, man coverage, compatibility-matrix strings, and more. The link checker skips packages/bare-os-seeder/kernel/** (a byte-identical copy of kernel/**) and the packages/bare-os-bare-libs/README.kernel-lib-bare.md template whose links are validated after copy into kernel/lib/bare/README.md. If you are about to trust a path or script name from the docs, grepping the repo or running pretest locally is the fastest sanity check.
Next: Chapter 1 — What this is