# Chapter 7 — “Apps” beyond the shell (what is realistic today)
# Chapter 7 — Apps beyond the shell
Bare OS does not have an appstore, sandboxed widgets, or a second GUI runtime inside the image. An **application** here is usually:
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.
- a **workflow** built from the **shell**, **`/bin`** tools, and files on the **personal** drive; or
- a **custom kernel** + utilities; or
- a **host Pear app** that changes boot behavior.
This chapter orients you without over-promising.
This chapter orients you to what is **real today** versus what still requires a **host Pear** process.
---
## The default “app”: shell + `/bin` + git
## Three application models
Most user goals are met by:
| Model | When to use | Entry points |
| --- | --- | --- |
| **Shell + `/bin` + files** | Scripts, pipelines, git on the VFS | `$HOME`, `run(ctx, argv)` utilities |
Most **end-user Pear apps** you build in Bare OS follow the **guest Pear + App Store** row. See **[Guest Pear and App Store workflow](../docs/guides/guest-pear-and-appstore-workflow.md)** for copy-paste commands.
---
## Guest Pear pipeline (`/bin/pear`)
Implemented in `packages/bare-os-coreutils` (`pear.js`, `pear-stage.js`, `pear-release.js`).
- **`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).
- **`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](../docs/design/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`** for repositories on the VFS (see [Handbook ch.8](../handbook/08-git-on-bare-os.md)).
That is the **intended** application platform for end users.
- **`git`** on the VFS ([Handbook ch.8](../handbook/08-git-on-bare-os.md)).
---
## initd and background flavor
## initd, cron, and services
The booter registers **initd**-style disposers via [`bare-initd.js`](../packages/bare-os-booter/lib/bare-initd.js). The stock system uses this lightly (e.g. kernel logger). **Extending** this usually means **host** booter changes: register a start function during `executeKernel`, not from arbitrary `/bin` scripts.
**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`).
Read [`bare-initd.js`](../packages/bare-os-booter/lib/bare-initd.js) before adding long-running tasks—teardown must be explicit (`stopBareInitd`).
---
## Cron and timers
**`bare-cron`** reads **`/etc/bare-os/crontab`** on the system image (if present), then the user’s **`~/.crontab`** on the personal drive; invalid lines are logged and skipped. **`crontab`** installs/lists/removes the **user** file (requires login). Timer drop-ins under `**~/.config/bare-os/timers/*.timer`** (**`[Timer]`** `**OnCalendar=**` + `**ExecLine=`**) merge into the same minute scheduler. See [Handbook ch.4](../handbook/04-the-booter-runtime.md) and [Developer guide ch.11](11-kernel-pear-cookbook.md).
**Socket-shaped activation:** initd unit drop-ins can set **`SocketActivationIpc=<fifo-name>`** so a service’s **`start()`** runs when something first **`readFile`**s that logical FIFO under **`/run/bare-os/ipc/`** (see **`bare-initd.js`**).
**Timers / cron** — See [Chapter 11](11-kernel-pear-cookbook.md) and handbook ch.4.
---
## HDMS and `/mnt`
After identity unlock, optional **HDMS** mounts may appear under **`/mnt`**. Utilities use **`ctx.vfs`**; HDMS integration is advanced and covered narratively in the handbook (identity + HDMS chapter). User scripts should prefer **`vfs.readFile`** /**`writeFile`** over hard-coding drive objects.
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
A heavier “app” might ship a **different `/boot/init.js**`—for example a menu-driven UI using **`readLine`** or a non-interactive worker when `**BARE_OS_SKIP_REPL=1`**. You still have the **single JavaScript realm** per session; there is no fork into a second Bare process from inside the image.
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 actually need a new Pear app
## When you need a new host Pear app
If you need **multiple OS images**, **custom networking**, or **native addons** not suitable for `AsyncFunction` utilities, create a **new Pear application** that embeds or forks the booter pattern—this is **host** development (Chapter 1), not `/bin` development.
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`**.
---
## See also
- [Guest Pear and App Store workflow](../docs/guides/guest-pear-and-appstore-workflow.md)
- [Chapter 12 — Bare modules and Pear](12-bare-modules-and-pear-ecosystem.md)
- **Guest Pear apps** — Author, release, install, and launch Pear apps entirely in the shell: see **[Guest Pear and App Store workflow](../docs/guides/guest-pear-and-appstore-workflow.md)** (`/bin/pear`, `/bin/appstore`). Host **`pear run pear://…`** remains for full Pear desktop/runtime on a Pear-capable machine.
- **Release metadata** — Host can set `BARE_OS_PEAR_CHANNEL`, `BARE_OS_PEAR_RELEASE`, and `BARE_OS_IMAGE_DIGEST`; they appear in `/run/bare-os/boot.json`.
- **`ctx.bareOsRequestPearReload()`** — Returns hints and env strings; the host `**pear-runtime` / `pear-runtime-updater**` must perform any real reload. A successful host reload can swap the Pear **booter** bundle so a new **`bare-module-manifest.data.mjs`** (from **`npm run sync:bare-manifest`** at staging time) takes effect; **`ctx.bareOsRequestPearReload`** does not rewrite **`ctx.bare`** in-process—expect a new guest boot for an updated host import list. Drive-only edits to **`/lib/bare/bare-module-manifest.json`** still merge bundles from the image without re-staging Pear.
This enables creating, staging, and (with host delegates) releasing real Pear apps entirely from inside a booted Bare OS instance, with natural integration into the P2P App Store.
**Guest workflow (no host Pear CLI required for release):**
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
