Get Pi Web running where your agents work.

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.

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.

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

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

$ 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, the safest option is an SSH tunnel:

$ ssh -L 8504:127.0.0.1:8504 user@your-server
# Open http://127.0.0.1:8504 on your local machine

Manage services

$ 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 to ~/.config/pi-web/config.json, or to $XDG_CONFIG_HOME/pi-web/config.json when XDG_CONFIG_HOME is set. You can choose a different config file during install with pi-web install --config /path/to/config.json, or at runtime with PI_WEB_CONFIG=/path/to/config.json.

{
  "host": "127.0.0.1",
  "port": 8504,
  "allowedHosts": []
}

The web server defaults to 127.0.0.1:8504 and stores Pi Web state in ~/.pi-web.

• PI_WEB_CONFIG: path to a config JSON file. Defaults to ~/.config/pi-web/config.json.
• PI_WEB_PORT or PORT: web server port. Overrides the config file.
• PI_WEB_HOST: web server bind host. Overrides the config file. Use 127.0.0.1 for local/tunnel-only access, or a specific VPN/private-network IP for trusted remote access.
• PI_WEB_DATA_DIR: data directory, default ~/.pi-web.
• PI_WEB_SESSIOND_SOCKET: Unix socket path for daemon communication.

Uninstall

pi-web uninstall stops, disables, and removes the systemd user services. It does not remove the npm package, config file, or data directory.

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

Optional cleanup, if you also want to delete Pi Web config and state:

$ CONFIG_FILE="${PI_WEB_CONFIG:-${XDG_CONFIG_HOME:-$HOME/.config}/pi-web/config.json}"
$ DATA_DIR="${PI_WEB_DATA_DIR:-$HOME/.pi-web}"
$ rm -f "$CONFIG_FILE"
$ rmdir "$(dirname "$CONFIG_FILE")" 2>/dev/null || true
$ rm -rf "$DATA_DIR"

# If you configured a socket outside PI_WEB_DATA_DIR, remove it too:
$ [ -z "${PI_WEB_SESSIOND_SOCKET:-}" ] || rm -f "$PI_WEB_SESSIOND_SOCKET"

If you installed with pi-web install --config /custom/path.json, delete that custom file instead of the default config path.