FAQ & troubleshooting

# Fix the things that usually go wrong first.

Most PI WEB install issues are environment issues: native service manager availability, PATH setup, Node version managers, or remote access expectations.

## What platforms are supported?

PI WEB can run anywhere its runtime dependencies work. The automatic `pi-web install` command uses a supported per-user service manager when one is available.

- User-service install: use `npm install -g @jmfederico/pi-web --allow-scripts=node-pty` and `pi-web install`.
- WSL: if your distro has systemd enabled, the installer may work; otherwise use the manual run path.
- Native Windows: outside WSL is not the recommended path today.

## Is PI WEB a Pi web UI?

Yes. PI WEB is a web UI for Pi Coding Agent that runs and supervises persistent sessions from a browser. Unlike simple session viewers, PI WEB is built around real server-side workspaces, long-running session daemons, git worktrees, remote machines, terminals, files, and multi-device supervision.

## 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 owned by systemd or launchd, so an interactive terminal—or even a caller-invoked login shell—can work while the native service fails.

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 keeps two kinds of checks separate. General login-shell readiness covers Node 22.19.0 or newer, npm, Pi, and optional ripgrep. Native-service diagnostics validate only the exact prerequisites of the selected service plan in the real systemd user-manager or launchd `gui/<uid>` context. Development installs follow their installed checkout plan; production checks are clearly labelled prospective when the installed executable strategy cannot be reconstructed safely.

Missing plan requirements fail doctor and include login-file guidance. Manager, timeout, malformed-output, and cleanup failures are reported as probe infrastructure problems rather than being mislabeled as PATH drift. On unsupported/manual-only platforms, native-service drift checks are skipped. Doctor also checks that the `node-pty` native module can load, prints installed and running PI WEB versions, and reports systemd lingering when relevant.

## 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.19.0` from `bash -lc`, `zsh -lc`, or your detected shell.
- Run `pi-web doctor` again after changing shell files.

## `pi-web-sessiond` cannot load `pty.node`

npm 12 blocks dependency installation scripts unless they are explicitly approved. If PI WEB was installed without approving `node-pty`, its required native module can be missing even though npm reported a successful installation.

Reinstall PI WEB with approval limited to `node-pty`:

Allow the node-pty installation scripts

    $ npm install -g @jmfederico/pi-web --allow-scripts=node-pty

Then run `pi-web install` again, or restart `pi-web-sessiond` if you run PI WEB manually. The flag does not enable installation scripts for other dependencies.

## User service manager is unavailable

The automatic installer needs a supported per-user service manager. On WSL without systemd, containers without a user service manager, or minimal 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.

## How do I connect another PI WEB machine?

Install and run PI WEB on the target machine, make its PI WEB URL reachable from the gateway through a trusted path, then open the gateway and choose Actions → Add Machine. The browser keeps talking to the gateway while projects, sessions, files, and terminals run on the selected remote runtime.

- Use NetBird, Tailscale, WireGuard, private LAN, SSH tunnel, or an authenticated reverse proxy.
- Remote Pi auth, OAuth state, sessions, terminals, repositories, and plugins stay on the target machine.
- API-key provider configuration can be proxied, but OAuth login should be completed by opening the remote PI WEB directly.
- Remote plugins are trusted browser code and only appear while that machine is selected.
- If the remote reports offline, check that the gateway server can reach the remote URL and try Actions → Refresh Selected Machine.

Read the fleet guide →

## Should I run PI WEB on my laptop or a server?

You can run it locally, but PI WEB is most useful on a machine that stays on. A remote dev box, home server, cloud VM, or workstation gives agents a stable place to keep working while your laptop becomes just a client.

Local development can become a blocker when one device owns the tools, secrets, shells, editor, and agent runtime. Remote AI-driven development unlocks persistent work: agents keep running, sessions remain available, and you connect from whatever screen you have.

## Can I use local plugins with production PI WEB?

Yes. Put trusted browser-side plugins in `~/.pi-web/plugins/<plugin-id>/`, or symlink a development folder there. Reload the browser tab after edits. If `PI_WEB_DATA_DIR` is set, use `$PI_WEB_DATA_DIR/plugins` instead.

Read the plugin guide →

## A worktree I created or deleted outside PI WEB is missing or still listed

PI WEB does not register worktrees. It lists the git worktrees of the selected project on demand, so worktrees you create or delete with `git worktree`, a terminal, or another tool are picked up without any adopt or import step. This works the same way on remote machines.

The workspace list is re-read when the PI WEB tab regains focus or becomes visible again, not continuously. If a worktree appeared while you were already looking at PI WEB, switch to another window or tab and back, and the list updates. Your selected workspace, session, and scroll position are kept.

Worktrees whose checkout directory no longer exists are hidden, so a directory you removed with `rm -rf` instead of `git worktree remove` stops appearing as a selectable workspace. Git still tracks it until you run `git worktree prune`.

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

    $ pi-web status
    $ pi-web logs

## Where are logs?

Use the service log command:

Logs

    $ pi-web logs