# jmfederico/pi-web: a persistent web UI for Pi Coding Agent sessions > pi-web keeps Pi Coding Agent chats running inside real repositories and git worktrees, then lets you supervise them from any browser. It assumes trusted users and trusted paths, and it is not a sandbox. **jmfederico/pi-web** — Web UI for Pi Coding Agent that keeps sessions alive in real workspaces. - Repository: https://github.com/jmfederico/pi-web - Website: https://pi-web.dev/ - Stars: 813 · Forks: 163 - Language: TypeScript - License: MIT - Published: 2026-08-08 · Updated: 2026-08-18 · Language: en - Canonical page: https://hysenlabs.com/projects/jmfederico-pi-web ## The problem pi-web solves: agent work that dies with the tab A coding agent is only useful while it is running. If the agent process is tied to a browser tab, closing the laptop ends the run. pi-web separates the two. The README states the project "keeps agent sessions running in real workspaces on your machine or server," and that sessions stay alive after browser disconnects. The browser becomes a control surface rather than the runtime. The second problem is location. Agents need the repository, the git history, the credentials and the build caches. Running them against a copy of the code on a hosted runner means those things are missing or duplicated. pi-web runs the session inside a workspace on a machine you choose, which the README describes as a server, desktop, cloud VM, home lab machine, or remote dev box. The intended audience is a developer who already has Pi Coding Agent configured and wants to point it at real checkouts, including several at once. The README lists supervising multiple sessions in parallel and switching between laptop, phone, tablet and desktop as core capabilities. ## Machine, project, workspace, session: how pi-web models the work The README lays out four levels. 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, where bundled Git discovers worktrees and otherwise the project folder is used. A session is a Pi Coding Agent chat running inside a workspace. That nesting is the whole architecture in miniature: sessions never float free of a directory, and directories never float free of a machine. The runtime is split into processes. The package.json declares three binaries: pi-web (the CLI), pi-web-server, and pi-web-sessiond. The development scripts run sessiond, the web server and the Vite client as separate watchers, and there is a dedicated dev:sessiond script, so the session daemon is a distinct long-lived process rather than a thread inside the HTTP server. That matches the README's note that server-backed plugin changes require a session-daemon restart. Remote machines extend the same model. One browser-facing pi-web instance can register other pi-web runtimes and proxy projects, files, git state, sessions, terminals, activity and Pi package management from them. The README is precise about which settings follow the selected machine and which stay local: Pi packages, plugin enablement, session daemon toggles, external file access and upload defaults target the selected machine, while host, port, allowed hosts, registered machines and tokens stay with the gateway. That split is worth reading twice before you change anything in Settings, because the same panel can be editing two different machines depending on which one is selected. ## Installing pi-web and starting a first session The README lists three requirements before you start: Node.js 22.19.0 or newer, npm, and Pi Coding Agent >=0.84.0 configured for your user, plus git and whatever development tools your agents need. The quick start installs pi-web globally and registers it as per-user services. ```bash npm install -g @jmfederico/pi-web --allow-scripts=node-pty pi-web install pi-web doctor ``` The scoped flag matters. The README explains that on npm 12 it lets node-pty prepare its required native module without enabling install scripts for other dependencies. If you drop it, the terminal component may not build. After install, pi-web doctor is the check to run before anything else; the README does not describe what it reports, only that it exists and appears again in the command list. Once the services are up, the README says to open this address in a browser: ```text http://127.0.0.1:8504 ``` From there the README's typical flow is: add a project, choose a workspace or git worktree, start a session, let the agent work, and come back later from any browser. Day to day, the CLI is the operational surface. ```bash pi-web status pi-web logs pi-web restart pi-web doctor pi-web version pi-web uninstall ``` pi-web logs is where you look when a session daemon restart does not take effect. The README points to the installation guide for one-line install, Pi package install, WSL and manual usage, and remote access, so the global npm path above is one option rather than the only one. ## Access control is your job, not pi-web's The security model section is blunt. pi-web "assumes trusted users, trusted repositories, and trusted server paths" and states that it is "not a sandbox, permission system, or multi-tenant platform." The README then warns against exposing it directly to the public internet without a trusted network, firewall, VPN, SSH tunnel, or authenticated reverse proxy. This is the constraint that should drive your deployment more than any feature. A session runs a coding agent with access to a real workspace, and the workspace is a real folder on a real machine. Anyone who reaches the UI is, in effect, someone who can drive that agent. There is no documented role model, no per-project ACL, and no mention of audit logging. The README's remote-first guidance points at a private network, an SSH tunnel, a trusted reverse proxy, or a federated machine setup, and it is worth treating that list as the supported deployment shapes rather than suggestions. Two smaller consequences follow. First, the allowed-hosts setting is a gateway concern, so hardening it on a remote machine will not help; the README places it with host, port, registered machines and tokens as local to the gateway. Second, because external file access is a per-machine setting, a fleet where one machine is more locked down than another will behave differently depending on which machine is selected in Settings. ## Where pi-web is the wrong tool If you want a hosted, multi-user agent platform, pi-web is the wrong shape. The README says so directly: not multi-tenant. Sharing one instance across a team means sharing the machine's paths and credentials. If you do not already run Pi Coding Agent, pi-web adds a dependency rather than removing one. The README requires Pi Coding Agent >=0.84.0 configured for your user, and pi-web is a UI and runtime layer over it, not a replacement. Nothing in the README suggests pi-web works with other agent backends. If your agent work is short and interactive, the persistent-session design buys you less. The value is in runs that outlive a browser tab. For a two-minute edit you pay the cost of a global install, a session daemon, and a service to keep running. Finally, the repository has a plugin system with two public contracts, plugin-api and server-plugin-api, exported from the package and typed via plugin-api.d.ts and server-plugin-api.d.ts. That is a real extension surface, but the README separates Pi packages from pi-web plugins and notes that installing a package and enabling it are different operations. If your need is a small UI tweak, check whether a plugin is the right layer before writing one. ## How pi-web differs from running Pi Coding Agent in a terminal The obvious alternative is a terminal multiplexer such as tmux or screen on the same machine, running the Pi Coding Agent CLI directly. The difference is not persistence, since both keep a process alive across disconnects. It is the supervision layer. tmux gives you a text buffer per window; pi-web gives you a browser UI that groups sessions by machine, project and workspace, and that can proxy those same objects from other registered pi-web runtimes. It also exposes files, terminals, git state and Pi package management in the same surface, which tmux does not attempt. The cost of that layer is a running service and a listening port. tmux needs neither. If your workflow is one agent in one checkout on one machine, tmux is smaller and has no security model to reason about beyond SSH. pi-web starts to pay off when the count grows: several sessions in parallel, several machines, and a device you did not install anything on. The README's fleet section is explicit that one browser-facing instance can proxy from trusted remote machines, which is a capability a multiplexer does not have. ## Maintenance cost, licence and what to check before upgrading The last push to the default branch was on 2026-08-24, and the most recent release, v1.202608.2, carries the same timestamp. The repository is not archived. Version numbers follow a date-based scheme, and package.json shows 1.202609.0 while the newest published release is v1.202608.2, so the working tree is ahead of the last release. There is a .changeset directory and a CHANGELOG.md at the top level, which means releases are cut through Changesets rather than by hand. The operational cost sits in the session daemon. The README states that server-backed plugin changes require a session-daemon restart, and the CLI provides pi-web restart for that. Plugin state is stored as desired state per machine, so an upgrade can leave a machine's plugins out of sync with what is enabled until the daemon restarts. The README points to the plugin guide for lifecycle and recovery details rather than documenting them inline; the README does not document rollback, so treat a version pin as your own responsibility. The licence is MIT, copyright 2026 Federico Jaramillo Martinez, and the package ships a LICENSE file. MIT is permissive and carries no copyleft obligation on your own code. That is the extent of what can be said here; questions about your organisation's policy are for your legal team, not this article. One practical note: the global install uses --allow-scripts=node-pty, which permits a native module build step for that one dependency. If your environment forbids install scripts entirely, that flag will not help you, and the README's installation guide is the place to look for alternatives. ## Conclusion Adopt pi-web if you already run Pi Coding Agent and want sessions that survive a closed laptop lid, and if the machine holding your repositories is one you trust. Skip it if you need multi-tenant isolation, per-user permissions, or a public-facing endpoint without a proxy in front. Before installing, confirm Node.js 22.19.0 or newer, Pi Coding Agent >=0.84.0 configured for your user, and git plus the development tools your agents call, since the README lists all three as requirements. ## FAQ ### What is pi-web? It is a web UI for Pi Coding Agent that keeps agent sessions running in real workspaces on your machine or server, so sessions survive browser disconnects. The README describes the browser as the control surface while the work stays where it can keep running. ### How do I access the pi-web interface after installing it? The README's quick start says to open http://127.0.0.1:8504 after running the install commands. For access from another device, the README points to a private network, SSH tunnel, trusted reverse proxy, or a federated pi-web machine setup. ### How do I install pi-web? The README installs it globally with npm install -g @jmfederico/pi-web --allow-scripts=node-pty, then runs pi-web install and pi-web doctor. Requirements are Node.js 22.19.0 or newer, npm, and Pi Coding Agent >=0.84.0 configured for your user. ### Does pi-web have an API? The package exports two typed contracts, ./plugin-api and ./server-plugin-api, and the repository carries plugin-api.d.ts and server-plugin-api.d.ts. The README points to the plugin guide and API page on pi-web.dev for the contracts themselves. ## Sources - [Official documentation](https://pi-web.dev/) - [Official README](https://github.com/jmfederico/pi-web#readme) - [Project repository](https://github.com/jmfederico/pi-web) - [Release notes](https://github.com/jmfederico/pi-web/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/jmfederico-pi-web