pi-web: A Browser Front End That Keeps Pi Coding Agent Sessions Alive in Real Workspaces
Web UI for Pi Coding Agent that keeps sessions alive in real workspaces.
At a glance
- What is it?
- pi-web is a TypeScript web UI for Pi Coding Agent that runs agent sessions on a persistent machine and lets you supervise them from any browser. It is not a sandbox and assumes trusted users, so its value depends on how you handle access.
- Who is it for?
- Adopt pi-web if you are a solo developer or a small trusted team running Pi Coding Agent on a machine that stays on, and you want to switch between laptop, phone, and desktop without losing agent state. Do not adopt it if you need multi-tenant isolation or public-internet exposure, because the README explicitly says it is not a sandbox or permission system.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 4 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 14, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
What pi-web solves and who it targets
Pi Coding Agent, like many coding agents, runs in a chat loop that can be tied to the terminal or IDE where you started it. If your browser tab closes or your laptop sleeps, the session may die with it. pi-web addresses that by separating the control surface from the execution environment. The README states that pi-web is a web UI for Pi Coding Agent that keeps agent sessions running in real workspaces on your machine or server. The target user is someone who wants to run agents on a persistent box, such as a server, desktop, cloud VM, or remote dev box, and supervise them from any browser. That includes switching between laptop, phone, tablet, and desktop mid-session. The project is not aimed at teams that need per-user isolation or fine-grained permissions; the security model section makes that clear.
Core model: machines, projects, workspaces, sessions
The README defines a four-level hierarchy. A Machine is a local or remote pi-web runtime endpoint. A Project is a folder on that machine. A Workspace is a provider-owned working folder; the bundled Git provider discovers worktrees, otherwise it uses the project folder. A Session is a Pi Coding Agent chat running inside a workspace. The flow is straightforward: add a project, choose a workspace or git worktree, start a session, let the agent work, and come back later from any browser. The key design choice is that the session lives in the workspace, not in the browser. That means the agent can access your code, tools, credentials, and build caches where they already exist. The browser is only a control surface. This is a different model from running an agent in a cloud sandbox that has to be configured separately.
Installation and first run
The quick start assumes Node.js 22.19.0 or newer, npm, Pi Coding Agent version 0.84.0 or newer, and git plus the development tools your agents need. The install command is npm install -g @jmfederico/pi-web --allow-scripts=node-pty. The README notes that on npm 12, the scoped flag lets node-pty prepare its required native module without enabling install scripts for other dependencies. After installing, you run pi-web install and then pi-web doctor. The web UI opens at http://127.0.0.1:8504. Useful commands include pi-web status, pi-web logs, pi-web restart, pi-web doctor, pi-web version, and pi-web uninstall. The README points to an installation guide for one-line install, Pi package install, WSL, and manual usage. For development, you clone the repo, run npm install and npm run dev, and open the Vite URL, usually http://localhost:8505. There is also a split setup with npm run dev:sessiond, npm run dev:web, and npm run dev:client.
Remote-first design and the fleet concept
pi-web is explicitly designed for remote AI-driven development. The README recommends running pi-web on a machine that stays available, and accessing it via a private network, SSH tunnel, trusted reverse proxy, or a federated pi-web machine setup. The fleet feature lets one browser-facing pi-web instance register other pi-web runtimes as remote machines. That instance can proxy projects, files, git state, sessions, terminals, activity, Pi package management, and selected-machine settings from trusted remote machines. There is a clear split: machine-affecting settings like Pi packages, plugin enablement, session daemon toggles, external file access, and upload defaults target the selected remote machine. Gateway settings like host, port, allowed hosts, registered machines, tokens, and keyboard shortcuts stay local to the browser-facing instance. This is a practical way to manage multiple machines from one UI, but it also means you need to trust every registered machine, because it can access your files and credentials.
Configuration and project-local settings
Global configuration lives at $PI_WEB_CONFIG or ~/.config/pi-web/config.json. Project-local configuration lives at <project>/.pi-web/config.json. The README lists common configuration keys: host/port, path access, uploads, PI WEB plugin enablement, shortcuts, and session daemon options. The distinction between machine-affecting and gateway-local settings is repeated in the configuration section, which suggests that the same setting name may behave differently depending on where it is set. For example, a plugin enablement flag in a project config might target the selected machine, while a keyboard shortcut stays local. This is a useful separation, but it also means you have to read the configuration reference to know which tab in Settings is being changed. The README does not give example JSON for these files, so you would need to consult the docs at pi-web.dev/config to see actual key names and values.
Security model is a hard boundary
The README is explicit: pi-web assumes trusted users, trusted repositories, and trusted server paths. It is not a sandbox, permission system, or multi-tenant platform. The advice is to not expose it directly to the public internet without a trusted network, firewall, VPN, SSH tunnel, or authenticated reverse proxy. This is a genuine limitation, not a minor caveat. If you want to run pi-web for a team where users should not see each other's files, or if you need to restrict what the agent can do, pi-web is the wrong tool. The project does not attempt to provide isolation. The value proposition is persistence and convenience, not security. For a solo developer on a home server, that trade-off is acceptable. For a company with strict access controls, it is not.
Plugins and Pi packages: two separate concepts
pi-web supports trusted browser plugins plus optional sessiond-backed workspace providers. The bundled Git provider uses the same public provider and backend contracts available to installed plugins. You manage plugins via Settings -> PI WEB plugins on the selected machine. The README draws a clear line between Pi packages and PI WEB plugins: a Pi package may include a PI WEB plugin, but installing a package and enabling it are different operations. Server-backed changes require a session-daemon restart, so you should read the plugin guide for lifecycle and recovery details. This separation is sensible but adds operational complexity. If you install a Pi package that includes a plugin, you still have to enable it, and you may need to restart the session daemon. The README does not specify how to do that restart, only that it is required. This is a point to verify in the docs before relying on plugins in production.
Alternatives and the real difference
The obvious alternative is to run Pi Coding Agent directly in a terminal or IDE on your local machine. That approach ties the session to your laptop and does not survive a disconnect. Another alternative is a cloud-based coding agent service that runs in a managed sandbox, which gives you persistence but takes your code and credentials out of your control. pi-web sits in between: it keeps your code on your own machine or server, but it adds a web layer that requires you to manage the network and security yourself. Compared to a terminal-based workflow, pi-web adds a browser UI, session persistence across disconnects, and the ability to supervise multiple sessions in parallel. Compared to a cloud service, pi-web keeps everything on your hardware but offers no isolation. The choice depends on whether you value control over convenience and whether you can secure a network path to the machine.
Editorial conclusion
Adopt pi-web if you are a solo developer or a small trusted team running Pi Coding Agent on a machine that stays on, and you want to switch between laptop, phone, and desktop without losing agent state. Do not adopt it if you need multi-tenant isolation or public-internet exposure, because the README explicitly says it is not a sandbox or permission system. Before deploying, verify your network path: use a private network, SSH tunnel, or authenticated reverse proxy, and confirm that Pi Coding Agent >=0.84.0 is configured for your user. Check the plugin lifecycle notes if you plan to use sessiond-backed workspace providers, since server-backed changes require a session-daemon restart. The project's value is tied to its persistent-session model, not to any sandboxing promise.
Community notes