Installation guide

Get Pi Web running where your agents work.

The best production-style setup is a Linux machine with user-level systemd services. macOS and Windows WSL are useful too: run the two Pi Web processes manually, or use the installer in WSL when systemd is enabled.

Requirements

  • Node.js 22 or newer and npm.
  • Pi Coding Agent installed/configured so the pi command works for your user.
  • A shell login environment that exposes Node, npm, Pi, git, and any tools your agents need.
  • For the automatic installer: Linux with systemctl --user.
Important PATH detail: Pi Web services run through your login shell with -lc. Setup that only lives in interactive shell files or prompt hooks may not be visible to services. Run pi-web doctor after installing.

Recommended: Linux systemd install

This creates two user services: one long-lived session daemon and one web/API service. It is the easiest way to keep sessions available after SSH disconnects or browser restarts.

Linux install 
$ npm install -g @jmfederico/pi-web
# Recommended on servers so user services survive logout/reboot:
$ sudo loginctl enable-linger "$USER"
$ pi-web install
$ pi-web doctor

Then open http://127.0.0.1:8504.

One-line install

If you prefer a curl pipe, use the repository installer:

One-liner 
$ curl -fsSL https://raw.githubusercontent.com/jmfederico/pi-web/main/install.sh | sh

Install through Pi

Pi Web is also published as a Pi package. This exposes a /pi-web command inside Pi.

Pi package path 
$ pi install npm:@jmfederico/pi-web

# Then inside Pi:
/pi-web install
/pi-web status
/pi-web logs
/pi-web doctor

macOS / WSL manual run

Pi Web is not Linux-only, but the pi-web install service setup is Linux/systemd-specific. On macOS or WSL without systemd, install the package and run the daemon and web server yourself.

Manual processes 
$ npm install -g @jmfederico/pi-web

# Terminal 1
$ pi-web-sessiond

# Terminal 2
$ PI_WEB_PORT=8504 pi-web-server

On modern WSL distributions with systemd enabled, the Linux installer can work. Without systemd, use the manual run approach above.

Remote access

Pi Web binds to 127.0.0.1:8504 by default. For a remote server, keep that safe default and use an SSH tunnel:

SSH tunnel 
$ ssh -L 8504:127.0.0.1:8504 user@your-server
# Open http://127.0.0.1:8504 on your local machine
Pi Web is designed for trusted users and trusted server paths. Do not expose it directly to the public internet without adding your own network controls, authentication, or reverse proxy policy.

Manage services

Useful commands 
$ pi-web status
$ pi-web logs
$ pi-web restart
$ pi-web doctor
$ systemctl --user status pi-web-sessiond.service pi-web.service
$ journalctl --user -u pi-web-sessiond.service -u pi-web.service -f

Configure

The installer writes a config file under your user config directory. The web server defaults to 127.0.0.1:8504 and stores Pi Web state in ~/.pi-web.

  • PI_WEB_PORT or PORT: web server port.
  • PI_WEB_HOST: web server bind host. Keep 127.0.0.1 unless you know why not.
  • PI_WEB_DATA_DIR: data directory, default ~/.pi-web.
  • PI_WEB_SESSIOND_SOCKET: Unix socket path for daemon communication.

Uninstall

Remove the user services, then remove the npm package if you installed it globally.

Uninstall 
$ pi-web uninstall
$ npm uninstall -g @jmfederico/pi-web