FAQ & troubleshooting

# Fix the things that usually go wrong first.

Most Pi Web install issues are environment issues: systemd availability, PATH setup, Node version managers, or remote access expectations.

## Is this Linux only?

No. Pi Web can run anywhere its runtime dependencies work, including macOS and Windows through WSL. The automatic `pi-web install` command is the Linux-specific part because it writes and manages `systemctl --user` services.

- Linux with systemd: use `npm install -g @jmfederico/pi-web` and `pi-web install`.
- macOS: install the package, then run `pi-web-sessiond` and `pi-web-server` manually.
- Windows: use WSL. If your WSL distro has systemd enabled, the installer may work; otherwise use the manual run path.

Native Windows outside WSL is not the recommended path today.

## Tools are failing, node is not found, or Pi cannot find commands

The shell environment needs to be set up so login shells have the required PATH entries for Pi Web, Pi, and any tools your agents need. Pi Web services run commands through a non-interactive login shell, so an interactive terminal can work while services fail.

Run diagnostics

    $ pi-web doctor

- bash: put PATH setup in `~/.bash_profile` or `~/.profile`. If `~/.bash_profile` exists, source `~/.profile` from it if needed.
- zsh: put PATH setup in `~/.zprofile`, not only `~/.zshrc`.
- fish: prefer universal PATH setup, for example `fish_add_path -U ...`.

Avoid relying only on prompt hooks, shell integrations that rewrite PATH while rendering a prompt, or interactive-only shell files for tools needed by services. Version-manager shims are usually the most reliable option for service environments.

## What does `pi-web doctor` check?

It checks whether the service shell and systemd user environment can find Node 22+, npm, Pi, and the Pi Web binaries. It also reports whether user service lingering is enabled for server-style installs.

If something works in your terminal but fails in doctor, treat that as a login-shell PATH mismatch and move the setup earlier in your shell startup chain.

## I installed Node with nvm, fnm, asdf, or another version manager

Version managers often initialize in interactive shells only. Some tools, including `fnm` and `mise` when used through shell activation instead of shims, depend on shell hooks or prompt-time PATH updates that are unreliable in non-interactive login shells.

- Prefer version-manager shims when available; for `mise`, use shims or enable its shim setup rather than relying only on shell activation.
- Move any required version-manager initialization to your login shell file.
- Make sure `node --version` is at least `v22` from `bash -lc`, `zsh -lc`, or your detected shell.
- Run `pi-web doctor` again after changing shell files.

## `systemctl --user` is not available

The automatic installer needs Linux user systemd. On macOS, WSL without systemd, containers without a user systemd manager, or minimal Linux environments, run the two processes manually:

Manual run

    $ pi-web-sessiond
    # in another terminal
    $ PI_WEB_PORT=8504 pi-web-server

## I cannot open the web UI

- Check `pi-web status`.
- Check logs with `pi-web logs`.
- Make sure port `8504` is not already in use.
- On a remote server, use an SSH tunnel: `ssh -L 8504:127.0.0.1:8504 user@server`.

## Can I expose Pi Web to the public internet?

Do not expose it directly to the public internet. Pi Web assumes trusted users and trusted server paths. For remote access, bind only to an interface that is already private and controlled: for example the server's VPN IP, a private LAN IP, or localhost behind an SSH tunnel.

When you connect over a VPN, `127.0.0.1` usually means your own device, not the server, so the server must listen on its VPN/private-network address or sit behind a tunnel/proxy.

Avoid `0.0.0.0` unless a firewall, VPN, or reverse proxy strictly limits who can reach the port.

## Sessions stop unexpectedly

Active agent runtimes are owned by the session daemon. Browser disconnects and web/API restarts should not stop them. If they stop anyway, check whether the session daemon service restarted or crashed.

Session daemon logs

    $ systemctl --user status pi-web-sessiond.service
    $ journalctl --user -u pi-web-sessiond.service -f

## Where are logs?

For the Linux systemd install, use:

Logs

    $ pi-web logs
    $ journalctl --user -u pi-web-sessiond.service -u pi-web.service -f