Archived
261 lines
14 KiB
HTML
261 lines
14 KiB
HTML
<!doctype html>
|
|
<html lang="en">
|
|
<head>
|
|
<meta charset="utf-8" />
|
|
<meta name="viewport" content="width=device-width, initial-scale=1" />
|
|
<title>PI WEB FAQ</title>
|
|
<meta name="description" content="Answers for common PI WEB install and runtime issues." />
|
|
<meta property="og:title" content="PI WEB FAQ" />
|
|
<meta property="og:image" content="assets/pi-web-banner.png" />
|
|
<link rel="icon" type="image/svg+xml" href="assets/favicon.svg" />
|
|
<script>
|
|
(() => {
|
|
const theme = window.localStorage.getItem("pi-web-theme");
|
|
if (theme === "light" || theme === "dark") document.documentElement.dataset.theme = theme;
|
|
})();
|
|
</script>
|
|
<link rel="preconnect" href="https://fonts.googleapis.com" />
|
|
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
|
|
<link
|
|
href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500;600;700&family=IBM+Plex+Sans:wght@400;500;600;700;800&display=swap"
|
|
rel="stylesheet"
|
|
/>
|
|
<link rel="stylesheet" href="styles.css" />
|
|
</head>
|
|
<body>
|
|
<header class="site-header">
|
|
<nav class="container nav" aria-label="Main navigation">
|
|
<a class="brand" href="./" aria-label="PI WEB home">PI WEB</a>
|
|
<div class="nav-links">
|
|
<a href="remote-first.html">Remote-first</a>
|
|
<a href="install.html">Install</a>
|
|
<a href="plugins.html">Plugins</a>
|
|
<a href="faq.html" aria-current="page">FAQ</a>
|
|
<a class="github-link" href="https://github.com/jmfederico/pi-web" aria-label="PI WEB on GitHub">
|
|
<svg class="github-icon" viewBox="0 0 16 16" aria-hidden="true">
|
|
<path
|
|
fill="currentColor"
|
|
d="M8 0C3.58 0 0 3.67 0 8.2c0 3.63 2.29 6.7 5.47 7.79.4.08.55-.18.55-.4 0-.2-.01-.85-.01-1.55-2.01.38-2.53-.5-2.69-.96-.09-.24-.48-.96-.82-1.16-.28-.16-.68-.56-.01-.57.63-.01 1.08.59 1.23.84.72 1.24 1.87.89 2.33.68.07-.53.28-.89.51-1.09-1.78-.21-3.64-.91-3.64-4.04 0-.89.31-1.62.82-2.2-.08-.2-.36-1.03.08-2.16 0 0 .67-.22 2.2.84A7.4 7.4 0 0 1 8 3.94c.68 0 1.36.09 2 .28 1.53-1.06 2.2-.84 2.2-.84.44 1.13.16 1.96.08 2.16.51.58.82 1.31.82 2.2 0 3.14-1.87 3.83-3.65 4.04.29.26.54.76.54 1.53 0 1.1-.01 1.99-.01 2.27 0 .22.15.49.55.4A8.12 8.12 0 0 0 16 8.2C16 3.67 12.42 0 8 0Z"
|
|
/>
|
|
</svg>
|
|
<span>GitHub</span>
|
|
</a>
|
|
<button class="theme-toggle" type="button" data-theme-toggle aria-label="Toggle light and dark theme">
|
|
<span data-theme-icon aria-hidden="true">◐</span>
|
|
<span data-theme-label>Theme</span>
|
|
</button>
|
|
</div>
|
|
</nav>
|
|
</header>
|
|
|
|
<main>
|
|
<section class="page-hero">
|
|
<div class="container">
|
|
<p class="eyebrow"><span class="pulse"></span> FAQ & troubleshooting</p>
|
|
<h1>Fix the things that usually go wrong first.</h1>
|
|
<p>
|
|
Most PI WEB install issues are environment issues: native service manager availability, PATH setup, Node
|
|
version managers, or remote access expectations.
|
|
</p>
|
|
</div>
|
|
</section>
|
|
|
|
<section class="section compact">
|
|
<div class="container doc-layout">
|
|
<aside class="toc" aria-label="FAQ contents">
|
|
<strong>Questions</strong>
|
|
<a href="#is-this-linux-only">What platforms are supported?</a>
|
|
<a href="#tools-are-not-found">Tools are failing / node not found</a>
|
|
<a href="#doctor-fails">What does doctor check?</a>
|
|
<a href="#nvm-fnm-asdf">nvm, fnm, or asdf issues</a>
|
|
<a href="#systemd-not-found">User service manager is unavailable</a>
|
|
<a href="#cannot-open">I cannot open the web UI</a>
|
|
<a href="#public-internet">Can I expose this publicly?</a>
|
|
<a href="#laptop-or-server">Laptop or server?</a>
|
|
<a href="#plugins">Can I use local plugins?</a>
|
|
<a href="#sessions-stop">Sessions stop unexpectedly</a>
|
|
<a href="#logs">Where are logs?</a>
|
|
</aside>
|
|
|
|
<div class="faq-list">
|
|
<article id="is-this-linux-only" class="faq-item">
|
|
<h2>What platforms are supported?</h2>
|
|
<p>
|
|
PI WEB can run anywhere its runtime dependencies work. The automatic <code>pi-web install</code> command uses
|
|
a supported per-user service manager when one is available.
|
|
</p>
|
|
<ul>
|
|
<li><strong>User-service install:</strong> use <code>npm install -g @jmfederico/pi-web</code> and <code>pi-web install</code>.</li>
|
|
<li><strong>WSL:</strong> if your distro has systemd enabled, the installer may work; otherwise use the manual run path.</li>
|
|
<li><strong>Native Windows:</strong> outside WSL is not the recommended path today.</li>
|
|
</ul>
|
|
</article>
|
|
|
|
<article id="tools-are-not-found" class="faq-item">
|
|
<h2>Tools are failing, node is not found, or Pi cannot find commands</h2>
|
|
<p>
|
|
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.
|
|
</p>
|
|
<div class="code-card">
|
|
<div class="copy-row">
|
|
<strong>Run diagnostics</strong>
|
|
<button class="copy-button" data-copy="#doctor-command">Copy</button>
|
|
</div>
|
|
<pre id="doctor-command"><code><span class="prompt">$</span> pi-web doctor</code></pre>
|
|
</div>
|
|
<ul>
|
|
<li><strong>bash:</strong> put PATH setup in <code>~/.bash_profile</code> or <code>~/.profile</code>. If <code>~/.bash_profile</code> exists, source <code>~/.profile</code> from it if needed.</li>
|
|
<li><strong>zsh:</strong> put PATH setup in <code>~/.zprofile</code>, not only <code>~/.zshrc</code>.</li>
|
|
<li><strong>fish:</strong> prefer universal PATH setup, for example <code>fish_add_path -U ...</code>.</li>
|
|
</ul>
|
|
<p>
|
|
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.
|
|
</p>
|
|
</article>
|
|
|
|
<article id="doctor-fails" class="faq-item">
|
|
<h2>What does <code>pi-web doctor</code> check?</h2>
|
|
<p>
|
|
It checks whether the service shell and native service environment can find Node 22+, npm, Pi, and the Pi
|
|
Web binaries. It also reports user service lingering when relevant for server-style installs.
|
|
</p>
|
|
<p>
|
|
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.
|
|
</p>
|
|
</article>
|
|
|
|
<article id="nvm-fnm-asdf" class="faq-item">
|
|
<h2>I installed Node with nvm, fnm, asdf, or another version manager</h2>
|
|
<p>
|
|
Version managers often initialize in interactive shells only. Some tools, including <code>fnm</code> and
|
|
<code>mise</code> 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.
|
|
</p>
|
|
<ul>
|
|
<li>Prefer version-manager shims when available; for <code>mise</code>, use shims or enable its shim setup rather than relying only on shell activation.</li>
|
|
<li>Move any required version-manager initialization to your login shell file.</li>
|
|
<li>Make sure <code>node --version</code> is at least <code>v22</code> from <code>bash -lc</code>, <code>zsh -lc</code>, or your detected shell.</li>
|
|
<li>Run <code>pi-web doctor</code> again after changing shell files.</li>
|
|
</ul>
|
|
</article>
|
|
|
|
<article id="systemd-not-found" class="faq-item">
|
|
<h2>User service manager is unavailable</h2>
|
|
<p>
|
|
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:
|
|
</p>
|
|
<div class="code-card">
|
|
<div class="copy-row">
|
|
<strong>Manual run</strong>
|
|
<button class="copy-button" data-copy="#manual-faq">Copy</button>
|
|
</div>
|
|
<pre id="manual-faq"><code><span class="prompt">$</span> pi-web-sessiond
|
|
<span class="comment"># in another terminal</span>
|
|
<span class="prompt">$</span> PI_WEB_PORT=8504 pi-web-server</code></pre>
|
|
</div>
|
|
</article>
|
|
|
|
<article id="cannot-open" class="faq-item">
|
|
<h2>I cannot open the web UI</h2>
|
|
<ul>
|
|
<li>Check <code>pi-web status</code>.</li>
|
|
<li>Check logs with <code>pi-web logs</code>.</li>
|
|
<li>Make sure port <code>8504</code> is not already in use.</li>
|
|
<li>On a remote server, use an SSH tunnel: <code>ssh -L 8504:127.0.0.1:8504 user@server</code>.</li>
|
|
</ul>
|
|
</article>
|
|
|
|
<article id="public-internet" class="faq-item">
|
|
<h2>Can I expose PI WEB to the public internet?</h2>
|
|
<p>
|
|
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.
|
|
</p>
|
|
<p>
|
|
When you connect over a VPN, <code>127.0.0.1</code> 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.
|
|
</p>
|
|
<p>
|
|
Avoid <code>0.0.0.0</code> unless a firewall, VPN, or reverse proxy strictly limits who can reach the port.
|
|
</p>
|
|
</article>
|
|
|
|
<article id="laptop-or-server" class="faq-item">
|
|
<h2>Should I run PI WEB on my laptop or a server?</h2>
|
|
<p>
|
|
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.
|
|
</p>
|
|
<p>
|
|
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.
|
|
</p>
|
|
</article>
|
|
|
|
<article id="plugins" class="faq-item">
|
|
<h2>Can I use local plugins with production PI WEB?</h2>
|
|
<p>
|
|
Yes. Put trusted browser-side plugins in <code>~/.pi-web/plugins/<plugin-id>/</code>, or symlink a
|
|
development folder there. Reload the browser tab after edits. If <code>PI_WEB_DATA_DIR</code> is set, use
|
|
<code>$PI_WEB_DATA_DIR/plugins</code> instead.
|
|
</p>
|
|
<p><a href="plugins.html">Read the plugin guide →</a></p>
|
|
</article>
|
|
|
|
<article id="sessions-stop" class="faq-item">
|
|
<h2>Sessions stop unexpectedly</h2>
|
|
<p>
|
|
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.
|
|
</p>
|
|
<div class="code-card">
|
|
<div class="copy-row">
|
|
<strong>Session daemon logs</strong>
|
|
<button class="copy-button" data-copy="#session-logs">Copy</button>
|
|
</div>
|
|
<pre id="session-logs"><code><span class="prompt">$</span> pi-web status
|
|
<span class="prompt">$</span> pi-web logs</code></pre>
|
|
</div>
|
|
</article>
|
|
|
|
<article id="logs" class="faq-item">
|
|
<h2>Where are logs?</h2>
|
|
<p>Use the service log command:</p>
|
|
<div class="code-card">
|
|
<div class="copy-row">
|
|
<strong>Logs</strong>
|
|
<button class="copy-button" data-copy="#logs-command">Copy</button>
|
|
</div>
|
|
<pre id="logs-command"><code><span class="prompt">$</span> pi-web logs</code></pre>
|
|
</div>
|
|
</article>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
</main>
|
|
|
|
<footer class="site-footer">
|
|
<div class="container footer-inner">
|
|
<span>PI WEB FAQ</span>
|
|
<div class="footer-links">
|
|
<a href="./">Home</a>
|
|
<a href="remote-first.html">Remote-first</a>
|
|
<a href="install.html">Install</a>
|
|
<a href="plugins.html">Plugins</a>
|
|
<a href="https://github.com/jmfederico/pi-web/issues">Issues</a>
|
|
</div>
|
|
</div>
|
|
</footer>
|
|
<script src="site.js"></script>
|
|
</body>
|
|
</html>
|