Installation guide

Get PI WEB running where your agents work.

The recommended setup runs PI WEB as per-user services. PI WEB chooses the native user-service backend for your operating system.

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: a supported per-user service manager.
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: run PI WEB as user services

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

User service install 
$ npm install -g @jmfederico/pi-web
$ pi-web install
$ pi-web doctor

Then open http://127.0.0.1:8504.

On Linux servers, also consider sudo loginctl enable-linger "$USER" so user services survive logout/reboot.

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.

When installed this way, /pi-web install can use PI WEB's package-local service entrypoints, so pi-web-server and pi-web-sessiond do not need to be on your shell PATH.

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

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

WSL / manual run

On WSL without systemd, containers without a user service manager, or other unsupported environments, 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 installer can work. Without systemd, use the manual run approach above.

From a PI WEB checkout, pi-web install --dev installs the split development services on supported user-service platforms. pi-web uninstall removes both production and development service files; no uninstall flags are needed.

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 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. If you use a VPN or private network, bind PI WEB to the server's VPN/private IP, such as a Tailscale/WireGuard/LAN address, and make sure that network policy limits access. Avoid 0.0.0.0 unless a firewall, VPN, or authenticated reverse proxy strictly controls the port.

Manage services

pi-web version compares the installed package version with the versions reported by the running Web/UI and session daemon services.

Useful commands 
$ pi-web status
$ pi-web logs
$ pi-web restart
$ pi-web doctor
$ pi-web version

# From a checkout, install the split development services:
$ pi-web install --dev

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.

Default config 
{
  "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.
  • PI_CODING_AGENT_SESSION_DIR: Pi session storage directory. PI WEB follows Pi's priority for sessions: this environment variable, then sessionDir in Pi settings for the selected workspace, then Pi's default session directory.
  • PI_CODING_AGENT_DIR: Pi agent config directory for auth, settings, resources, and default session storage.

Uninstall

pi-web uninstall stops, disables, and removes PI WEB's production and development service files. It does not remove the npm package, config file, or data directory.

Uninstall services and package 
$ pi-web uninstall
$ npm uninstall -g @jmfederico/pi-web

Optional cleanup, if you also want to delete PI WEB config and state:

Delete config and data 
$ 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.