Most Pi Web install issues are environment issues: systemd availability, PATH setup, Node version managers,
or remote access expectations.
Is this Linux only?
No. Pi Web can run anywhere its runtime dependencies work, including macOS and Windows through WSL. The
automatic pi-web install command is the Linux-specific part because it writes and manages
systemctl --user services.
Linux with systemd: use npm install -g @jmfederico/pi-web and pi-web install.
macOS: install the package, then run pi-web-sessiond and pi-web-server manually.
Windows: use WSL. If your WSL distro has systemd enabled, the installer may work; otherwise use the manual run path.
Native Windows outside WSL is not the recommended path today.
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.
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 checks whether the service shell and systemd user environment can find Node 22+, npm, Pi, and the Pi
Web binaries. It also reports whether user service lingering is enabled 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.
systemctl --user is not available
The automatic installer needs Linux user systemd. On macOS, WSL without systemd, containers without a
user systemd manager, or minimal Linux 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.
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.