Most PI WEB install issues are environment issues: native service manager availability, PATH setup, Node
version managers, or remote access expectations.
What platforms are supported?
PI WEB can run anywhere its runtime dependencies work. The automatic pi-web install command uses
a supported per-user service manager when one is available.
User-service install: use npm install -g @jmfederico/pi-web --allow-scripts=node-pty and pi-web install.
WSL: if your distro has systemd enabled, the installer may work; otherwise use the manual run path.
Native Windows: outside WSL is not the recommended path today.
Is PI WEB a Pi web UI?
Yes. PI WEB is a web UI for Pi Coding Agent that runs and supervises persistent sessions from a browser.
Unlike simple session viewers, PI WEB is built around real server-side workspaces, long-running session
daemons, git worktrees, remote machines, terminals, files, and multi-device supervision.
Tools are failing, node is not found, or Pi cannot find commands
The shell environment needs to be set up so login shells have the required PATH entries for PI WEB, Pi,
and any tools your agents need. PI WEB services run commands through a non-interactive login shell owned
by systemd or launchd, so an interactive terminal—or even a caller-invoked login shell—can work while the
native service fails.
Run diagnostics
$ pi-web doctor
bash: put PATH setup in ~/.bash_profile or ~/.profile. If ~/.bash_profile exists, source ~/.profile from it if needed.
zsh: put PATH setup in ~/.zprofile, not only ~/.zshrc.
fish: prefer universal PATH setup, for example fish_add_path -U ....
Avoid relying only on prompt hooks, shell integrations that rewrite PATH while rendering a prompt, or
interactive-only shell files for tools needed by services. Version-manager shims are usually the most
reliable option for service environments.
What does pi-web doctor check?
It keeps two kinds of checks separate. General login-shell readiness covers Node 22.19.0 or newer, npm, Pi, and optional
ripgrep. Native-service diagnostics validate only the exact prerequisites of the selected service plan in
the real systemd user-manager or launchd gui/<uid> context. Development installs follow their
installed checkout plan; production checks are clearly labelled prospective when the installed executable
strategy cannot be reconstructed safely.
Missing plan requirements fail doctor and include login-file guidance. Manager, timeout, malformed-output,
and cleanup failures are reported as probe infrastructure problems rather than being mislabeled as PATH
drift. On unsupported/manual-only platforms, native-service drift checks are skipped. Doctor also checks
that the node-pty native module can load, prints installed and running PI WEB versions, and reports
systemd lingering when relevant.
I installed Node with nvm, fnm, asdf, or another version manager
Version managers often initialize in interactive shells only. Some tools, including fnm and
mise when used through shell activation instead of shims, depend on shell hooks or prompt-time
PATH updates that are unreliable in non-interactive login shells.
Prefer version-manager shims when available; for mise, use shims or enable its shim setup rather than relying only on shell activation.
Move any required version-manager initialization to your login shell file.
Make sure node --version is at least v22.19.0 from bash -lc, zsh -lc, or your detected shell.
Run pi-web doctor again after changing shell files.
pi-web-sessiond cannot load pty.node
npm 12 blocks dependency installation scripts unless they are explicitly approved. If PI WEB was installed
without approving node-pty, its required native module can be missing even though npm reported a
successful installation.
Reinstall PI WEB with approval limited to node-pty:
Then run pi-web install again, or restart pi-web-sessiond if you run PI WEB manually.
The flag does not enable installation scripts for other dependencies.
User service manager is unavailable
The automatic installer needs a supported per-user service manager. On WSL without systemd, containers
without a user service manager, or minimal environments, run the two processes manually:
Manual run
$ pi-web-sessiond
# in another terminal$ PI_WEB_PORT=8504 pi-web-server
I cannot open the web UI
Check pi-web status.
Check logs with pi-web logs.
Make sure port 8504 is not already in use.
On a remote server, use an SSH tunnel: ssh -L 8504:127.0.0.1:8504 user@server.
Can I expose PI WEB to the public internet?
Do not expose it directly to the public internet. PI WEB assumes trusted users and trusted server paths.
For remote access, bind only to an interface that is already private and controlled: for example the
server's VPN IP, a private LAN IP, or localhost behind an SSH tunnel.
When you connect over a VPN, 127.0.0.1 usually means your own device, not the server, so the
server must listen on its VPN/private-network address or sit behind a tunnel/proxy.
Avoid 0.0.0.0 unless a firewall, VPN, or reverse proxy strictly limits who can reach the port.
How do I connect another PI WEB machine?
Install and run PI WEB on the target machine, make its PI WEB URL reachable from the gateway through a
trusted path, then open the gateway and choose Actions → Add Machine. The browser keeps
talking to the gateway while projects, sessions, files, and terminals run on the selected remote runtime.
Use NetBird, Tailscale, WireGuard, private LAN, SSH tunnel, or an authenticated reverse proxy.
Remote Pi auth, OAuth state, sessions, terminals, repositories, and plugins stay on the target machine.
API-key provider configuration can be proxied, but OAuth login should be completed by opening the remote PI WEB directly.
Remote plugins are trusted browser code and only appear while that machine is selected.
If the remote reports offline, check that the gateway server can reach the remote URL and try Actions → Refresh Selected Machine.
You can run it locally, but PI WEB is most useful on a machine that stays on. A remote dev box, home
server, cloud VM, or workstation gives agents a stable place to keep working while your laptop becomes
just a client.
Local development can become a blocker when one device owns the tools, secrets, shells, editor, and
agent runtime. Remote AI-driven development unlocks persistent work: agents keep running, sessions remain
available, and you connect from whatever screen you have.
Can I use local plugins with production PI WEB?
Yes. Put trusted browser-side plugins in ~/.pi-web/plugins/<plugin-id>/, or symlink a
development folder there. Reload the browser tab after edits. If PI_WEB_DATA_DIR is set, use
$PI_WEB_DATA_DIR/plugins instead.
A worktree I created or deleted outside PI WEB is missing or still listed
PI WEB does not register worktrees. It lists the git worktrees of the selected project on demand, so
worktrees you create or delete with git worktree, a terminal, or another tool are picked up
without any adopt or import step. This works the same way on remote machines.
The workspace list is re-read when the PI WEB tab regains focus or becomes visible again, not
continuously. If a worktree appeared while you were already looking at PI WEB, switch to another window
or tab and back, and the list updates. Your selected workspace, session, and scroll position are kept.
Worktrees whose checkout directory no longer exists are hidden, so a directory you removed with
rm -rf instead of git worktree remove stops appearing as a selectable
workspace. Git still tracks it until you run git worktree prune.
Sessions stop unexpectedly
Active agent runtimes are owned by the session daemon. Browser disconnects and web/API restarts should
not stop them. If they stop anyway, check whether the session daemon service restarted or crashed.