Chapter 7 — Apps beyond the shell

Bare OS now ships a P2P App Store client (/bin/appstore) and guest Pear tooling (/bin/pear) so “applications” can be authored, published, installed, and launched inside the shell without a second GUI runtime.

This chapter orients you to what is real today versus what still requires a host Pear process.

Four application models

Model	When to use	Entry points
Shell + `/bin` + files	Scripts, pipelines, git on the VFS	`$HOME`, `run(ctx, argv)` utilities
Guest TUI	Full-screen terminal apps in the session	`ctx.tui.run(model)` — Chapter 20, `tui demo`
Pear app (guest)	P2P apps with `pear://` distribution	`pear init` → `stage` → `release` → `appstore install` → `launch`
Host Pear app	Custom booter/seeder images, native addons, desktop Pear	Repo root `pear run`, new Pear project (Chapter 1)

Most end-user Pear apps you build in Bare OS follow the guest Pear + App Store row. See Guest Pear and App Store workflow for copy-paste commands.

Guest Pear pipeline (`/bin/pear`)

Implemented in packages/bare-os-coreutils (pear.js, pear-stage.js, pear-release.js).

pear init
cd ~/pear-projects/my-pear-app
pear stage
login                    # unlock identity / HDMS
pear release .
pear seed .

pear stage — Writes <project>/.pear/stage/ (sources/, package.json, app.bundle.js, stage.json).
pear release — Mirrors the stage tree onto a writable HDMS mount (/mnt/pear-<name>/) and prints pear:// links (uses HDMS registry keys; does not require host Pear CLI).
pear seed — Best-effort Hyperswarm flush so peers can replicate the release drive.

Release metadata is stored in <project>/.pear/release.json.

P2P App Store (`/bin/appstore`)

Implemented in packages/bare-os-coreutils (appstore.js, appstore-pear.js, p2p-suite.js preamble).

appstore install my-app pear://0.<length>.<key> --yes
appstore launch my-app

install — Fetches the pear:// release tree (local HDMS mount with matching key, or ephemeral readonly HDMS fetch) into ~/.appstore/packages/<name>/ (or /mnt/appstore/packages/<name>/ when the store HDMS drive is mounted).
launch — Runs the materialized entry script (sources/index.js or package.json main) in the guest shell; output appears on ctx.console.
update — Re-fetches from the package’s stored pearLink.
setup — Prints how to create/mount the optional appstore HDMS label.

Design and trust model: p2p-app-store.md.

The default platform: shell + `/bin` + git

Workflows that are not Pear-packaged still use:

Scripts in $HOME (run(ctx, argv)).
Pipelines and redirection (simulated stdin/stdout).
git on the VFS (Handbook ch.8).

initd, cron, and services

initd — User units under ~/.config/bare-os/units/. appstore services can generate initd unit stubs for packages that declare a service manifest (see appstore.js).

Timers / cron — See Chapter 11 and handbook ch.4.

HDMS and `/mnt`

After login, HDMS mounts extra Hyperdrives under /mnt/<label>/. Pear releases use labels like pear-my-pear-app. The App Store prefers label appstore at /mnt/appstore.

User scripts should use ctx.vfs rather than hard-coding drive handles.

Replacing the kernel

Shipping a different /boot/init.js remains a kernel image change (non-interactive worker, custom menu, etc.). Pear user apps do not require replacing the stock kernel.

When you need a new host Pear app

Use a new Pear application on the host when you need:

A different system image or booter embedding model
Native addons unsuitable for AsyncFunction /bin scripts
Desktop/mobile Pear runtime features

Guest pear release still produces valid pear:// links consumable by host pear run.

4.6 KiB Raw Blame History Unescape Escape

Chapter 7 — Apps beyond the shell

Four application models

Guest Pear pipeline (/bin/pear)

P2P App Store (/bin/appstore)

The default platform: shell + /bin + git