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 NetBird/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.

Federated machines

To use one PI WEB instance as a gateway to others, install and run PI WEB on each target machine first. Make each target reachable from the gateway through a trusted path, then open the gateway and use Actions → Add Machine with the target PI WEB base URL.

The remote URL can be reachable through NetBird, Tailscale, WireGuard, LAN, an SSH tunnel, or an authenticated reverse proxy. The browser keeps using the gateway origin while projects, sessions, files, and terminals run on the selected remote runtime.

Read the fleet guide

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.