PI WEB

This is a personal fork. Forked from jmfederico/pi-web. It tracks upstream and adds a few local changes (terminal spawn fix, file preview for HTML/Markdown/PDF, file delete/rename, client-side token-speed display). The original project lives at https://github.com/jmfederico/pi-web and its website/docs at https://pi-web.dev/.

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.

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 multiple 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 remote machines from one web UI.

Your browser is the control surface. The work stays where it can keep running.

Quick start

Requirements:

• Node.js 22 or newer
• npm
• Pi Coding Agent installed and configured for your user (i.e. a working ~/.pi directory)
• git and the development tools your agents need

Option A — Run from source (this fork)

git clone <your-fork-url> pi_web
cd pi_web
npm install
npm run dev

Then open the Vite dev URL printed in the terminal:

http://localhost:4444

npm run dev starts three things together: the long-lived session daemon, the API server, and the Vite UI. The browser talks to Vite (4444), which proxies /api to the API server (8504 by default).

For the split setup (run each in its own terminal), use:

npm run dev:sessiond   # session daemon (long-lived, holds active Pi sessions)
npm run dev:web        # API server + plugin builder
npm run dev:client     # Vite UI

Note: the session daemon must be restarted manually to pick up changes to src/server/sessiond.ts or the session daemon protocol. The API/UI side autoreloads via tsx watch / Vite HMR.

Validate changes with:

npm run verify          # typecheck + lint + knip + tests

Option B — Install from npm (upstream)

The upstream package is published to npm as @jmfederico/pi-web:

npm install -g @jmfederico/pi-web
pi-web install          # installs per-user launchd/systemd services
pi-web doctor           # checks your setup
pi-web status
pi-web logs
pi-web restart

Then open:

http://127.0.0.1:8504

See the upstream installation guide for one-line installs, Pi package install, WSL/manual usage, and remote access.

Core model

PI WEB organizes work like this:

Machine     a local or remote PI WEB runtime endpoint
Project     a folder on that machine
Workspace   a git worktree, or the project folder for non-git projects
Session     a Pi Coding Agent chat running inside a workspace

A typical flow:

1. Add a project.
2. Choose a workspace or git worktree.
3. Start a session.
4. Let the agent work.
5. Come back later from any browser.

Remote-first development

PI WEB is designed for remote AI-driven development.

Instead of tying agent work to your laptop session, run PI WEB on a machine that stays available: a server, desktop, cloud VM, home lab machine, or remote dev box.

Use a private network, SSH tunnel, trusted reverse proxy, or federated PI WEB machine setup when accessing it remotely.

Read more: Remote-first development

Machines and fleets

PI WEB can register other PI WEB runtimes as remote machines. One browser-facing PI WEB instance can proxy projects, files, git state, sessions, terminals, and activity from trusted remote machines.

Read more: Fleet and machines guide

Plugins

PI WEB supports trusted local browser-side plugins that can add actions, workspace panels, and workspace metadata.

Read more: Plugin API

Configuration

Global config lives at:

$PI_WEB_CONFIG
~/.config/pi-web/config.json

Project-local PI WEB config lives at:

<project>/.pi-web/config.json

Common configuration includes host/port, path access, uploads, plugins, shortcuts, and session daemon options.

Read more: Configuration reference

Development

See Quick start → Option A above for the run-from-source flow.

Key scripts:

npm run dev            # sessiond + API + Vite UI together
npm run dev:sessiond   # session daemon only
npm run dev:web        # API server only
npm run dev:client     # Vite UI only
npm run build          # production build
npm run verify         # typecheck + lint + knip + tests
npm test               # vitest

Security model

PI WEB assumes trusted users, trusted repositories, and trusted server paths.

It is not a sandbox, permission system, or multi-tenant platform. Do not expose it directly to the public internet without a trusted network, firewall, VPN, SSH tunnel, or authenticated reverse proxy.

Documentation

• Website
• Install
• Remote-first development
• Machines / fleet
• Configuration
• Plugins
• FAQ

License

MIT © 2026 Federico Jaramillo Martinez. See LICENSE.