@gang-of-beads/pi-web2.202610.14

Web UI for persistent Pi Coding Agent sessions in real workspaces.

GitHub Actions Published 2 days ago MIT ~6K downloads/mo

Untested on omp

This is a pi package. No one has reported whether it works on omp yet. If you try it, add your result below.

Reports 0

No reports yet.

Readme

PI WEB

PI WEB is a web UI for Pi Coding Agent that keeps agent sessions running in real workspaces on your machine or server.

Run agents where your code, tools, credentials and build caches live. Supervise them from any browser.

PI WEB on a desktop: sessions, a conversation and the project's files

The session board on a phone The Go to menu on a phone A conversation on a phone in Material Light

On a phone: the session board, the Go to menu, and a conversation in the light theme.

Why PI WEB?

Agentic development works better when the work environment is persistent. PI WEB lets you:

keep Pi Coding Agent sessions alive after browser disconnects;
run agents inside real repositories and git worktrees;
supervise several sessions in parallel;
switch between laptop, phone, tablet and desktop;
use a server, workstation or remote dev box as your agent runtime;
manage projects, workspaces, files, terminals, sessions and other machines from one web UI.

Your browser is the control surface. The work stays where it can keep running. See Remote-first development.

Quick start

Requirements:

Node.js 22.19.0 or newer, and npm, on your login-shell PATH and able to npm install -g without sudo; see Requirements for nvm and distribution packages
Pi Coding Agent 1.3.0 or newer, configured for your user
git and the development tools your agents need; on Linux also python3, make and a C++ compiler (for example build-essential), which npm uses to build the terminal
Linux or macOS with a per-user service manager (systemd or launchd), Windows 10 or 11 (per-user scheduled tasks), or Termux on Android (termux-services)

Recommended setup

Run PI WEB with the Gang of Beads preset on the machine where your code lives, publish it to your tailnet with Tailscale Serve, and use it from your phone.

Install PI WEB as per-user services, with the agent tools and Web plugins of the Gang of Beads preset:
```
curl -fsSL https://raw.githubusercontent.com/Gang-of-Beads/pi-web/main/install.sh | sh -s -- --preset gang-of-beads
```
On a Linux server, also run sudo loginctl enable-linger "$USER" so the services keep running after you log out.

On Windows, run this in PowerShell instead:
```
$env:PI_WEB_PRESET = "gang-of-beads"; irm https://raw.githubusercontent.com/Gang-of-Beads/pi-web/main/install.ps1 | iex
```
Publish it to your tailnet with Tailscale Serve (MagicDNS and HTTPS certificates enabled). PI WEB stays on loopback, and your devices get the HTTPS that dictation and the clipboard need:
```
tailscale serve --bg --https=8504 http://127.0.0.1:8504
```
On your phone, signed in to the same tailnet, open https://<machine>.<tailnet>.ts.net:8504 and add it to the Home Screen (Safari: Share → Add to Home Screen). It opens as an app: see Install on iPhone or iPad.

PI WEB alone, without the preset:

curl -fsSL https://raw.githubusercontent.com/Gang-of-Beads/pi-web/main/install.sh | sh

On Windows, in PowerShell (Windows has the details):

irm https://raw.githubusercontent.com/Gang-of-Beads/pi-web/main/install.ps1 | iex

Then open http://127.0.0.1:8504, or publish it as in step 2.

npm, Nix, Home Manager, Docker, installing through Pi, WSL and manual runs: see the installation guide.

Everyday commands:

pi-web status
pi-web logs
pi-web restart
pi-web doctor
pi-web version
pi-web uninstall

Core model

Machine     a PI WEB runtime: the one you opened, or another one you added
Project     a folder on that machine
Workspace   a working folder of the project: the project folder, or with Git, each worktree
Session     a Pi Coding Agent chat running inside a workspace

A typical flow: add a project, choose a workspace or git worktree, start a session, let the agent work, and come back later from any browser.

Security

PI WEB has no login of its own and assumes trusted users, repositories and server paths; it is not a sandbox or a multi-user platform. Keep it on localhost, a private network, an SSH tunnel or an authenticated reverse proxy, never directly on the public internet. See SECURITY.md for the threat model and how to report a vulnerability.

Documentation

Install: requirements, install options, services, updates, remote access
Configuration: config files, keys, environment variables, restart rules
Machines: use several PI WEB machines from one page
Remote-first development
Plugins: PI WEB plugins and Pi packages
FAQ and troubleshooting

Plugins and packages maintained alongside PI WEB: docs/plugins.md.

Contributing

See CONTRIBUTING.md for the development setup, checks and pull request expectations.