http server updates and docs
This commit is contained in:
Raven Scott
@@ -87,6 +87,7 @@ Full operations, environment variables, and troubleshooting: [Handbook — Chapt
|
||||
- **Tier-1 `/bin`** — **157** POSIX-oriented utilities (authoritative list: `**COREUTILS_COMMANDS`** in `[packages/bare-os-coreutils/lib/commands.mjs](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](handbook/04-the-booter-runtime.md#bare-os-www-static-http-for-www).
|
||||
- **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). Details: [Handbook — Chapter 3](handbook/03-protocol-and-disk.md) and [Protocol reference](docs/reference/package-bare-os-protocol.md).
|
||||
|
||||
|
||||
@@ -71,7 +71,7 @@ Use **`execLine`** when you want users to type natural shell commands from your
|
||||
1. **Keep the loop async**—never block on synchronous host APIs that might hang the Pear app.
|
||||
2. **Catch errors** around `execLine` so a typo does not tear down the whole session unless you want that.
|
||||
3. **Do not assume `import`**—the kernel source is the same `AsyncFunction` model as `/bin` (Chapter 1).
|
||||
4. To add **startup services**, prefer hooks already wired in the booter (**`startBareInitd`**) or a small kernel that calls **`runBinCommand`** after banner—see [Chapter 7](07-apps-beyond-the-shell.md).
|
||||
4. To add **startup services**, prefer hooks already wired in the booter (**`startBareInitd`**)—stock units include **`bare-os-www`** (loopback HTTP for **`~/.www`**, see [Handbook ch.4](../handbook/04-the-booter-runtime.md#bare-os-www-static-http-for-www))—or a small kernel that calls **`runBinCommand`** after banner; see [Chapter 7](07-apps-beyond-the-shell.md).
|
||||
5. To run code when the session ends, use **`ctx.registerKernelShutdownHook(fn)`** (runs before initd disposers); see [Chapter 2 — `ctx`](02-the-context-object.md).
|
||||
6. After **`login`**, **`~/.barerc`** is reloaded automatically via **`applyUnlockedEnv`**—see [Handbook — Identity](../handbook/05-identity-vault-and-hdms.md). The stock **`init.js`** does not re-print the boot banner; use **`onIdentityUnlocked`** or a custom kernel loop if you want that.
|
||||
|
||||
|
||||
@@ -11,6 +11,7 @@ This chapter ties the Hyperdrive-resident kernel ([`kernel/init.js`](../kernel/i
|
||||
## Init, timers, and sockets
|
||||
|
||||
- **bare-initd** — User drop-ins under `~/.config/bare-os/units/<name>.unit` support `SocketActivationIpc=<fifo>`; the unit’s `start` runs after the first byte is read on that logical FIFO under `/run/bare-os/ipc/…`. Optional `IdleSec=N` (with `stop`) stops the unit after N seconds without further IPC traffic; optional fragments `~/.config/bare-os/units.d/<name>/*.conf` merge before `~/.config/bare-init/units/` overrides. `ReadinessPath=` may be `exec:<execLine>` for a bounded readiness gate. **`ConditionPathExists=`** skips start when a VFS path is missing; **`AssertPathExists=`** fails the unit when missing (systemd-like, bounded absolute paths). **`ConditionPathIsDirectory=`** / **`AssertPathIsDirectory=`** do the same for directories (via **`vfs.lstat`**). Inspect the live DAG at **`/proc/bare_os/initd_graph.json`** (same payload as **`initd_dag.json`**, optional **`dot`** field).
|
||||
- **bare-os-www** — Stock initd serves **`GET`/`HEAD`** from **`~/.www`** on **`127.0.0.1:8088`** by default; **`bare-holesail`** starts after it so managed **`bare-www-<port>`** rows reach the listener. Handbook [ch.4 § bare-os-www](../handbook/04-the-booter-runtime.md#bare-os-www-static-http-for-www).
|
||||
- **Timers** — Files in `~/.config/bare-os/timers/*.timer` (max **8**) with a `[Timer]` section: either `OnCalendar=` (five cron fields) + `ExecLine=` on the same minute tick as `~/.crontab`, or `EveryMs=` (**1000**–**86400000**) + `ExecLine=` on a fixed `setInterval`, or **`OnInactiveSec=`** to run after the last timer-triggered finish plus an idle gap (one-shot or repeating; **`Persistent=`** keeps state across sessions where implemented). Optional `JitterSec=` spreads the first (or periodic) `execLine` within **0…N** seconds. Copy from `/etc/bare-os/timers/*.timer.example` on the system image when present.
|
||||
- **System cron** — Optional image file `/etc/bare-os/crontab` (see [crontab.example](../kernel/etc/bare-os/crontab.example)) is merged with user crontab entries. Lines may use `@reboot` + command (once per `bare-cron` start) and optional `JitterSec=N` prefix on the command for calendar lines.
|
||||
|
||||
|
||||
@@ -10,7 +10,7 @@ This document is the **single overview** of how the Bare OS “kernel” is spli
|
||||
| **VFS + policy** | Booter | `createVfs`, path classes, mounts, synthetic `/proc`; optional read-only **system** alias via **`BARE_OS_VFS_SYSTEM_RO_ALIAS`** (see `vfs.js`) |
|
||||
| **Identity / vault** | Booter + bins | Session env, account file, `login` / `savevault` flows |
|
||||
| **POSIX-like IPC** | Booter | In-memory FIFOs under **`/run/bare-os/ipc/<name>`** (**`bare-os-ipc.js`**); **`mq_open` / `mq_send` / `mq_receive`** via **`ctx.bareOsSyscall`** map to **`bareOsIpc`** priority queues (**higher `prio` first**, then FIFO by enqueue **`seq`**) with **`maxmsg`** / **`maxBytes`** caps — distinct from FIFO byte streams. Telemetry: **`bareOsIpc.stats().posixMessageQueues`** (schema **2**). |
|
||||
| **Init / services** | Booter | `bare-initd`, `systemctl` delegate, unit files |
|
||||
| **Init / services** | Booter | `bare-initd`, `systemctl` delegate, unit files — stock units include **`kernel-logger`**, **`bare-os-www`** (loopback static HTTP for **`~/.www`**, default port **8088**), **`bare-holesail`**, **`bare-cron`**, **`bare-openssh`**, **`bare-os-chat`**, … |
|
||||
| **Guest shell + `/bin`** | Image + booter | Hyperdrive-resident scripts; host delegates for selected CLIs |
|
||||
| **Extensions** | Image | `kernel.ext.d`, manifests; resolver in booter |
|
||||
| **Peer search / OS RPC** | Booter | `disk.os` after initd (`bare-os-disk-os-bridge.js`); optional **`BARE_OS_VFS_HYPERBLOBS_DEDUP`** surfaces **non-secret** dedup hints via **`BARE_OS_HYPERBLOBS_STATS_JSON`** merged into **`replication_operator_sketch`**; optional **`BARE_OS_CORESTORE_STATS_JSON`** merges **`corestoreOperatorSketch`**; **`corestoreSnapshotUxHint`** compares snapshot vs stats env JSON (**schema 7** response). Guest does not run **`hyperblobs`** / Corestore internals. |
|
||||
|
||||
@@ -7,7 +7,8 @@ This document is the **boundary map** for the Bare operating system runtime: whi
|
||||
| Subsystem | Role | Canonical modules |
|
||||
| --- | --- | --- |
|
||||
| **boot** | Swarm join, MBR, Hyperdrive replication, timeout, offline LKG | [`packages/bare-os-booter/index.js`](../../packages/bare-os-booter/index.js), [`bare-os-kernel-loader.js`](../../packages/bare-os-booter/lib/bare-os-kernel-loader.js), [`bare-os-lifecycle-manager.js`](../../packages/bare-os-booter/lib/bare-os-lifecycle-manager.js) |
|
||||
| **vfs** | Two-drive routing, pseudo `/proc`/`/sys`/`/run`/`/dev`, policy | [`vfs.js`](../../packages/bare-os-booter/lib/vfs.js), [`vfs-posix-meta.js`](../../packages/bare-os-booter/lib/vfs-posix-meta.js) |
|
||||
| **vfs** | Two-drive routing, pseudo `/proc`/`/sys`/`/run`/`/dev`, policy; optional **`$HOME/.www` → `/mnt/www`** when HDMS label **`www`** is mounted | [`vfs.js`](../../packages/bare-os-booter/lib/vfs.js), [`vfs-posix-meta.js`](../../packages/bare-os-booter/lib/vfs-posix-meta.js) |
|
||||
| **initd services** | Stock **`bare-initd`** units (logger, static **`~/.www`**, Holesail, cron, SSH, …) | [`bare-initd.js`](../../packages/bare-os-booter/lib/bare-initd.js), [`bare-os-www-initd.js`](../../packages/bare-os-booter/lib/bare-os-www-initd.js), [`bare-holesail.js`](../../packages/bare-os-booter/lib/bare-holesail.js), [`bare-cron.js`](../../packages/bare-os-booter/lib/bare-cron.js), [`bare-openssh.js`](../../packages/bare-os-booter/lib/bare-openssh.js) |
|
||||
| **process** | Synthetic process table, jobs/shell coordination | [`bare-os-process-table.js`](../../packages/bare-os-booter/lib/bare-os-process-table.js), [`shell.js`](../../packages/bare-os-booter/lib/shell.js) |
|
||||
| **ipc** | FIFOs, JSON-RPC, fan-out | [`bare-os-ipc.js`](../../packages/bare-os-booter/lib/bare-os-ipc.js) |
|
||||
| **net** | Hyperswarm, Protomux, peer disk I/O | [`swarm-disk.js`](../../packages/bare-os-booter/lib/swarm-disk.js), [`bare-os-swarm-connection-manager.js`](../../packages/bare-os-booter/lib/bare-os-swarm-connection-manager.js) |
|
||||
|
||||
@@ -29,6 +29,7 @@
|
||||
- A **line shell** backed by **157** Tier-1 utilities under `/bin` (see [`packages/bare-os-coreutils/lib/commands.mjs`](../packages/bare-os-coreutils/lib/commands.mjs); **`sshd`** is built by **`bare-os-openssh`**).
|
||||
- Two **Hyperdrives** mounted into one VFS: a **read-mostly system** image replicated from peers, and a **writable personal** drive for `$HOME`, `/.bare`, and similar paths. Short explainer: [Concepts — Two-drive model](concepts/two-drive-model.md).
|
||||
- A running **`/boot/init.js`** “kernel” and host-built **`ctx`** — not a hardware OS. See [User manual — Chapter 1](../users-manual/01-what-this-is.md).
|
||||
- A stock **loopback web root** — initd **`bare-os-www`** serves **`~/.www`** on **`127.0.0.1:8088`** by default (**GET**/**HEAD** only); optional managed **Holesail** row **`bare-www-<port>`** can tunnel it. [Handbook — Chapter 4](../handbook/04-the-booter-runtime.md#bare-os-www-static-http-for-www).
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -18,6 +18,8 @@ Short definitions for terms used across the user manual, handbook, developer gui
|
||||
|
||||
**Booter boot steps** — Canonical milestones: **`vfs`** → **`ctx`** → **`repl`** → **`initd`** → **`kernel_invoke`** (see [architecture/KERNEL_CONTRACT.md](architecture/KERNEL_CONTRACT.md) and `packages/bare-os-booter/lib/bare-os-boot-phases.js`).
|
||||
|
||||
**`bare-os-www`** — Initd static HTTP server for **`~/.www`** on **`127.0.0.1`** (default port **8088**); pairs with managed **Holesail** for a stock **`bare-www-<port>`** tunnel. Handbook: [Chapter 4 — bare-os-www](../handbook/04-the-booter-runtime.md#bare-os-www-static-http-for-www).
|
||||
|
||||
**Capability words** — Structured feature masks on **`bare_os.capabilities`** RPC and under **`/proc/bare_os_features`**. Described in [compatibility-matrix.md](reference/compatibility-matrix.md) and [kernel-capabilities-index.md](reference/kernel-capabilities-index.md).
|
||||
|
||||
**Corestore** — Storage backend for Hypercores/Hyperdrives on the host; default locations often under **`~/.bare-os/`**. Env vars: [environment-and-posix-appendix.md](reference/environment-and-posix-appendix.md).
|
||||
|
||||
@@ -239,6 +239,10 @@ The list below is one **bullet per variable** in the form **name — component
|
||||
- `BARE_OS_CHAT_GOSSIP_TTL` — Booter — Optional **`0`–`32`** relay hop budget for unseen chat events (**default `4`**).
|
||||
- `BARE_OS_CHAT_HISTORY_MAX` — Booter — Ring buffer depth for recent chat records (**default `512`**, range **`16`–`10000`**).
|
||||
- `BARE_OS_CHAT_MAX_BODY_BYTES` — Booter — Max UTF-8 body bytes per **`event`** frame (**default `4096`**).
|
||||
- `BARE_OS_WWW_INITD` — Booter — When **`0`** / **`false`**, skips registering the **`bare-os-www`** initd unit (stock default: unit **on**).
|
||||
- `BARE_OS_WWW_PORT` — Booter — TCP port for the loopback static HTTP server (default **`8088`**; must match the auto-managed Holesail entry when **`BARE_OS_WWW_HOLESAIL`** is on).
|
||||
- `BARE_OS_WWW_HOST` — Booter — Bind address for **`bare-os-www`** (default **`127.0.0.1`**; **`0.0.0.0`** exposes the port on all interfaces — use only with care).
|
||||
- `BARE_OS_WWW_HOLESAIL` — Booter — When **`0`** / **`false`**, skips idempotently merging **`bare-www-<port>`** into **`~/.holesail/state.json`** after the HTTP server listens (stock default: **on** so managed **`bare-holesail`** can expose the site).
|
||||
- `BARE_OS_COLLAB_SESSION_NDJSON` — Booter — When **`1`** / **`true`**, host boot trace may append collaboration session lines (non-secret peer counts) via swarm-disk logging.
|
||||
- `BARE_OS_PHYS_PAGES_HINT` — Booter — Optional integer string for **`getconf _SC_PHYS_PAGES`** via **`ctx.bareOsGetconfSysconf`** (default **`524288`** when unset).
|
||||
- `BARE_OS_SHELL_HEREDOC_MAX_BYTES` — Booter — When **`BARE_OS_SHELL_POSIX_MODE`** is on, caps here-document body size (default **`262144`**, max **2 MiB**).
|
||||
|
||||
@@ -64,7 +64,7 @@ See also [Kernel subsystem map](../architecture/kernel-subsystems.md) and [ADR 0
|
||||
- **`applyLogout({ save? })`** — optional **`save`** runs encrypted vault snapshot first (see `identity-session.js`).
|
||||
- **`saveVault()`** — encrypt personal-drive files into `/.bare/vault/` (skips `/.bare`, `bin`, `boot`, history paths).
|
||||
- **`registerKernelShutdownHook(fn)`** — register async/sync teardown before **`stopBareInitd`** when the REPL session cleans up.
|
||||
- After **`createKernelReplSession`**: wires **`readLine`**, **`console`**, **`execLine`**, **`suspendReplForSubprocess`** / **`resumeReplAfterSubprocess`**, then **`await startBareInitd(ctx)`** (services such as kernel log mirroring).
|
||||
- After **`createKernelReplSession`**: wires **`readLine`**, **`console`**, **`execLine`**, **`suspendReplForSubprocess`** / **`resumeReplAfterSubprocess`**, then **`await startBareInitd(ctx)`** (stock units include **`kernel-logger`**, **`bare-os-www`** — loopback static HTTP for **`~/.www`** — **`bare-holesail`**, **`bare-cron`**, **`bare-openssh`**, **`bare-os-chat`** when enabled, …).
|
||||
- Sets **`disk.os`** **after initd** with **`createBareOsDiskOsBridge`** (**`searchLocal`** with optional path manifest, whitelisted **`execRpc`** / **`bare_os.*`**, **`disk_os_hints`** schema **3**, **`replication_operator_sketch`** schema **7**, cap-gated **`replication_operator_intent`** when **`BARE_OS_DISK_OS_OPERATOR_INTENT_RPC=1`**) — peers use **`SwarmDisk`** messages **3–6**; see [`bare-os-disk-os-bridge.js`](../../packages/bare-os-booter/lib/bare-os-disk-os-bridge.js) and §12.4.
|
||||
- **`ctx.bareOsHrpcRequest`** (stock) — validates **`service`**, **`method`**, object **`payload`**; optional **`BARE_OS_HRPC_ALLOWLIST_JSON`**; built-in routes **`kernel.ping`**, **`kernel.capabilities`**, **`vfs.readText`**, **`bare_os.echo`**, **`bare_os.disk_os_hints`**, **`bare_os.search_local`**, **`bare_os.replication_operator_sketch`**, **`bare_os.replication_snapshot`**, **`bare_os.pkg_index_get`** (**`BARE_OS_HRPC_ROUTE_TABLE_SCHEMA_VERSION` 3**). **`BARE_OS_HRPC_EMIT_UNLISTED`** forwards unknown routes to **`process.emit('bare-os:hrpc-request', …)`** on Node when enabled.
|
||||
- `try { await runKernelFromSource(...) } finally { await session.cleanup() }` — cleanup runs **`bareInitdShutdownActiveUnitsReverse`**, **`runKernelShutdownHooks`**, **`stopBareInitd`**, fish TTY teardown.
|
||||
|
||||
@@ -7,7 +7,7 @@ Stock routing is implemented in `packages/bare-os-booter/lib/vfs.js` (`createVfs
|
||||
| `pseudo` | `/proc`, `/sys`, `/dev` | Synthetic trees; not Hyperdrive bytes |
|
||||
| `volatile` | `/run`, `/tmp` | Session / ephemeral; often personal-backed |
|
||||
| `mount` | `/mnt`, `/media`, `/mount` | Optional union / HDMS mounts |
|
||||
| `personal` | `/home/…`, `/root…`, **`/.bare/**`** | Personal Hyperdrive view; physical prefixes may nest under **`/.bare-os/acct/<id>/…`** when **`BARE_OS_PERSONAL_ACCT_PREFIX=1`**. With that flag, logical **`/.bare/account`** and **`/.bare/vault/**`** resolve to **`/.bare-os/acct/<id>/.bare/…`** on the personal drive (per-session identity isolation); without the flag, **`/.bare/**`** stays at the personal root as before. |
|
||||
| `personal` | `/home/…`, `/root…`, **`/.bare/**`** | Personal Hyperdrive view; physical prefixes may nest under **`/.bare-os/acct/<id>/…`** when **`BARE_OS_PERSONAL_ACCT_PREFIX=1`**. With that flag, logical **`/.bare/account`** and **`/.bare/vault/**`** resolve to **`/.bare-os/acct/<id>/.bare/…`** on the personal drive (per-session identity isolation); without the flag, **`/.bare/**`** stays at the personal root as before. **Exception:** when an HDMS (or mount-map) entry with label **`www`** is present, **`$HOME/.www`** and **`/home/<active>/.www`** are routed to that **`www`** drive’s root instead of the personal home tree (same path class for policy helpers; different backing **`drive`** in `route()`). |
|
||||
| `system` | `/boot`, `/bin`, `/lib`, `/etc`, `/usr`, `/var`, default | System image Hyperdrive |
|
||||
| `snapshot` | `/snapshots`, `/snapshots/system/…` | Read-only **system** checkout views when **`BARE_OS_VFS_SNAPSHOTS=1`** and `drive.checkout` exists |
|
||||
|
||||
|
||||
@@ -153,10 +153,14 @@ flowchart LR
|
||||
Console[ctx.console = session.console]
|
||||
Initd[startBareInitd]
|
||||
Logger[kernel-logger wraps log/error]
|
||||
Www[bare-os-www static HTTP]
|
||||
Holesail[bare-holesail tunnels]
|
||||
Cron[bare-cron setInterval]
|
||||
Session --> Console
|
||||
Console --> Initd
|
||||
Initd --> Logger
|
||||
Initd --> Www
|
||||
Initd --> Holesail
|
||||
Initd --> Cron
|
||||
```
|
||||
|
||||
|
||||
@@ -181,14 +181,14 @@ There is no arbitrary command execution, **`source`**, or control flow — it is
|
||||
**`bare-initd.js`**:
|
||||
|
||||
- **`registerBareService({ name, start, stop?, description?, logPath? })`** — optional **`stop`** enables **`systemctl stop`** / **`restart`** for that unit; **`logPath`** is a logical VFS path for **`systemctl status`** / **`logs`**
|
||||
- **`startBareInitd(ctx)`** — ensures **`/var/log/bare-os`** (see below), then **DAG-ordered** start with optional parallelism (**`BARE_OS_INITD_MAX_PARALLEL`**, default **1**). Skips units listed in **`~/.config/bare-os/initd/disabled.txt`**. Drop-ins **`~/.config/bare-os/units/<name>.unit`** support **`[Unit]`** keys **`After=`**, **`Before=`**, **`Requires=`**, **`Wants=`**, **`TimeoutStartSec=`**, **`TimeoutStopSec=`**, **`Restart=`**, **`RestartSec=`**, **`OnFailure=`**, **`FailureAction=`**, **`ExecStartPost=`**, **`SocketActivationIpc=`** (defers **`start()`** until the first read on that FIFO), **`IdleSec=`** (with socket activation and a **`stop`** handler: stop after idle seconds between FIFO messages), **`ReadinessPath=`** (VFS path until **`exists`**, or **`exec:<execLine>`** gated by **`ReadinessTimeoutSec=`**), **`ReadinessTimeoutSec=`**, **`ConditionPathExists=`** (skip start when missing), **`AssertPathExists=`** (fail unit when missing). Optional fragments **`~/.config/bare-os/units.d/<name>/*.conf`** (sorted **`.conf`**) merge after the main **`.unit`** and before **`~/.config/bare-init/units/`** overrides. Cycles in **`After`/`Before`** are detected and logged; affected units fail start. Default **`bare-cron`** runs after **`kernel-logger`**. Per-service `try/catch`, `[bare-initd] name: err` on failure; failures append to **`/var/log/bare-os/initd.log`** and the structured unit journal; runtime state **`active`** / **`failed`** / **`inactive`**. **`waitForBareInitdUnits(names, timeoutMs)`** polls until listed units are **`active`** (exposed as **`ctx.bareOsAwaitInitdUnits`**). Mobile **`Bare.suspend`** / **`Bare.wakeup`** walks **stop** handlers in **reverse boot order** and **start** hooks forward, matching the DAG snapshot in **`/proc/bare_os/initd_graph.json`**. Coalesced **`/proc/bare_os/metrics_live.json`** (and **`ctx.bareOsReadProcMetricsLive()`**) include **`initdReadiness`** (**schema 2**) for unit readiness summaries.
|
||||
- **`startBareInitd(ctx)`** — ensures **`/var/log/bare-os`** (see below), then **DAG-ordered** start with optional parallelism (**`BARE_OS_INITD_MAX_PARALLEL`**, default **1**). Skips units listed in **`~/.config/bare-os/initd/disabled.txt`**. Drop-ins **`~/.config/bare-os/units/<name>.unit`** support **`[Unit]`** keys **`After=`**, **`Before=`**, **`Requires=`**, **`Wants=`**, **`TimeoutStartSec=`**, **`TimeoutStopSec=`**, **`Restart=`**, **`RestartSec=`**, **`OnFailure=`**, **`FailureAction=`**, **`ExecStartPost=`**, **`SocketActivationIpc=`** (defers **`start()`** until the first read on that FIFO), **`IdleSec=`** (with socket activation and a **`stop`** handler: stop after idle seconds between FIFO messages), **`ReadinessPath=`** (VFS path until **`exists`**, or **`exec:<execLine>`** gated by **`ReadinessTimeoutSec=`**), **`ReadinessTimeoutSec=`**, **`ConditionPathExists=`** (skip start when missing), **`AssertPathExists=`** (fail unit when missing). Optional fragments **`~/.config/bare-os/units.d/<name>/*.conf`** (sorted **`.conf`**) merge after the main **`.unit`** and before **`~/.config/bare-init/units/`** overrides. Cycles in **`After`/`Before`** are detected and logged; affected units fail start. Built-in default edges include **`bare-cron`** after **`kernel-logger`**, **`bare-os-www`** after **`kernel-logger`**, and **`bare-holesail`** after **`kernel-logger`** and **`bare-os-www`** (so the static HTTP listener is up before managed Holesail tunnels target that port). Per-service `try/catch`, `[bare-initd] name: err` on failure; failures append to **`/var/log/bare-os/initd.log`** and the structured unit journal; runtime state **`active`** / **`failed`** / **`inactive`**. **`waitForBareInitdUnits(names, timeoutMs)`** polls until listed units are **`active`** (exposed as **`ctx.bareOsAwaitInitdUnits`**). Mobile **`Bare.suspend`** / **`Bare.wakeup`** walks **stop** handlers in **reverse boot order** and **start** hooks forward, matching the DAG snapshot in **`/proc/bare_os/initd_graph.json`**. Coalesced **`/proc/bare_os/metrics_live.json`** (and **`ctx.bareOsReadProcMetricsLive()`**) include **`initdReadiness`** (**schema 2**) for unit readiness summaries.
|
||||
- **`listBareServices()`**, **`getBareServiceRuntime(name)`**, **`findBareServiceDefinition(name)`**, **`startBareService` / `stopBareService` / `restartBareService`** — introspection and lifecycle (used by the CLI below)
|
||||
- **`bareInitdShutdownActiveUnitsReverse(ctx)`** — REPL **`session.cleanup`** awaits this **first**: calls **`stop`** on every **active** unit with a **`stop`** handler, in **reverse boot-DAG** order (same direction as mobile suspend).
|
||||
- **`registerKernelShutdownHook(fn)`** + **`runKernelShutdownHooks()`** — async-friendly teardown **after** initd reverse stop, **before** disposers; then **`stopBareInitd()`** clears intervals and runs **`registerBareInitdDisposer`** callbacks.
|
||||
- **`registerBareInitdDisposer(fn)`** + **`stopBareInitd()`** — for intervals and synchronous teardown
|
||||
- **Kernel logger** — mirrors **`console.log`/`error`** to **`/var/log/bare-os/kernel-console.log`**. The VFS exposes **`/var`** as a virtual directory and maps **`/var/log/…`** onto the **personal** Hyperdrive at **`/.bare-os/var/log/…`** (the system image drive stays read-only). Each log file is **trimmed** when it grows past 512 KiB (last 256 KiB kept plus a notice line).
|
||||
|
||||
Built-in **`kernel-logger`** wraps **`ctx.console.log` / `error`** to append UTF-8 lines to that path (with **`stop`** / **`restart`** support). **`startBareInitd`** also creates **`/var/log/bare-os`** and a short **`README`** there. Other services use the same tree (e.g. **`cron.log`**). Failures to write logs are swallowed so logging never kills the session.
|
||||
Built-in **`kernel-logger`** wraps **`ctx.console.log` / `error`** to append UTF-8 lines to that path (with **`stop`** / **`restart`** support). **`startBareInitd`** also creates **`/var/log/bare-os`** and a short **`README`** there. Other services use the same tree (e.g. **`cron.log`**, **`www.log`** for **`bare-os-www`**). Failures to write logs are swallowed so logging never kills the session.
|
||||
|
||||
**Service control:** **`/bin/systemctl`** is implemented by the booter (**`kernel-runner`** delegates to **`systemctl-cli.js`**), not by eval’d image JS. Subcommands: **`list`** / **`list-units`** (shows **PRESET** enabled/disabled from **`disabled.txt`**), **`status`**, **`logs`**, **`start`**, **`stop`**, **`restart`**, **`enable`**, **`disable`**, **`is-enabled`**. **`journalctl -u UNIT`** (log tail only) shares the same backend. The legacy name **`bare-initctl`** is still accepted as an alias. **`enable`** / **`disable`** only affect the next **`startBareInitd`** (personal-drive config); runtime **`start`** / **`stop`** remain session commands. See **`man systemctl`**.
|
||||
|
||||
@@ -222,6 +222,21 @@ Disable the unit for the next boot with **`~/.config/bare-os/initd/disabled.txt`
|
||||
|
||||
---
|
||||
|
||||
## bare-os-www (static HTTP for `~/.www`)
|
||||
|
||||
**`bare-os-www-initd.js`** registers initd unit **`bare-os-www`**: a minimal **HTTP/1.1** static file server for the session docroot **`~/.www`** (resolved through the VFS). Stock defaults: listen on **`127.0.0.1:8088`**, **GET** and **HEAD** only, safe path resolution (no **`..`**), small extension→**`Content-Type`** map. **`HEAD`** uses **`vfs.stat`** so **`Content-Length`** matches the file size.
|
||||
|
||||
- **Enable** — **On by default**. Disable with **`BARE_OS_WWW_INITD=0`** / **`false`** or **`systemctl disable bare-os-www`** (**`~/.config/bare-os/initd/disabled.txt`**).
|
||||
- **Env** — **`BARE_OS_WWW_PORT`** (default **8088**), **`BARE_OS_WWW_HOST`** (default **`127.0.0.1`**; use **`0.0.0.0`** only when you intend LAN exposure without Holesail). **`BARE_OS_WWW_HOLESAIL=0`** skips auto-merging the managed Holesail server entry (see below).
|
||||
- **Bootstrap** — If **`~/.www/index.html`** is missing or empty, the unit creates **`~/.www/`** and writes the stock landing page. The same **`ensureBareOsWwwHomeDefaults(ctx)`** helper runs after a successful **`login`**, **`login --new`**, or **`applyLoginKeys`** in **`identity-session.js`**, so operators often already have **`~/.www`** before initd starts.
|
||||
- **Holesail** — When managed **`bare-holesail`** is active, after **`listen`** succeeds the booter idempotently persists **`bare-www-<port>`** in **`~/.holesail/state.json`** as **`{ server: true, port, host: "127.0.0.1", enabled: true }`** (no **`key`** — upstream mints the URL). **`holesail list`** shows the live tunnel.
|
||||
- **Logs** — **`/var/log/bare-os/www.log`** (same personal-backed tree as other **`bare-os`** logs).
|
||||
- **VFS + HDMS** — When an HDMS mount with label **`www`** exists at **`/mnt/www`**, logical **`$HOME/.www`** and **`/home/<active>/.www`** route to that Hyperdrive root instead of the personal home tree (see [Chapter 5](05-identity-vault-and-hdms.md)). Without that mount, **`~/.www`** stays on the **personal** drive under the session home prefix.
|
||||
|
||||
Implementation: [`packages/bare-os-booter/lib/bare-os-www-initd.js`](../packages/bare-os-booter/lib/bare-os-www-initd.js), [`bare-os-www-holesail.js`](../packages/bare-os-booter/lib/bare-os-www-holesail.js) (Node uses **`node:http`**; Bare/Pear uses **`bare-node-http`**).
|
||||
|
||||
---
|
||||
|
||||
## bare-holesail (Holesail P2P proxy)
|
||||
|
||||
**`bare-holesail.js`** wires the upstream **`holesail`** package (**AGPL-3.0**) using **only** its public class API (no direct Hyperswarm / HyperDHT usage in this integration). Under **`pear run`**, the booter cannot bare-**`import('holesail')`** from **`pear:`** modules, so **`bare-holesail`** resolves the class from **`ctx.bare.holesail`** when the drive merge succeeded, else **`import.meta.resolve('holesail')`**, else a one-off eval of **`/lib/bare/bundles/holesail.js`** via **`ctx.vfs`** (same IIFE semantics as **`maybeMergeBareFromDrive`**).
|
||||
@@ -229,7 +244,7 @@ Disable the unit for the next boot with **`~/.config/bare-os/initd/disabled.txt`
|
||||
- **Initd unit `bare-holesail`** — **On by default** ( **`BARE_OS_HOLESAIL_INITD=1`** and **`BARE_OS_HOLESAIL_MANAGED=1`** in stock **`shellEnv`** unless the host sets them empty or to **`0`/`false`**). Disable for a session with **`BARE_OS_HOLESAIL_INITD=0`** or **`systemctl disable bare-holesail`** ( **`~/.config/bare-os/initd/disabled.txt`**). Either **managed multi-tunnel** or **single env tunnel**:
|
||||
- **Managed (persisted list)** — Stock default (**`BARE_OS_HOLESAIL_MANAGED=1`**). Tunnel definitions live in **`BARE_OS_HOLESAIL_STATE`** (default **`~/.holesail/state.json`**, under the session **`$HOME`** on the personal drive). On unit start, every **enabled** entry gets its own **`holesail`** instance. Use guest **`/bin/holesail`** ( **`ctx.bareOsRunHolesailCli`**) to **`list`**, **`add`**, **`remove`**, **`start`**, **`stop`**, **`enable`**, **`disable`**, **`restart`**.
|
||||
- **Single tunnel** — Set **`BARE_OS_HOLESAIL_MANAGED=0`**, then exactly one of **`BARE_OS_HOLESAIL_SERVER=1`** or **`BARE_OS_HOLESAIL_CLIENT=1`**, **`BARE_OS_HOLESAIL_KEY=…`** when in client mode, and optional **`BARE_OS_HOLESAIL_SECURE`**, **`BARE_OS_HOLESAIL_PORT`**, **`BARE_OS_HOLESAIL_HOST`**, **`BARE_OS_HOLESAIL_UDP`**, **`BARE_OS_HOLESAIL_LOG`**.
|
||||
Starts after **`kernel-logger`** by default. Logs: **`/var/log/bare-os/holesail.log`**. Example drop-in: **`/etc/bare-os/units/bare-holesail.unit.example`** on the system image.
|
||||
Starts after **`kernel-logger`** and **`bare-os-www`** by default (so **`bare-www-*`** server tunnels can reach the loopback HTTP listener). Logs: **`/var/log/bare-os/holesail.log`**. Example drop-in: **`/etc/bare-os/units/bare-holesail.unit.example`** on the system image.
|
||||
- **Early booter (“kernel-path”) instance** — Separate optional instance started **after** the **`repl`** boot phase and **before** **`startBareInitd`**. Enable with **`BARE_OS_HOLESAIL_KERNEL=1`** and the **`BARE_OS_HOLESAIL_KERNEL_*`** mirror of the options above (e.g. **`BARE_OS_HOLESAIL_KERNEL_SERVER=1`**). Uses **`registerKernelShutdownHook`** for teardown. **`hs.pause()` / `hs.resume()`** run on mobile suspend/resume hooks alongside other subsystems.
|
||||
- **Guest scripts** — Use **`ctx.bare.holesail`** (bundled under **`/lib/bare/bundles/holesail.js`**), not **`require('holesail')`**, because **`/bin`** and **`/boot/init.js`** are not Node modules. **`/bin/holesail`** is the operator CLI for persisted tunnels (see managed mode above). See **`kernel/etc/bare-os/kernel.d/.README`**.
|
||||
|
||||
|
||||
@@ -76,6 +76,7 @@ The personal drive still persists: guest data is **not** anonymous to the drive
|
||||
- **`vfs.chdir`** to the new home.
|
||||
- **`onIdentityUnlocked`** (from `index.js`) activates **HDMS** with Corestore, swarm bootstrap, personal drive, mount map.
|
||||
- **`loadBarerc`** runs inside **`applyUnlockedEnv`** after a successful **`login`** or **`login --new`** (with **`createSkeletonIfMissing: true`** on first unlock), so **`~/.barerc`** exports and aliases apply immediately—custom kernels normally **do not** need to reload barerc themselves. Use **`ctx.onIdentityUnlocked`** if you want an extra banner or post-login message.
|
||||
- **`~/.www`** — After **`ensureBareDir`**, **`ensureBareOsWwwHomeDefaults`** creates **`~/.www/`** and the stock **`index.html`** when the tree is missing or the file is empty, so a successful unlock/register/login leaves a ready **personal-site** docroot. The initd unit **`bare-os-www`** serves it over HTTP on **`127.0.0.1:8088`** by default (see [Chapter 4 — bare-os-www](04-the-booter-runtime.md#bare-os-www-static-http-for-www)).
|
||||
|
||||
**`logout`** zeroes sensitive material and returns to guest; **`logout --save`** (and **`savevault`**) snapshot selected paths into **`/.bare/vault/`** as encrypted records (see `identity-account.js` helpers for AEAD and path hashing).
|
||||
|
||||
@@ -100,7 +101,7 @@ The personal drive still persists: guest data is **not** anonymous to the drive
|
||||
|
||||
**`assertLoggedIn`** requires **`ctx.identity.state === 'unlocked'`** and active controller—guests can list mounts that are already open but cannot **mutate** registry until login.
|
||||
|
||||
**VFS** exposes **`/mnt/<label>/...`** for mounted drives; writable mounts allow **`put`** on those routes.
|
||||
**VFS** exposes **`/mnt/<label>/...`** for mounted drives; writable mounts allow **`put`** on those routes. When **`label`** is **`www`**, the VFS also routes logical **`$HOME/.www`** (and **`/home/<active>/.www`**) to that mount’s root so operators can use the familiar home path while still storing the site on a dedicated Hyperdrive (convention: **`hdms create www`** or **`mount local www`** after unlock).
|
||||
|
||||
**Kernel hooks:** **`ctx.bareOsSubscribeHdmsLifecycle(fn)`** runs your callback after HDMS **`activate`** and before **`deactivate`** with **`{ kind: 'afterActivate' | 'beforeDeactivate', labels?: string[] }`** so custom **`/boot/init.js`** can refresh mounts-dependent state without forking HDMS. The stock booter also invokes **`onAfterActivate`** on the **`hdms`** module export when present (see [Developer guide ch.11](../developer-guide/11-kernel-pear-cookbook.md)).
|
||||
|
||||
|
||||
@@ -22,7 +22,7 @@ This tree follows the **agent** Markdown workspace convention: “soul” files
|
||||
3. During a session, the model loads the full document with the **`read_skill`** tool (do not paste huge skills into the user channel unless asked).
|
||||
4. Shared skills can live under **`~/.agent/skills/`**; keep **`workspace/skills/`** for machine-local or repo-specific behavior.
|
||||
|
||||
Seeded examples in this repo (under **`skills/`**): **`p2p-os-status`**, **`bare-os-kernel-proc`**, **`bare-os-super-developer`**, **`holesail`** (Holesail tunnels / initd), and **`hdms`** (Hyperdrive mounts and invite/pair).
|
||||
Seeded examples in this repo (under **`skills/`**): **`p2p-os-status`**, **`bare-os-kernel-proc`**, **`bare-os-super-developer`**, **`holesail`** (Holesail tunnels / initd; stock **`bare-www-*`** pairs with **`bare-os-www`** on **`~/.www`**), and **`hdms`** (Hyperdrive mounts and invite/pair).
|
||||
|
||||
After **`agent --config`** / **`--setup`** (or changing **`owner_name`** / **`agent_label`** via **`edit_agent_config`**), **`IDENTITY.md`** and **`USER.md`** are regenerated from **`config.json`** so the workspace matches the operator and agent label.
|
||||
|
||||
|
||||
@@ -33,7 +33,7 @@ Think in layers the stock OS already uses:
|
||||
|
||||
| Layer | Mechanism | Notes |
|
||||
| --- | --- | --- |
|
||||
| **Init** | **`bareOsRegisterBootStepHook`**, initd units | Boot-order DAG; pair **`registerKernelShutdownHook`** / initd disposers for teardown. |
|
||||
| **Init** | **`bareOsRegisterBootStepHook`**, initd units | Boot-order DAG (stock example: **`bare-os-www`** before **`bare-holesail`** for **`bare-www-*`** tunnels); pair **`registerKernelShutdownHook`** / initd disposers for teardown. |
|
||||
| **Virtual files** | **`bareOsRegisterVirtualFile(name, reader, opts?)`** | Serves **`/run/bare-os/virtual/<name>`**; gated by runtime caps. |
|
||||
| **IPC** | **`ctx.bareOsIpc`** when present | **`push`/`take`**, JSON helpers, fanout, duplex bridge — bounded; audit when **`BARE_OS_IPC_AUDIT=1`**. |
|
||||
| **Kernel extensions** | **`bareOsRegisterKernelExtensionRecord`**, **`bareOsRunImageScript`** under **`/lib/bare-os/extensions/`** | Trusted image paths only. |
|
||||
|
||||
@@ -23,6 +23,7 @@ Use when the user asks about **HDMS** (Hyperdrive Management): **`hdms`** CLI, *
|
||||
- **Writable mounts:** **`hdms create <label>`** — new Corestore namespace + Hyperdrive, replicate to swarm.
|
||||
- **Read-only by key:** **`hdms add <label> <z32-key>`** — open an existing drive by key string.
|
||||
- **VFS:** paths **`/mnt/<label>/…`**; writable mounts allow **`put`** on those routes.
|
||||
- **`www` label:** A mount labeled **`www`** at **`/mnt/www`** also routes **`$HOME/.www`** and **`/home/<active>/.www`** in the VFS—the same docroot the stock **`bare-os-www`** initd serves by default. See **`handbook/05-identity-vault-and-hdms.md`** and **`handbook/04-the-booter-runtime.md`** § **bare-os-www**.
|
||||
|
||||
## Invite and pair (Autopass / BlindPairing)
|
||||
|
||||
|
||||
@@ -17,6 +17,7 @@ Use when the user asks about **Holesail** in this repo: exposing TCP/UDP through
|
||||
1. **Integration** lives in **`packages/bare-os-booter/lib/bare-holesail.js`** (initd + optional early “kernel-path” instance) and **`packages/bare-os-booter/lib/holesail-cli.js`** (**`ctx.bareOsRunHolesailCli`** for **`/bin/holesail`**).
|
||||
2. **Resolution order** under **`pear run`**: the booter prefers **`ctx.bare.holesail`** ( **`/lib/bare/bundles/holesail.js`** after drive merge), else host **`import.meta.resolve('holesail')`**, else eval of the drive IIFE bundle via **`ctx.vfs`** — **`/bin`** and **`/boot/init.js`** are **not** Node modules, so scripts must not **`require('holesail')`**.
|
||||
3. **Stock default**: initd unit **`bare-holesail`** is **on** when **`BARE_OS_HOLESAIL_INITD`** and **`BARE_OS_HOLESAIL_MANAGED`** are left at defaults (**`1`** in stock **`shellEnv`** unless the host clears them). Disable with **`BARE_OS_HOLESAIL_INITD=0`** or **`systemctl disable bare-holesail`** (**`~/.config/bare-os/initd/disabled.txt`**).
|
||||
4. **`bare-os-www`** (**`packages/bare-os-booter/lib/bare-os-www-initd.js`**) serves **`~/.www`** on **`127.0.0.1:8088`** by default. **`bare-holesail`** starts **after** it in the initd DAG so the stock managed entry **`bare-www-<port>`** (**`server: true`**, **`host: 127.0.0.1`**, **`port`** from **`BARE_OS_WWW_PORT`**) can reach the HTTP listener. Opt out of auto-merge with **`BARE_OS_WWW_HOLESAIL=0`**. Handbook: **`handbook/04-the-booter-runtime.md`** § **bare-os-www** and § **bare-holesail**.
|
||||
|
||||
## Managed vs single-tunnel mode
|
||||
|
||||
@@ -34,7 +35,7 @@ From **`holesail-cli.js`** help text:
|
||||
- **`holesail add ID --server|--client`** with optional **`--key`**, bare **`hs://…`** token (no **`--key`** prefix), **`--port`**, **`--host`**, **`--udp`**, **`--secure` / `--no-secure`**, **`--log`**.
|
||||
- **`holesail remove ID`**, **`start|stop|restart ID`**, **`enable|disable ID`**.
|
||||
|
||||
Initd starts after **`kernel-logger`** by default. Logs: **`/var/log/bare-os/holesail.log`**. Example unit drop-in: **`/etc/bare-os/units/bare-holesail.unit.example`** on the system image.
|
||||
Managed **`bare-holesail`** starts after **`kernel-logger`** and **`bare-os-www`** by default. Logs: **`/var/log/bare-os/holesail.log`**. Example unit drop-in: **`/etc/bare-os/units/bare-holesail.unit.example`** on the system image.
|
||||
|
||||
## Debugging and safety
|
||||
|
||||
|
||||
@@ -18,7 +18,8 @@ Use this skill whenever the user asks for system status, peer count, drive healt
|
||||
2. Call **`get_swarm_peers`** (and **`get_system_info`** as needed) for swarm / session context when exposed by the booter.
|
||||
3. Use **`read_proc_file`** on **`/proc/bare_os/*`** mirrors when the user cares about kernel/session metrics (see the **bare-os-kernel-proc** skill for feature/capability JSON).
|
||||
4. Check SSH/kernel narrative only when **`read_proc_file`** or **`read_man_page`** confirms how this image exposes **`sshd`** (do not assume **`node`** exists).
|
||||
5. Summarize in clear bullet points:
|
||||
5. When a **personal static site** matters, after **`login`** check **`~/.www`** (and optional **`curl -I http://127.0.0.1:8088/`**, or the port from **`BARE_OS_WWW_PORT`** in env); initd logs append to **`/var/log/bare-os/www.log`**.
|
||||
6. Summarize in clear bullet points:
|
||||
|
||||
- Drive sync status
|
||||
- Active peers
|
||||
|
||||
@@ -4,6 +4,7 @@ Authoritative **version alignment** with protocol and telemetry schema numbers l
|
||||
|
||||
## Maintenance
|
||||
|
||||
- **`bare-os-www` initd** — Stock static HTTP server for **`~/.www`** on **`127.0.0.1:8088`** ( **`bare-os-www-initd.js`**, **`bare-os-www-holesail.js`** ); managed **Holesail** entry **`bare-www-<port>`** with **`host: 127.0.0.1`**; **`ensureBareOsWwwHomeDefaults`** after **`login`** (creates **`~/.www`** when missing); **`maybeRestartBareOsWwwAfterIdentity`** restarts the unit after unlock/register/`applyLoginKeys` and after **`logout`** so the listener tracks the current session **`HOME`** (not a stale closed-over **`ctx`**). Handbook [ch.4 § bare-os-www](../../handbook/04-the-booter-runtime.md#bare-os-www-static-http-for-www); env **`BARE_OS_WWW_*`** in [environment appendix](../../docs/reference/environment-and-posix-appendix.md).
|
||||
- **Shell completion / Fish REPL:** canonical documentation is [`docs/reference/shell-completion-and-repl-editor.md`](../../docs/reference/shell-completion-and-repl-editor.md) (engine in **`lib/completion-engine.js`**, UI in **`lib/fish-readline.js`**, **`BARE_OS_FISH`**, **`BARE_OS_COMPACT_MENU`**).
|
||||
- **`baretop` snapshot**: **`ctx.bareOsReadBareTopSnapshot({ lite: true })`** returns a reduced **`files`** map (see **`BARE_TOP_SNAPSHOT_LITE_ENTRIES`** in **`packages/bare-os-coreutils/lib/baretop-snapshot.js`**). Full batch includes **`securityPosture`** → **`/proc/bare_os/security_posture.json`**. **`metrics_live`** JSON uses **`schema: 4`** with embedded **`processTable`** when present; kernel counters include optional **`vfs.readfile.samples`** ( **`BARE_OS_VFS_READ_METRICS`** ), **`initd.unit_failed_final`**, and **`shell.pipeline_last_stages`** gauge from the shell.
|
||||
- **`/proc/bare_os/net_summary.json`**: **`schemaVersion` 2** adds scalar **`replicationQueueDepth`**, firewall session totals, optional **`BARE_OS_BSD_SOCKET_BRIDGE_STATS_JSON`** merge into **`bsdSocketGuestBridge`**; **`peer_firewall_stats`** field alignment documented in **`bare-os-protocol`** channel handler.
|
||||
|
||||
@@ -38,7 +38,8 @@ node index.js
|
||||
- **`bare-os-ctx-bare.js` / `bare-module-manifest.json` / `bare-module-manifest.data.mjs`** — **`ctx.bare`** host imports + optional **`/lib/bare/`** drive bundle merge; Pear loads the manifest from generated **`bare-module-manifest.data.mjs`** (see [PEAR-RUN.md](../../docs/PEAR-RUN.md), [Developer guide ch.12](../../developer-guide/12-bare-modules-and-pear-ecosystem.md))
|
||||
- **`identity-session.js` / `identity-account.js`** — Guest vs unlocked user, `/.bare/account`, vault
|
||||
- **`hdms-manager.js`** — Extra Hyperdrives, mounts under `/mnt`, Autopass pair/invite
|
||||
- **`bare-initd.js`** — Service registry, unit drop-ins, **`units.d`** fragments, 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-initd.js`** — Service registry, unit drop-ins, **`units.d`** fragments, 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-holesail`** default chain
|
||||
- **`bare-os-www-initd.js`** / **`bare-os-www-holesail.js`** — Initd unit **`bare-os-www`**: static **`GET`/`HEAD`** HTTP for **`~/.www`** (default **`127.0.0.1:8088`**); idempotent managed **Holesail** server entry **`bare-www-<port>`** with **`host: 127.0.0.1`**
|
||||
- **`bare-cron.js`** — `/etc/bare-os/crontab`, `~/.crontab`, `~/.config/bare-os/timers/*.timer` (**`OnCalendar=`**, **`EveryMs=`**, **`OnInactiveSec=`** / **`Persistent=`**), minute scheduler, `ctx.execLine` jobs
|
||||
- **`bare-os-delegate-concurrent.js`** — Optional in-flight caps (**`BARE_OS_DELEGATE_MAX_CONCURRENT`**, per-kind **`BARE_OS_DELEGATE_*_MAX_CONCURRENT`**) around host delegates
|
||||
- **`repl-session.js`** — Fish-style TTY line editor, synced `console`, cleanup → `stopBareInitd`
|
||||
|
||||
@@ -11,7 +11,11 @@ const http =
|
||||
process.release.name === 'node'
|
||||
? nodeHttp
|
||||
: bareNodeHttp
|
||||
import { registerBareService } from './bare-initd.js'
|
||||
import {
|
||||
findBareServiceDefinition,
|
||||
registerBareService,
|
||||
restartBareService
|
||||
} from './bare-initd.js'
|
||||
import { appendVarLog, BARE_OS_VAR_LOG_DIR } from './bare-os-var-log.js'
|
||||
import { ensureBareOsWwwHolesailTunnel } from './bare-os-www-holesail.js'
|
||||
|
||||
@@ -228,6 +232,11 @@ function wwwLog(ctx, line) {
|
||||
export async function ensureBareOsWwwHomeDefaults(ctx) {
|
||||
const vfs = ctx.vfs
|
||||
if (!vfs || typeof vfs.resolveLogical !== 'function') return
|
||||
try {
|
||||
await vfs.mkdir(vfs.resolveLogical('~/.www'), { recursive: true })
|
||||
} catch {
|
||||
/* ignore */
|
||||
}
|
||||
const idx = vfs.resolveLogical('~/.www/index.html')
|
||||
try {
|
||||
const cur = await vfs.readFile(idx)
|
||||
@@ -243,11 +252,6 @@ export async function ensureBareOsWwwHomeDefaults(ctx) {
|
||||
} catch {
|
||||
/* missing or unreadable */
|
||||
}
|
||||
try {
|
||||
await vfs.mkdir(vfs.resolveLogical('~/.www'), { recursive: true })
|
||||
} catch {
|
||||
/* ignore */
|
||||
}
|
||||
try {
|
||||
if (!ctx.b4a || typeof ctx.b4a.from !== 'function') return
|
||||
const body = ctx.b4a.from(BARE_OS_WWW_DEFAULT_INDEX, 'utf8')
|
||||
@@ -446,6 +450,32 @@ let bareOsWwwInitdRegistered = false
|
||||
/**
|
||||
* @param {Record<string, string | undefined>} env
|
||||
*/
|
||||
/**
|
||||
* After `HOME` / session identity changes (`login`, `logout`, `applyLoginKeys`, register),
|
||||
* recreate the HTTP listener — `http.createServer` closed over the previous `ctx`.
|
||||
* No-op when the unit is not registered or `BARE_OS_WWW_INITD` disables the service.
|
||||
* @param {Record<string, unknown>} ctx
|
||||
*/
|
||||
export async function maybeRestartBareOsWwwAfterIdentity(ctx) {
|
||||
const env =
|
||||
ctx.env && typeof ctx.env === 'object'
|
||||
? /** @type {Record<string, string | undefined>} */ (ctx.env)
|
||||
: /** @type {Record<string, string | undefined>} */ ({})
|
||||
if (!bareOsWwwInitdEnabled(env)) return
|
||||
if (!findBareServiceDefinition('bare-os-www')) return
|
||||
try {
|
||||
await restartBareService(ctx, 'bare-os-www')
|
||||
} catch (e) {
|
||||
try {
|
||||
ctx.console?.error?.(
|
||||
`[bare-os-www] restart after identity: ${(e && /** @type {{ message?: string }} */ (e).message) || String(e)}`
|
||||
)
|
||||
} catch {
|
||||
/* ignore */
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
export function maybeRegisterBareOsWwwInitd(env) {
|
||||
if (bareOsWwwInitdRegistered) return
|
||||
if (!bareOsWwwInitdEnabled(env || {})) return
|
||||
|
||||
@@ -27,7 +27,10 @@ import {
|
||||
SSHD_DEFAULT_AUTHORIZED_KEYS_FILE
|
||||
} from './sshd-config-parse.js'
|
||||
import { ensureBareOsVarLogTree } from './bare-os-var-log.js'
|
||||
import { ensureBareOsWwwHomeDefaults } from './bare-os-www-initd.js'
|
||||
import {
|
||||
ensureBareOsWwwHomeDefaults,
|
||||
maybeRestartBareOsWwwAfterIdentity
|
||||
} from './bare-os-www-initd.js'
|
||||
|
||||
const LEGACY_ROOT_MIGRATION_STATE = '/.bare-os/migration/legacy-root-v1.json'
|
||||
|
||||
@@ -379,6 +382,7 @@ export async function applyLoginKeys(ctx, keys) {
|
||||
} catch (e) {
|
||||
ctx.console?.error?.('[bare-os] ensureBareOsWwwHomeDefaults: ' + (e?.message || e))
|
||||
}
|
||||
await maybeRestartBareOsWwwAfterIdentity(ctx)
|
||||
maybeAppendVaultMultisigContinuityAudit(ctx, 'applyLoginKeys')
|
||||
}
|
||||
|
||||
@@ -462,6 +466,7 @@ export async function registerIdentity(ctx, passphrase) {
|
||||
} catch (e) {
|
||||
ctx.console?.error?.('[bare-os] ensureBareOsWwwHomeDefaults: ' + (e?.message || e))
|
||||
}
|
||||
await maybeRestartBareOsWwwAfterIdentity(ctx)
|
||||
try {
|
||||
await bareOsAppendVaultRotationCheckpoint(ctx, {
|
||||
kind: 'identity_register',
|
||||
@@ -510,6 +515,7 @@ export async function unlockIdentity(ctx, passphrase) {
|
||||
} catch (e) {
|
||||
ctx.console?.error?.('[bare-os] ensureBareOsWwwHomeDefaults: ' + (e?.message || e))
|
||||
}
|
||||
await maybeRestartBareOsWwwAfterIdentity(ctx)
|
||||
try {
|
||||
await bareOsAppendVaultRotationCheckpoint(ctx, {
|
||||
kind: 'identity_unlock',
|
||||
@@ -555,6 +561,7 @@ export async function logoutIdentity(ctx, opts = {}) {
|
||||
}
|
||||
wipeSecret(ctx)
|
||||
await applyGuestEnv(ctx)
|
||||
await maybeRestartBareOsWwwAfterIdentity(ctx)
|
||||
ctx.console.log('Logged out (guest)')
|
||||
}
|
||||
|
||||
|
||||
@@ -13,7 +13,8 @@ import {
|
||||
bareOsWwwResolveStaticPath,
|
||||
BARE_OS_WWW_DEFAULT_INDEX,
|
||||
ensureBareOsWwwHomeDefaults,
|
||||
maybeRegisterBareOsWwwInitd
|
||||
maybeRegisterBareOsWwwInitd,
|
||||
maybeRestartBareOsWwwAfterIdentity
|
||||
} from './lib/bare-os-www-initd.js'
|
||||
import { findBareServiceDefinition } from './lib/bare-initd.js'
|
||||
import {
|
||||
@@ -198,3 +199,97 @@ test('ensureBareOsWwwHomeDefaults creates ~/.www/index.html', async (t) => {
|
||||
await store.close()
|
||||
rmSync(dir, { recursive: true, force: true })
|
||||
})
|
||||
|
||||
test('maybeRestartBareOsWwwAfterIdentity rebinds HTTP server to new HOME', async (t) => {
|
||||
const dir = testCorestoreDir('wwwrebind')
|
||||
const store = new Corestore(dir)
|
||||
const sys = new Hyperdrive(store)
|
||||
const personal = new Hyperdrive(store.namespace('prebind'))
|
||||
await sys.ready()
|
||||
await personal.ready()
|
||||
const port = 19500 + Math.floor(Math.random() * 800)
|
||||
const shellEnv = {
|
||||
HOME: '/home/alice',
|
||||
PATH: '/bin',
|
||||
USER: 'alice',
|
||||
UID: '1000',
|
||||
GID: '1000',
|
||||
PWD: '/home/alice',
|
||||
BARE_OS_EXIT_STATUS: '0',
|
||||
BARE_OS_SSH_LISTEN_PORT: '0',
|
||||
BARE_OS_WWW_PORT: String(port),
|
||||
BARE_OS_WWW_HOLESAIL: '0'
|
||||
}
|
||||
const bareOsIpc = createBareOsIpc()
|
||||
const vfs = createVfs(sys, personal, shellEnv, null, { bareOsIpc })
|
||||
const ctx = {
|
||||
drive: sys,
|
||||
personalDrive: personal,
|
||||
vfs,
|
||||
bareOsIpc,
|
||||
env: shellEnv,
|
||||
console,
|
||||
b4a
|
||||
}
|
||||
await vfs.mkdir(vfs.resolveLogical('~/.www'), { recursive: true })
|
||||
await vfs.writeFile(
|
||||
vfs.resolveLogical('~/.www/index.html'),
|
||||
b4a.from('ALICE', 'utf8')
|
||||
)
|
||||
shellEnv.HOME = '/home/bob'
|
||||
shellEnv.USER = 'bob'
|
||||
shellEnv.PWD = '/home/bob'
|
||||
await vfs.mkdir(vfs.resolveLogical('~/.www'), { recursive: true })
|
||||
await vfs.writeFile(
|
||||
vfs.resolveLogical('~/.www/index.html'),
|
||||
b4a.from('BOB', 'utf8')
|
||||
)
|
||||
shellEnv.HOME = '/home/alice'
|
||||
shellEnv.USER = 'alice'
|
||||
shellEnv.PWD = '/home/alice'
|
||||
|
||||
maybeRegisterBareOsWwwInitd(ctx.env)
|
||||
const svc = findBareServiceDefinition('bare-os-www')
|
||||
t.ok(svc && typeof svc.start === 'function')
|
||||
await /** @type {{ start: (c: unknown) => Promise<void> }} */ (svc).start(ctx)
|
||||
|
||||
const fetchText = () =>
|
||||
new Promise((resolve, reject) => {
|
||||
http.get(`http://127.0.0.1:${port}/`, (res) => {
|
||||
const chunks = []
|
||||
res.on('data', (c) => chunks.push(c))
|
||||
res.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')))
|
||||
res.on('error', reject)
|
||||
}).on('error', reject)
|
||||
})
|
||||
|
||||
const fetchTextRetry = async (want, ms = 3000) => {
|
||||
const deadline = Date.now() + ms
|
||||
let last = /** @type {unknown} */ (null)
|
||||
while (Date.now() < deadline) {
|
||||
try {
|
||||
const txt = await fetchText()
|
||||
if (txt === want) return txt
|
||||
last = txt
|
||||
} catch {
|
||||
/* port may still be rebound after restart */
|
||||
}
|
||||
await new Promise((r) => setTimeout(r, 25))
|
||||
}
|
||||
throw new Error(
|
||||
`expected body ${JSON.stringify(want)}, last ${JSON.stringify(last)}`
|
||||
)
|
||||
}
|
||||
|
||||
t.is(await fetchText(), 'ALICE')
|
||||
|
||||
shellEnv.HOME = '/home/bob'
|
||||
shellEnv.USER = 'bob'
|
||||
shellEnv.PWD = '/home/bob'
|
||||
await maybeRestartBareOsWwwAfterIdentity(ctx)
|
||||
t.is(await fetchTextRetry('BOB'), 'BOB')
|
||||
|
||||
await /** @type {{ stop: (c: unknown) => Promise<void> }} */ (svc).stop(ctx)
|
||||
await store.close()
|
||||
rmSync(dir, { recursive: true, force: true })
|
||||
})
|
||||
|
||||
@@ -22,7 +22,7 @@ This tree follows the **agent** Markdown workspace convention: “soul” files
|
||||
3. During a session, the model loads the full document with the **`read_skill`** tool (do not paste huge skills into the user channel unless asked).
|
||||
4. Shared skills can live under **`~/.agent/skills/`**; keep **`workspace/skills/`** for machine-local or repo-specific behavior.
|
||||
|
||||
Seeded examples in this repo (under **`skills/`**): **`p2p-os-status`**, **`bare-os-kernel-proc`**, **`bare-os-super-developer`**, **`holesail`** (Holesail tunnels / initd), and **`hdms`** (Hyperdrive mounts and invite/pair).
|
||||
Seeded examples in this repo (under **`skills/`**): **`p2p-os-status`**, **`bare-os-kernel-proc`**, **`bare-os-super-developer`**, **`holesail`** (Holesail tunnels / initd; stock **`bare-www-*`** pairs with **`bare-os-www`** on **`~/.www`**), and **`hdms`** (Hyperdrive mounts and invite/pair).
|
||||
|
||||
After **`agent --config`** / **`--setup`** (or changing **`owner_name`** / **`agent_label`** via **`edit_agent_config`**), **`IDENTITY.md`** and **`USER.md`** are regenerated from **`config.json`** so the workspace matches the operator and agent label.
|
||||
|
||||
|
||||
+1
-1
@@ -33,7 +33,7 @@ Think in layers the stock OS already uses:
|
||||
|
||||
| Layer | Mechanism | Notes |
|
||||
| --- | --- | --- |
|
||||
| **Init** | **`bareOsRegisterBootStepHook`**, initd units | Boot-order DAG; pair **`registerKernelShutdownHook`** / initd disposers for teardown. |
|
||||
| **Init** | **`bareOsRegisterBootStepHook`**, initd units | Boot-order DAG (stock example: **`bare-os-www`** before **`bare-holesail`** for **`bare-www-*`** tunnels); pair **`registerKernelShutdownHook`** / initd disposers for teardown. |
|
||||
| **Virtual files** | **`bareOsRegisterVirtualFile(name, reader, opts?)`** | Serves **`/run/bare-os/virtual/<name>`**; gated by runtime caps. |
|
||||
| **IPC** | **`ctx.bareOsIpc`** when present | **`push`/`take`**, JSON helpers, fanout, duplex bridge — bounded; audit when **`BARE_OS_IPC_AUDIT=1`**. |
|
||||
| **Kernel extensions** | **`bareOsRegisterKernelExtensionRecord`**, **`bareOsRunImageScript`** under **`/lib/bare-os/extensions/`** | Trusted image paths only. |
|
||||
|
||||
@@ -23,6 +23,7 @@ Use when the user asks about **HDMS** (Hyperdrive Management): **`hdms`** CLI, *
|
||||
- **Writable mounts:** **`hdms create <label>`** — new Corestore namespace + Hyperdrive, replicate to swarm.
|
||||
- **Read-only by key:** **`hdms add <label> <z32-key>`** — open an existing drive by key string.
|
||||
- **VFS:** paths **`/mnt/<label>/…`**; writable mounts allow **`put`** on those routes.
|
||||
- **`www` label:** A mount labeled **`www`** at **`/mnt/www`** also routes **`$HOME/.www`** and **`/home/<active>/.www`** in the VFS—the same docroot the stock **`bare-os-www`** initd serves by default. See **`handbook/05-identity-vault-and-hdms.md`** and **`handbook/04-the-booter-runtime.md`** § **bare-os-www**.
|
||||
|
||||
## Invite and pair (Autopass / BlindPairing)
|
||||
|
||||
|
||||
@@ -17,6 +17,7 @@ Use when the user asks about **Holesail** in this repo: exposing TCP/UDP through
|
||||
1. **Integration** lives in **`packages/bare-os-booter/lib/bare-holesail.js`** (initd + optional early “kernel-path” instance) and **`packages/bare-os-booter/lib/holesail-cli.js`** (**`ctx.bareOsRunHolesailCli`** for **`/bin/holesail`**).
|
||||
2. **Resolution order** under **`pear run`**: the booter prefers **`ctx.bare.holesail`** ( **`/lib/bare/bundles/holesail.js`** after drive merge), else host **`import.meta.resolve('holesail')`**, else eval of the drive IIFE bundle via **`ctx.vfs`** — **`/bin`** and **`/boot/init.js`** are **not** Node modules, so scripts must not **`require('holesail')`**.
|
||||
3. **Stock default**: initd unit **`bare-holesail`** is **on** when **`BARE_OS_HOLESAIL_INITD`** and **`BARE_OS_HOLESAIL_MANAGED`** are left at defaults (**`1`** in stock **`shellEnv`** unless the host clears them). Disable with **`BARE_OS_HOLESAIL_INITD=0`** or **`systemctl disable bare-holesail`** (**`~/.config/bare-os/initd/disabled.txt`**).
|
||||
4. **`bare-os-www`** (**`packages/bare-os-booter/lib/bare-os-www-initd.js`**) serves **`~/.www`** on **`127.0.0.1:8088`** by default. **`bare-holesail`** starts **after** it in the initd DAG so the stock managed entry **`bare-www-<port>`** (**`server: true`**, **`host: 127.0.0.1`**, **`port`** from **`BARE_OS_WWW_PORT`**) can reach the HTTP listener. Opt out of auto-merge with **`BARE_OS_WWW_HOLESAIL=0`**. Handbook: **`handbook/04-the-booter-runtime.md`** § **bare-os-www** and § **bare-holesail**.
|
||||
|
||||
## Managed vs single-tunnel mode
|
||||
|
||||
@@ -34,7 +35,7 @@ From **`holesail-cli.js`** help text:
|
||||
- **`holesail add ID --server|--client`** with optional **`--key`**, bare **`hs://…`** token (no **`--key`** prefix), **`--port`**, **`--host`**, **`--udp`**, **`--secure` / `--no-secure`**, **`--log`**.
|
||||
- **`holesail remove ID`**, **`start|stop|restart ID`**, **`enable|disable ID`**.
|
||||
|
||||
Initd starts after **`kernel-logger`** by default. Logs: **`/var/log/bare-os/holesail.log`**. Example unit drop-in: **`/etc/bare-os/units/bare-holesail.unit.example`** on the system image.
|
||||
Managed **`bare-holesail`** starts after **`kernel-logger`** and **`bare-os-www`** by default. Logs: **`/var/log/bare-os/holesail.log`**. Example unit drop-in: **`/etc/bare-os/units/bare-holesail.unit.example`** on the system image.
|
||||
|
||||
## Debugging and safety
|
||||
|
||||
|
||||
@@ -18,7 +18,8 @@ Use this skill whenever the user asks for system status, peer count, drive healt
|
||||
2. Call **`get_swarm_peers`** (and **`get_system_info`** as needed) for swarm / session context when exposed by the booter.
|
||||
3. Use **`read_proc_file`** on **`/proc/bare_os/*`** mirrors when the user cares about kernel/session metrics (see the **bare-os-kernel-proc** skill for feature/capability JSON).
|
||||
4. Check SSH/kernel narrative only when **`read_proc_file`** or **`read_man_page`** confirms how this image exposes **`sshd`** (do not assume **`node`** exists).
|
||||
5. Summarize in clear bullet points:
|
||||
5. When a **personal static site** matters, after **`login`** check **`~/.www`** (and optional **`curl -I http://127.0.0.1:8088/`**, or the port from **`BARE_OS_WWW_PORT`** in env); initd logs append to **`/var/log/bare-os/www.log`**.
|
||||
6. Summarize in clear bullet points:
|
||||
|
||||
- Drive sync status
|
||||
- Active peers
|
||||
|
||||
@@ -22,7 +22,7 @@ This tree follows the **agent** Markdown workspace convention: “soul” files
|
||||
3. During a session, the model loads the full document with the **`read_skill`** tool (do not paste huge skills into the user channel unless asked).
|
||||
4. Shared skills can live under **`~/.agent/skills/`**; keep **`workspace/skills/`** for machine-local or repo-specific behavior.
|
||||
|
||||
Seeded examples in this repo (under **`skills/`**): **`p2p-os-status`**, **`bare-os-kernel-proc`**, **`bare-os-super-developer`**, **`holesail`** (Holesail tunnels / initd), and **`hdms`** (Hyperdrive mounts and invite/pair).
|
||||
Seeded examples in this repo (under **`skills/`**): **`p2p-os-status`**, **`bare-os-kernel-proc`**, **`bare-os-super-developer`**, **`holesail`** (Holesail tunnels / initd; stock **`bare-www-*`** pairs with **`bare-os-www`** on **`~/.www`**), and **`hdms`** (Hyperdrive mounts and invite/pair).
|
||||
|
||||
After **`agent --config`** / **`--setup`** (or changing **`owner_name`** / **`agent_label`** via **`edit_agent_config`**), **`IDENTITY.md`** and **`USER.md`** are regenerated from **`config.json`** so the workspace matches the operator and agent label.
|
||||
|
||||
|
||||
+1
-1
@@ -33,7 +33,7 @@ Think in layers the stock OS already uses:
|
||||
|
||||
| Layer | Mechanism | Notes |
|
||||
| --- | --- | --- |
|
||||
| **Init** | **`bareOsRegisterBootStepHook`**, initd units | Boot-order DAG; pair **`registerKernelShutdownHook`** / initd disposers for teardown. |
|
||||
| **Init** | **`bareOsRegisterBootStepHook`**, initd units | Boot-order DAG (stock example: **`bare-os-www`** before **`bare-holesail`** for **`bare-www-*`** tunnels); pair **`registerKernelShutdownHook`** / initd disposers for teardown. |
|
||||
| **Virtual files** | **`bareOsRegisterVirtualFile(name, reader, opts?)`** | Serves **`/run/bare-os/virtual/<name>`**; gated by runtime caps. |
|
||||
| **IPC** | **`ctx.bareOsIpc`** when present | **`push`/`take`**, JSON helpers, fanout, duplex bridge — bounded; audit when **`BARE_OS_IPC_AUDIT=1`**. |
|
||||
| **Kernel extensions** | **`bareOsRegisterKernelExtensionRecord`**, **`bareOsRunImageScript`** under **`/lib/bare-os/extensions/`** | Trusted image paths only. |
|
||||
|
||||
@@ -23,6 +23,7 @@ Use when the user asks about **HDMS** (Hyperdrive Management): **`hdms`** CLI, *
|
||||
- **Writable mounts:** **`hdms create <label>`** — new Corestore namespace + Hyperdrive, replicate to swarm.
|
||||
- **Read-only by key:** **`hdms add <label> <z32-key>`** — open an existing drive by key string.
|
||||
- **VFS:** paths **`/mnt/<label>/…`**; writable mounts allow **`put`** on those routes.
|
||||
- **`www` label:** A mount labeled **`www`** at **`/mnt/www`** also routes **`$HOME/.www`** and **`/home/<active>/.www`** in the VFS—the same docroot the stock **`bare-os-www`** initd serves by default. See **`handbook/05-identity-vault-and-hdms.md`** and **`handbook/04-the-booter-runtime.md`** § **bare-os-www**.
|
||||
|
||||
## Invite and pair (Autopass / BlindPairing)
|
||||
|
||||
|
||||
@@ -17,6 +17,7 @@ Use when the user asks about **Holesail** in this repo: exposing TCP/UDP through
|
||||
1. **Integration** lives in **`packages/bare-os-booter/lib/bare-holesail.js`** (initd + optional early “kernel-path” instance) and **`packages/bare-os-booter/lib/holesail-cli.js`** (**`ctx.bareOsRunHolesailCli`** for **`/bin/holesail`**).
|
||||
2. **Resolution order** under **`pear run`**: the booter prefers **`ctx.bare.holesail`** ( **`/lib/bare/bundles/holesail.js`** after drive merge), else host **`import.meta.resolve('holesail')`**, else eval of the drive IIFE bundle via **`ctx.vfs`** — **`/bin`** and **`/boot/init.js`** are **not** Node modules, so scripts must not **`require('holesail')`**.
|
||||
3. **Stock default**: initd unit **`bare-holesail`** is **on** when **`BARE_OS_HOLESAIL_INITD`** and **`BARE_OS_HOLESAIL_MANAGED`** are left at defaults (**`1`** in stock **`shellEnv`** unless the host clears them). Disable with **`BARE_OS_HOLESAIL_INITD=0`** or **`systemctl disable bare-holesail`** (**`~/.config/bare-os/initd/disabled.txt`**).
|
||||
4. **`bare-os-www`** (**`packages/bare-os-booter/lib/bare-os-www-initd.js`**) serves **`~/.www`** on **`127.0.0.1:8088`** by default. **`bare-holesail`** starts **after** it in the initd DAG so the stock managed entry **`bare-www-<port>`** (**`server: true`**, **`host: 127.0.0.1`**, **`port`** from **`BARE_OS_WWW_PORT`**) can reach the HTTP listener. Opt out of auto-merge with **`BARE_OS_WWW_HOLESAIL=0`**. Handbook: **`handbook/04-the-booter-runtime.md`** § **bare-os-www** and § **bare-holesail**.
|
||||
|
||||
## Managed vs single-tunnel mode
|
||||
|
||||
@@ -34,7 +35,7 @@ From **`holesail-cli.js`** help text:
|
||||
- **`holesail add ID --server|--client`** with optional **`--key`**, bare **`hs://…`** token (no **`--key`** prefix), **`--port`**, **`--host`**, **`--udp`**, **`--secure` / `--no-secure`**, **`--log`**.
|
||||
- **`holesail remove ID`**, **`start|stop|restart ID`**, **`enable|disable ID`**.
|
||||
|
||||
Initd starts after **`kernel-logger`** by default. Logs: **`/var/log/bare-os/holesail.log`**. Example unit drop-in: **`/etc/bare-os/units/bare-holesail.unit.example`** on the system image.
|
||||
Managed **`bare-holesail`** starts after **`kernel-logger`** and **`bare-os-www`** by default. Logs: **`/var/log/bare-os/holesail.log`**. Example unit drop-in: **`/etc/bare-os/units/bare-holesail.unit.example`** on the system image.
|
||||
|
||||
## Debugging and safety
|
||||
|
||||
|
||||
@@ -18,7 +18,8 @@ Use this skill whenever the user asks for system status, peer count, drive healt
|
||||
2. Call **`get_swarm_peers`** (and **`get_system_info`** as needed) for swarm / session context when exposed by the booter.
|
||||
3. Use **`read_proc_file`** on **`/proc/bare_os/*`** mirrors when the user cares about kernel/session metrics (see the **bare-os-kernel-proc** skill for feature/capability JSON).
|
||||
4. Check SSH/kernel narrative only when **`read_proc_file`** or **`read_man_page`** confirms how this image exposes **`sshd`** (do not assume **`node`** exists).
|
||||
5. Summarize in clear bullet points:
|
||||
5. When a **personal static site** matters, after **`login`** check **`~/.www`** (and optional **`curl -I http://127.0.0.1:8088/`**, or the port from **`BARE_OS_WWW_PORT`** in env); initd logs append to **`/var/log/bare-os/www.log`**.
|
||||
6. Summarize in clear bullet points:
|
||||
|
||||
- Drive sync status
|
||||
- Active peers
|
||||
|
||||
@@ -24,7 +24,7 @@
|
||||
|
||||
The **seeder** owns the **publisher** side: it stages the kernel tree into a system Hyperdrive, writes the **MBR** block that points at drive keys, and stays on the swarm so others can replicate.
|
||||
|
||||
The **booter** owns the **consumer** side: it looks up peers on the same topic, replicates the system drive, attaches or creates a **personal** drive, and starts the in-image runtime (**`/boot/init.js`**, shell, initd, cron as configured).
|
||||
The **booter** owns the **consumer** side: it looks up peers on the same topic, replicates the system drive, attaches or creates a **personal** drive, and starts the in-image runtime (**`/boot/init.js`**, shell, **initd** — including stock **`bare-os-www`** for **`~/.www`** on loopback — and cron as configured).
|
||||
|
||||
You almost always run them as **two separate processes** (two terminal tabs or windows). The booter needs a live seeder (or an already-replicated drive) to make progress within its boot timeout.
|
||||
|
||||
|
||||
@@ -31,7 +31,7 @@ Logical **`$HOME`**, **`/tmp`**, and **`/var/log`** map into stable prefixes on
|
||||
|
||||
**`login`** prompts for a passphrase. If an account already exists at **`/.bare/account`**, the booter decrypts it and derives session keys. **`login --new`** creates a **new** Ed25519 keypair and writes a versioned on-disk blob.
|
||||
|
||||
After a successful login, **`HOME`** moves under **`/home/<public-key-prefix>`**, **`BARE_OS_PUBLIC_KEY`** is set, and optional **HDMS** features become available for managing extra drives. **`logout`** clears sensitive state and returns you to **guest**. **`logout --save`** can combine logout with vault snapshotting (see below).
|
||||
After a successful login, **`HOME`** moves under **`/home/<public-key-prefix>`**, **`BARE_OS_PUBLIC_KEY`** is set, and optional **HDMS** features become available for managing extra drives. The booter also ensures **`~/.www/`** exists with a default **`index.html`** when missing (personal static site root). The initd unit **`bare-os-www`** serves that tree over HTTP on **`127.0.0.1:8088`** by default; see [Handbook — Chapter 4](../handbook/04-the-booter-runtime.md#bare-os-www-static-http-for-www). **`logout`** clears sensitive state and returns you to **guest**. **`logout --save`** can combine logout with vault snapshotting (see below).
|
||||
|
||||
Cryptographic details are implementation-specific; this manual stays at the behavior level. For prose-level crypto and flow diagrams, read [Handbook — Chapter 5](../handbook/05-identity-vault-and-hdms.md).
|
||||
|
||||
|
||||
@@ -10,6 +10,7 @@
|
||||
- [Missing binaries or stale image](#missing-binaries-or-stale-image)
|
||||
- [Environment variables](#environment-variables)
|
||||
- [SSH server (bare-openssh)](#ssh-server-bare-openssh)
|
||||
- [Personal static HTTP (bare-os-www)](#personal-static-http-bare-os-www)
|
||||
- [Themes and terminals](#themes-and-terminals)
|
||||
- [CI and contributing](#ci-and-contributing)
|
||||
- [Pretest and verifier failures](#pretest-and-verifier-failures)
|
||||
@@ -63,7 +64,7 @@ When debugging, ask whether the variable was set on the **host** before launchin
|
||||
|
||||
## SSH server (bare-openssh)
|
||||
|
||||
The stock booter starts initd unit **`bare-openssh`**, which runs an SSH-2 server inside the booter process (not a forked host **`sshd`**). **`/bin/sshd`** in the image calls **`ctx.bareOsRunSshdCli`**; configuration is **`/etc/ssh/sshd_config`** on the system drive, while **host keys** are stored on the **personal** drive (default under **`~/.config/bare-os/ssh/host/`**), so a read-only **`/etc`** is fine.
|
||||
The stock booter starts several **initd** units after the console exists, including **`kernel-logger`**, **`bare-os-www`** (loopback HTTP for **`~/.www`**, default port **8088**), **`bare-holesail`** (managed tunnels; starts after **`bare-os-www`** so stock **`bare-www-*`** entries can reach the HTTP port), **`bare-cron`**, **`bare-openssh`**, and **`bare-os-chat`** when enabled. Unit **`bare-openssh`** runs an SSH-2 server inside the booter process (not a forked host **`sshd`**). **`/bin/sshd`** in the image calls **`ctx.bareOsRunSshdCli`**; configuration is **`/etc/ssh/sshd_config`** on the system drive, while **host keys** are stored on the **personal** drive (default under **`~/.config/bare-os/ssh/host/`**), so a read-only **`/etc`** is fine.
|
||||
|
||||
- **Localhost default** — Stock **`ListenAddress`** is **`127.0.0.1`**. To listen on all interfaces, set host **`BARE_OS_SSH_BIND_ALL=1`** (this remaps **`127.0.0.1`** to **`0.0.0.0`** when that is the configured address) or edit **`sshd_config`** on your image.
|
||||
- **Port override** — Host **`BARE_OS_SSH_LISTEN_PORT`** overrides **`Port`**; use **`0`** for an ephemeral port (automation/tests).
|
||||
@@ -75,6 +76,17 @@ See **`man sshd`** and **`man sshd_config`** in-guest after building **`bare-os-
|
||||
|
||||
---
|
||||
|
||||
## Personal static HTTP (bare-os-www)
|
||||
|
||||
Initd **`bare-os-www`** serves **`GET`/`HEAD`** from **`~/.www`** on **`127.0.0.1:8088`** by default ( **`BARE_OS_WWW_PORT`** / **`BARE_OS_WWW_HOST`** override bind and port). Access and path rules: [Handbook — Chapter 4](../handbook/04-the-booter-runtime.md#bare-os-www-static-http-for-www).
|
||||
|
||||
- **Logs** — **`/var/log/bare-os/www.log`** (same **`/var/log/bare-os`** tree as other initd services).
|
||||
- **Quick check** — After **`login`**, **`curl -I http://127.0.0.1:8088/`** should show a non-zero **`Content-Length`** for **`/`** when **`~/.www/index.html`** exists.
|
||||
- **Disable the unit** — **`BARE_OS_WWW_INITD=0`** or add **`bare-os-www`** to **`~/.config/bare-os/initd/disabled.txt`** for the next session.
|
||||
- **Holesail row** — With stock managed **`bare-holesail`**, **`bare-www-<port>`** is merged into **`~/.holesail/state.json`** after the listener is up (**`host: 127.0.0.1`**). Set **`BARE_OS_WWW_HOLESAIL=0`** to skip auto-merge.
|
||||
|
||||
---
|
||||
|
||||
## Themes and terminals
|
||||
|
||||
**Symptom: colors or `ls --color` look wrong.** Themes interact with **`LS_COLORS`**, **`~/.barerc`**, and the **truecolor** versus **256-color** capability of your terminal emulator. Read the themes documentation and handbook notes rather than chasing random color codes:
|
||||
|
||||
Reference in New Issue
Block a user