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 or interactive-only shell files for tools needed by services.
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. Pi Web needs Node and npm to be available to
login shells and systemd user services.
Move the 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. Pi Web assumes trusted users and trusted server paths. Keep the default
localhost bind and use SSH tunneling, a VPN, or a reverse proxy with authentication and network policy.
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.