bare-operating-system/README.md

Bare operating system

License Node

Caution

Experimental research software — not a production OS. Peers, keys, vault data, and network exposure deserve the same caution you would give any crypto-heavy prototype.

Bare OS is a P2P-first system image: the operating tree lives on a Hyperdrive replicated over Hyperswarm and Protomux, not a single HTTP mirror. A seeder stages the kernel and /bin into the system drive and publishes the MBR; a booter discovers peers, replicates the image, attaches a personal drive for identity and mutable state, and runs /boot/init.js. After a successful boot, eligible booters can also mirror the same block 0 MBR and captured seed RPC hints for cold joiners (peer-assisted seeding; see the environment appendix and handbook chapter 3). The stack targets decentralized distribution alongside Holepunch-style runtimes (Bare / Pear).

New here? Read Get started (one page: clone → two terminals → what “success” looks like), then skim Concepts — Two drives.

Prerequisites (before first run)

• Node.js ≥ 20 and npm ci at the repository root.
• Bare CLI (npm i -g bare) for npm run os:seeder / npm run os:booter, or download rolling binaries from Gitea (see BINARY-RELEASE.md).
• Network: the booter must find a peer on the bare-os-v1 swarm topic within BARE_OS_BOOT_TIMEOUT_MS (default 60000 ms).

Canonical remote: https://git.ssh.surf/snxraven/bare-operating-system.git

60-second mental model

• System drive — replicated image: /boot, /bin, stock kernel, read-only policy for most tree.
• Personal drive — $HOME, /.bare, vault material, per-node history.
• Dev workflow — almost always two processes: seeder (canonical publisher) + booter (consumer, and optional helper for later cold joiners).
• Two runtimes — the host (Bare standalone / Node) implements ctx and the VFS; scripts on the drive run under the in-image eval model (not Node ESM on-disk). See Developer guide §1 — Two runtimes.

Try it

One-line installer (downloads rolling binaries from Gitea):

curl -fsSL https://install.bare-os.live | bash
# or from Gitea raw:
# curl -fsSL https://git.ssh.surf/snxraven/bare-operating-system/raw/branch/main/scripts/install.sh | bash

Non-interactive:

curl -fsSL https://install.bare-os.live | bash -s -- --both --yes

Or unpack a release tarball / pear install:

tar -xzf bare-os-booter-0.1.0-linux-x64.tar.gz
./bare-os-booter --no-updates

pear install pear://khtauzttriz8dpgrphj79rfy98iwoatqm59fnogtsdqk5f1kg6ao

From this repository:

git clone https://git.ssh.surf/snxraven/bare-operating-system.git
cd bare-operating-system
npm ci

Terminal A — seeder (publishes the canonical drive + MBR):

npm run os:seeder

Terminal B — booter (boots from peers; later may mirror block 0 when eligible):

npm run os:booter

Tip

npm run os:seeder and npm run os:booter run pear run --dev after linking hoisted workspace dependencies.

Tip

For a Node-only path (no Pear), see User manual — Chapter 3.

Full operations, environment variables, and troubleshooting: Handbook — Chapter 7 and Environment appendix.

Documentation

Start here	Role
Get started	Zero-to-prompt path with prerequisites and failure table
Documentation home	Role-based map, contract spine, POSIX + P2P dashboard
Documentation sitemap	How user manual, handbook, developer guide, and reference fit together
Concepts	Short evergreen pages: two drives, boot, swarm, identity, POSIX stance

Legacy router: DOCUMENTATION.md maps the old monolith sections to docs/reference/.

On this page: What you get · User manual · Handbook · Developer guide · Reference · POSIX surface · Protocol · Kernel parity · Contributing

What you get

• Two-drive model — read-only system image + writable personal namespace; VFS routes $HOME and /.bare/ to the personal drive.
• Tier-1 /bin — 186 POSIX-oriented utilities (authoritative list: COREUTILS_COMMANDS in packages/bare-os-coreutils/lib/commands.mjs; verify-man-coverage in pretest keeps man.json in sync), line shell with pipelines and redirects, sed/awk, man backed by merged JSON handbook + coreutils pages.
• Identity — Ed25519 account on the personal drive, guest vs unlocked session, encrypted vault snapshot (savevault / logout --save).
• Boot plumbing — initd/cron themes, synthetic /proc / /run / /sys, optional ctx.bare bundles from /lib/bare (Holepunch catalog workflow at repo root).
• Personal site (HTTP) — Initd bare-os-www serves static files from ~/.www on 127.0.0.1:8088 by default; managed Holesail can expose **bare-www-<port>** when enabled. Handbook — Chapter 4.
• SSH in the booter — Initd unit bare-openssh runs an SSH-2 server (bare-ssh2, vendored in [packages/bare-os-openssh](packages/bare-os-openssh)) bound to 127.0.0.1 by default; /bin/sshd delegates to ctx.bareOsRunSshdCli. Host keys live on the personal drive under **~/.config/bare-os/ssh/host/** (see man sshd / sshd_config). Set BARE_OS_SSH_BIND_ALL=1 on the host to widen ListenAddress when sshd_config still says 127.0.0.1; use BARE_OS_SSH_LISTEN_PORT to override the listen port (including 0 for an ephemeral port in tests).
• Protocol — Swarm topic + Protomux bare-os-v1, 512-byte MBR with Hyperdrive keys (BIOS magic). Seeder is the canonical source; eligible booted peers can mirror the same MBR for availability. Details: Handbook — Chapter 3 and Protocol reference.

Verifier-backed docs: root npm test runs pretest, which checks kernel/seeder parity, doc links, man coverage, POSIX profile triplet, compatibility-matrix strings, and more — see scripts/README.md.

Agent system — Markdown brain at ~/.agent/workspace

The in-image /bin/agent loads a Markdown workspace from **~/.agent/workspace/** on the personal Hyperdrive (canonical soul files: SOUL.md, AGENTS.md, IDENTITY.md, …). Defaults ship under /share/agent-workspace/ on the system image; on first run, if **~/.agent/workspace/SOUL.md** is missing, the agent seeds that tree from the share so every home gets a portable, git-friendly brain.

• Templates in git: packages/bare-os-coreutils/share/agent-workspace/ — copied to kernel/share/agent-workspace/ by npm run build -w bare-os-coreutils.
• Host sample prompt: npm run sample:agent-workspace — prints a concatenated preview from the repo share (no booter required).
• Skills: modular SKILL.md trees under ~/.agent/workspace/skills/ (optional ~/.agent/skills/**); /bin/agent appends a compact index to the system message and exposes the read_skill tool for full instructions. Seeded examples include bare-os-super-developer (ctx**, scripts, small apps).
• First-time config: agent --setup or agent --config runs a plain TTY wizard (owner name, agent label, API URL/key/model/provider) and seeds ~/.agent/workspace/ from /share/agent-workspace/ when SOUL.md is missing; --config is an alias for --setup.
• Runtime docs: seeded ~/.agent/README-agent.md after first seed; see also man agent and User manual — ch.4.

User manual

For run and use without reading full architecture first: users-manual/README.md — install, seeder and booter, shell, identity, man / help, troubleshooting.

Handbook

Narrative spine — why the system is shaped this way: handbook/README.md. Begin with Preface or Chapter 7 — Operations for CI and Pear.

Developer guide

How-to for start(ctx) / run(ctx, argv), extending /bin, testing, Pear, telemetry scrubbing: developer-guide/README.md.

Reference and contracts

• File-level reference — packages, environment appendix, data flow (legacy map: [DOCUMENTATION.md](DOCUMENTATION.md)).
• ctx API changelog — bareOsCtxApiVersion history.
• Compatibility matrix — protocol, feature-bits doc, ctx API, lifecycle/telemetry schema versions.

Glossary and help

Glossary · FAQ · Troubleshooting · Contributing to docs

POSIX surface

Handbook — Chapter 9. Declared profile 1.0.19 (BARE_OS_POSIX_PROFILE_VERSION) with ctx API 1.57.0 — POSIX declared profile and compatibility matrix. Machine-readable: docs/reference/posix-compliance-matrix.json (verified in pretest).

Protocol snapshot

• Swarm topic — crypto.hash(b4a.from('bare-os-v1'))
• Protomux channel name — bare-os-v1
• MBR — 512 bytes, magic BIOS, primary Hyperdrive key at byte offset 8, failover keys at offsets 40 and 72

Full wire layout: Handbook — Chapter 3 and protocol package reference.

Guest identity (short)

Default session is guest; login / logout, /.bare/account, guest /.bare read policy, legacy-root migration (BARE_OS_PERSONAL_ROOT_MIGRATE), and optional BARE_OS_PERSONAL_ACCT_PREFIX: booter reference, environment appendix, Handbook — Chapter 4.

Kernel image and Pear seeder parity

Canonical tree: kernel/; packages/bare-os-seeder/kernel/ must stay byte-identical.

• Full maintainer rebuild: npm run maintainer:kernel-image
• Sync only: npm run maintainer:sync-kernel-seeder (or …:bundle to re-bundle /boot/init.js first)

Details: Handbook — Chapter 7.

Contributing / CI

Root npm test runs workspace tests plus pretest hooks (kernel/seeder parity, verify-ctx-api-feature-bits, Pear import policy, doc link and contract checks). Maintainer script inventory: scripts/README.md.

Before a release tag, run npm run release-checklist ([scripts/release-checklist.mjs](scripts/release-checklist.mjs)) — see docs/release-checklist.md.

Observability (host env)

Optional guest paths BARE_OS_TELEMETRY_NDJSON, BARE_OS_TELEMETRY_OTEL_JSONL, and shorthand BARE_OS_TELEMETRY_OTEL=1 (defaults the OTel path) append capped JSON lines; records carry lifecycleSchemaVersion and telemetrySchemaVersion aligned with stock BARE_OS_LIFECYCLE_SCHEMA_VERSION (see compatibility matrix and environment appendix). Coalesced metrics: /proc/bare_os/metrics_live.json (poll BARE_OS_PROC_POLL_MS). Dev-only BARE_OS_DIAGNOSTICS_SUBSCRIBE=1 enables ctx.bareOsDiagnosticsSubscribe. Kernel extensions · JSON Schemas.

License

Apache-2.0 — open source software owned, operated, and engineered by HoneyPeer, LLC, a DeKalb, Georgia limited liability company. See LICENSE.