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.

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