Bom Pi

Your durable Pi console — every host, one browser.

A durable, multiplayer, mobile-first web app for Pi agents, built on Pi Durable. Fork of pi-pocket — renamed and extended as Bom Pi; fresh data starts in ~/.bom-pi.

• Pair another machine from the console. The rail's machines sheet has Pair a machine: make an invite (a code the other machine enters), review the requests waiting on you (with the requester's suffix to confirm before you approve), and switch the relay on or off — off until you press it. A paired machine then appears in the picker, and the session list labels every row with the machine it belongs to; looking at a remote host scopes the whole console (views, drafts, approvals, notifications) through the relay, and anything not routed refuses honestly with that machine's name. Runs on your own machine or directly on your phone. No cloud VM.

Website · Quick start · Feature tour · Docs

Highlights

• Durable. Every model call, tool call, and subagent is stored as it happens. Restart the server mid-run, and the work continues.
• Multiplayer. Share a live session with presence, a side chat Pi does not see, invites, and roles.
• Made for phones. Push notifications, dictation, sharing into Pi from other apps, and a home-screen app.
• PiP. An assistant that starts, follows, and reports on your other sessions, and watches GitHub for you.
• Your models. Pi's own providers, sign-ins, skills, and prompt templates, with the model chosen per session.
• Live-editable. No build step. Pi can change Bom Pi while it runs, and you can add your own extensions.

The feature tour covers everything else, from plan mode and peek tiles to the built-in browser.

Quick start

Requires Node.js 22.19 or newer. Runs on Linux, macOS, Windows, and Android (Termux); Linux is the most tested. Sign in to a provider with Pi first (pi, then /login), or later from the app's Providers sheet.

npm install -g bom-pi
bom-pi

Newer npm may print "install-scripts ... not yet covered by allowScripts" for @google/genai and protobufjs, which come from Pi's model library. The warning is expected: Bom Pi needs neither script. npm config set allow-scripts=@google/genai,protobufjs --location=user quiets it by letting both run, which does no harm.

Or try it with npx bom-pi. To change Bom Pi's code, run a git checkout instead:

git clone https://github.com/baphuongna/bom-pi.git
cd bom-pi
npm install
npm start

The launcher asks how your devices should connect, then prints a sign-in link and a QR code. The link is the owner's key: keep it private. --rotate-token replaces it and signs out every device that used it.

While it runs: q quit · r restart server · a change access · o open in browser · s show QR code.

Updating: Menu → Update Bom Pi updates a git checkout run with npm start, or a global npm install (npm install -g bom-pi) that your user can write, and restarts. It goes back by itself if the new version does not start (features). A local install (npm install bom-pi in a project) and npx bom-pi do not update from the app: the sheet says what to run, npm install bom-pi@latest or npx bom-pi@latest. By hand: stop the server, back up ~/.bom-pi, pull, run npm install, and start again; for a global install, run npm install -g bom-pi@latest. If the machine stops at the very moment of the switch, bom-pi may not start; npm install -g bom-pi restores it. Read the release notes first: 0.21.0 upgrades the database one way, so going back needs the backup.

Other ways to run it

• Docker or Podman: docker compose up -d --build. See docs/docker.md.

• Nix: nix run github:baphuongna/bom-pi, or the NixOS module services.bom-pi.enable = true; (nix/module.nix).

• Android (Termux):

  pkg update && pkg upgrade && pkg install nodejs git
  npm install -g --ignore-scripts @earendil-works/pi-coding-agent
  pi    # /login, then quit
  git clone https://github.com/baphuongna/bom-pi.git
  cd bom-pi && npm install --ignore-scripts && termux-wake-lock && npm start

  Lancet Guard may not load on Android. If it is on but fails, start with BOM_PI_GUARD=off.

Remote access

Choose a mode in the launcher, or pass --access:

| Mode | Who can connect | Notes | | ----------------- | -------------------- | ---------------------------------------------------------- | | local | This machine | 127.0.0.1; bring your own tunnel to port 8787 | | lan | Your local network | Plain http | | cloudflare | Anyone with the link | Free https quick tunnel, no account; needs cloudflared | | tailscale | Your tailnet | Tailscale address only | | tailscale-serve | Your tailnet | https at the tailnet name; needs tailscale 1.52 or newer |

tailscale-serve needs the tailscale command on your PATH, signed in, with MagicDNS and HTTPS certificates enabled in the tailnet, and, when the launcher does not run as root, that user as tailscaled's operator (sudo tailscale set --operator=$USER). It serves port 443 at the machine's tailnet name, and a server restart keeps the address. When the launcher quits it takes down the mount it made; one it found already in place is left where it is. Without the command the launcher says so and stops rather than falling back to this device only when nobody is there to pick another mode. --host cannot be combined with it: serve always listens on 127.0.0.1 and lets tailscaled reach it. For another tunnel (ngrok), choose local and point it at port 8787.

Other options: --port (8787), --cwd, --data (~/.bom-pi), --host, and -y to reuse the last access choice. --host overrides the address a named mode would listen on, and one launcher runs per data folder (a second one says which pid holds it). npm start -- --help lists them all. BOM_PI_BROWSER and BOM_PI_BROWSER_ARGS pick the built-in browser and its flags when Chromium or Chrome is not found by itself. BOM_PI_PROMPT_DATE=1 puts today's date in Pi's system prompt; it is left out by default, so the prompt cache does not start over when the date changes. BOM_PI_CACHE_KEEPER=off turns off the prompt cache keeper, which keeps a model's prompt cache warm while a run waits on a tool call (features). BOM_PI_KEEPALIVE_SECONDS (default 5, from 1 to 3600) is how long the server keeps an idle connection open for its next request. Behind a reverse proxy of your own (Caddy, nginx, a load balancer), set it above the proxy's idle timeout, or set the proxy's below it: otherwise the proxy can send a request on a connection as the server closes it, and answers with a 502. Caddy keeps idle connections for 2 minutes by default, so BOM_PI_KEEPALIVE_SECONDS=125, or keepalive 4s in Caddy's transport http block.

[!WARNING] Anyone who can steer a session can make Pi run commands on this machine, as you. That reaches your files, Bom Pi's own settings and tokens, and its code. Invite only people you would trust at your keyboard. View-only users cannot make Pi act. SECURITY.md says what is protected and what is not.

Documentation

• Feature tour: every feature, in full.
• Docs site: customizing Pi without code, and writing extensions.
• Engineering and code map: how Bom Pi is built.

Development

npm run check   # type-check
npm test        # server tests with a scripted model
npm run format  # ESLint's layout fixes, then Prettier
npm run lint    # check the layout rules

web/ changes reload every open browser, and extensions reload into the running server. node test/serve.ts runs a throwaway copy to check a change on. AGENTS.md covers editing Bom Pi safely from inside itself, and CONTRIBUTING.md how to send a change.

Limitations

• Pi Durable is experimental, and its API can change between releases. Versions are pinned in package.json.
• Only one server process can use the database at a time.
• Pi's own extensions are not supported. Bom Pi runs its own, on Pi Durable.
• A git worktree keeps a session's files apart; it is not a sandbox.
• The built-in browser needs Chromium, Chrome, Brave, or Edge on the server. It is tested on Linux and macOS.

The full list has the details.

Credits and license

Inspired by Mario Zechner's demo of his own Pi app. Bom Pi is an independent project, not affiliated with Earendil. The bundled fonts keep their own licenses, which are beside them in web/fonts/.

MIT. To report a security problem, see SECURITY.md.