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.