Fix the things that usually go wrong first.

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 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, so an interactive terminal can work while services fail.

$ 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 checks whether the service shell and native service environment can find Node 22+, npm, Pi, and the Pi Web binaries. It also prints installed and running PI WEB versions when available, reports optional ripgrep availability for faster all-file @-mention suggestions, uses a bounded filesystem fallback when ripgrep is unavailable, and reports user service lingering when relevant for server-style installs.

If something works in your terminal but fails in doctor, treat that as a login-shell PATH mismatch and move the setup earlier in your shell startup chain.

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 from bash -lc, zsh -lc, or your detected shell.
• Run pi-web doctor again after changing shell files.

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:

$ 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.

Read the fleet guide →

Should I run PI WEB on my laptop or a server?

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.

Read the plugin guide →

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.

$ pi-web status
$ pi-web logs

Where are logs?

Use the service log command:

$ pi-web logs