snowspeeder/pi-web
Archived
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: document machine federation

Browse Source
This commit is contained in:
Federico Jaramillo Martinez
2026-06-05 23:27:04 +02:00
parent 058fdeea1b
commit 271c9905f7
11 changed files with 348 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.changeset/document-machine-federation.md
+5
View File
@@ -0,0 +1,5 @@
---
"@jmfederico/pi-web": patch
---
Document machine federation across the website and add a Fleet guide for setup, trust model, remote plugins, and troubleshooting.
README.md
+1 -1
View File
@@ -104,7 +104,7 @@ PI WEB keeps its own state intentionally small:
## Machine federation
The Machines section lets one PI WEB instance act as a gateway to other PI WEB runtimes. Register a remote machine from **Actions → Add Machine** with the remote PI WEB base URL, for example a Tailscale, WireGuard, SSH tunnel, or trusted reverse-proxy URL. The browser continues talking to the local PI WEB origin; project, workspace, file, git, session, activity, and terminal HTTP/WebSocket traffic is proxied server-to-server.
The Machines section lets one PI WEB instance act as a gateway to other PI WEB runtimes. Register a remote machine from **Actions → Add Machine** with the remote PI WEB base URL, for example a URL reachable over NetBird, Tailscale, WireGuard, an SSH tunnel, or a trusted reverse proxy. The browser continues talking to the local PI WEB origin; project, workspace, file, git, session, activity, and terminal HTTP/WebSocket traffic is proxied server-to-server. See the [Fleet guide](https://pi-web.dev/machines.html) for setup, trust model, and troubleshooting details.
Remote model-provider credentials and OAuth state 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. Register remote machines only when you trust the endpoint and the network path: adding a machine gives this PI WEB server permission to contact that URL with the optional bearer token you configured.
docs/404.html
+2
View File
@@ -29,6 +29,7 @@
<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="/machines.html">Fleet</a>
<a href="/install.html">Install</a>
<a href="/plugins.html">Plugins</a>
<a href="/faq.html">FAQ</a>
@@ -75,6 +76,7 @@
<div class="container footer-inner">
<span>PI WEB · remote control for persistent Pi Coding Agent sessions.</span>
<div class="footer-links">
<a href="/machines.html">Fleet</a>
<a href="/install.html">Install</a>
<a href="/plugins.html">Plugins</a>
<a href="/faq.html">FAQ</a>
docs/faq.html
+20
View File
@@ -28,6 +28,7 @@
<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="machines.html">Fleet</a>
<a href="install.html">Install</a>
<a href="plugins.html">Plugins</a>
<a href="faq.html" aria-current="page">FAQ</a>
@@ -71,6 +72,7 @@
<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="#remote-machines">How do remote machines work?</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>
@@ -189,6 +191,23 @@
</p>
</article>
<article id="remote-machines" class="faq-item">
<h2>How do I connect another PI WEB machine?</h2>
<p>
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 <strong>Actions → Add Machine</strong>. The browser keeps
talking to the gateway while projects, sessions, files, and terminals run on the selected remote runtime.
</p>
<ul>
<li>Use NetBird, Tailscale, WireGuard, private LAN, SSH tunnel, or an authenticated reverse proxy.</li>
<li>Remote Pi auth, OAuth state, sessions, terminals, repositories, and plugins stay on the target machine.</li>
<li>API-key provider configuration can be proxied, but OAuth login should be completed by opening the remote PI WEB directly.</li>
<li>Remote plugins are trusted browser code and only appear while that machine is selected.</li>
<li>If the remote reports offline, check that the gateway server can reach the remote URL and try <strong>Actions → Refresh Selected Machine</strong>.</li>
</ul>
<p><a href="machines.html">Read the fleet guide →</a></p>
</article>
<article id="laptop-or-server" class="faq-item">
<h2>Should I run PI WEB on my laptop or a server?</h2>
<p>
@@ -251,6 +270,7 @@
<div class="footer-links">
<a href="./">Home</a>
<a href="remote-first.html">Remote-first</a>
<a href="machines.html">Fleet</a>
<a href="install.html">Install</a>
<a href="plugins.html">Plugins</a>
<a href="https://github.com/jmfederico/pi-web/issues">Issues</a>
docs/index.html
+2
View File
@@ -35,6 +35,7 @@
<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="machines.html">Fleet</a>
<a href="install.html">Install</a>
<a href="plugins.html">Plugins</a>
<a href="faq.html">FAQ</a>
@@ -298,6 +299,7 @@
<span>PI WEB · remote control for persistent Pi Coding Agent sessions.</span>
<div class="footer-links">
<a href="remote-first.html">Remote-first</a>
<a href="machines.html">Fleet</a>
<a href="install.html">Install</a>
<a href="plugins.html">Plugins</a>
<a href="faq.html">FAQ</a>
docs/install.html
+21 -1
View File
@@ -28,6 +28,7 @@
<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="machines.html">Fleet</a>
<a href="install.html" aria-current="page">Install</a>
<a href="plugins.html">Plugins</a>
<a href="faq.html">FAQ</a>
@@ -70,6 +71,7 @@
<a href="#pi-package">Install through Pi</a>
<a href="#manual-run">WSL / manual run</a>
<a href="#remote-access">Remote access</a>
<a href="#federated-machines">Federated machines</a>
<a href="#manage-services">Manage services</a>
<a href="#configure">Configure</a>
<a href="#uninstall">Uninstall</a>
@@ -189,11 +191,28 @@
<div class="callout danger">
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
NetBird/Tailscale/WireGuard/LAN address, and make sure that network policy limits access. Avoid
<code>0.0.0.0</code> unless a firewall, VPN, or authenticated reverse proxy strictly controls the port.
</div>
</section>
<section id="federated-machines">
<h2>Federated machines</h2>
<p>
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
<strong>Actions → Add Machine</strong> with the target PI WEB base URL.
</p>
<p>
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.
</p>
<div class="doc-actions">
<a class="button" href="machines.html">Read the fleet guide</a>
</div>
</section>
<section id="manage-services">
<h2>Manage services</h2>
<p><code>pi-web version</code> compares the installed package version with the versions reported by the running Web/UI and session daemon services.</p>
@@ -289,6 +308,7 @@
<div class="footer-links">
<a href="./">Home</a>
<a href="remote-first.html">Remote-first</a>
<a href="machines.html">Fleet</a>
<a href="plugins.html">Plugins</a>
<a href="faq.html">FAQ</a>
<a href="https://github.com/jmfederico/pi-web">GitHub</a>
docs/machines.html
+277
View File
@@ -0,0 +1,277 @@
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>PI WEB fleet</title>
<meta
name="description"
content="Connect trusted PI WEB runtimes through machine federation so one browser control plane can supervise local and remote projects, sessions, files, git state, terminals, and plugins."
/>
<meta property="og:title" content="PI WEB fleet" />
<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="machines.html" aria-current="page">Fleet</a>
<a href="install.html">Install</a>
<a href="plugins.html">Plugins</a>
<a href="faq.html">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> PI WEB fleet</p>
<h1>Connect trusted PI WEB runtimes when one machine is not enough.</h1>
<p>
Most PI WEB setups only need one runtime. When you do have more than one, machine federation lets the PI WEB
instance you opened act as a gateway to other trusted runtimes while each machine keeps its own repositories,
credentials, sessions, and plugins.
</p>
</div>
</section>
<section class="section compact">
<div class="container doc-layout">
<aside class="toc" aria-label="Machines page contents">
<strong>On this page</strong>
<a href="#what-it-is">What federation is</a>
<a href="#when-to-use">When to use it</a>
<a href="#prepare-machines">Prepare machines</a>
<a href="#add-machine">Add a machine</a>
<a href="#what-is-proxied">What is proxied</a>
<a href="#auth-credentials">Auth and credentials</a>
<a href="#plugins">Remote plugins</a>
<a href="#trust-model">Trust model</a>
<a href="#storage-troubleshooting">Storage and troubleshooting</a>
</aside>
<div class="doc-content">
<section id="what-it-is">
<h2>What machine federation is</h2>
<p>
A machine is a PI WEB runtime endpoint. The local machine is synthesized automatically. Remote machines
are opt-in PI WEB runtimes that you register with a base URL and, optionally, a bearer token.
</p>
<p>
After registration, the browser keeps talking to the current PI WEB origin. The gateway contacts the
selected remote PI WEB server and routes that machine's projects, workspaces, sessions, files, git state,
activity, and terminals to the browser UI.
</p>
<div class="code-card">
<div class="copy-row">
<strong>Federated shape</strong>
<button class="copy-button" data-copy="#federated-shape">Copy</button>
</div>
<pre id="federated-shape"><code>Browser
↓
PI WEB gateway you opened
↓ gateway proxy
Remote PI WEB runtime
↓
Remote projects, workspaces, sessions, terminals, plugins</code></pre>
</div>
</section>
<section id="when-to-use">
<h2>When to use federation</h2>
<p>
Federation is useful when you have more than one place where agents should work, but you want one stable
browser entrypoint.
</p>
<div class="cards">
<article class="card">
<div class="card-icon">▦</div>
<h3>Many dev boxes</h3>
<p>Register a workstation, home server, cloud VM, or client-specific host without moving repositories.</p>
</article>
<article class="card">
<div class="card-icon">⇄</div>
<h3>One gateway</h3>
<p>Open one trusted PI WEB URL and switch machines instead of juggling browser tabs and tunnels.</p>
</article>
<article class="card">
<div class="card-icon">⌁</div>
<h3>Local ownership</h3>
<p>Each target machine keeps its own Pi auth, sessions, worktrees, terminal state, and plugins.</p>
</article>
</div>
</section>
<section id="prepare-machines">
<h2>Prepare the target machines</h2>
<p>
Install and run PI WEB on every machine you want to register. The remote URL must be reachable from the
gateway server, not just from your browser.
</p>
<div class="code-card">
<div class="copy-row">
<strong>Install on each target</strong>
<button class="copy-button" data-copy="#target-install">Copy</button>
</div>
<pre id="target-install"><code><span class="prompt">$</span> npm install -g @jmfederico/pi-web
<span class="prompt">$</span> pi-web install
<span class="prompt">$</span> pi-web doctor</code></pre>
</div>
<p>
Prefer a private path such as NetBird, Tailscale, WireGuard, private LAN, SSH tunnel, or an authenticated reverse
proxy. If the remote is behind a path prefix, include that prefix in the machine URL, for example
<code>https://devbox.example.test/pi-web</code>.
</p>
<div class="callout danger">
Do not expose PI WEB directly to the public internet. Register machines only over trusted network paths
and only when you trust the endpoint.
</div>
</section>
<section id="add-machine">
<h2>Add a remote machine</h2>
<ol>
<li>Open the PI WEB instance you want to use as the gateway.</li>
<li>Open <strong>Actions → Add Machine</strong>.</li>
<li>Enter the remote PI WEB base URL, including <code>http://</code> or <code>https://</code>.</li>
<li>Accept the suggested name or enter a friendlier sidebar label.</li>
<li>Paste an optional bearer token if the remote endpoint requires one.</li>
</ol>
<p>
The Machines section appears when there is more than one machine. Select a machine, then add projects,
workspaces, and sessions on that selected machine.
</p>
<div class="callout">
Removing a remote machine only removes it from this gateway's registry. It does not stop the remote PI WEB
service or delete projects, workspaces, sessions, or credentials on the target machine.
</div>
</section>
<section id="what-is-proxied">
<h2>What is proxied</h2>
<p>
After you select a machine, the rest of the app works in that machine's scope. The gateway routes the
selected-machine work to the target PI WEB runtime.
</p>
<ul>
<li>Projects and workspaces.</li>
<li>Files, previews, git status, and diffs.</li>
<li>Pi sessions, transcripts, prompts, model controls, and commands.</li>
<li>Activity indicators and realtime updates.</li>
<li>Terminals and terminal command runs.</li>
<li>Remote plugins from the selected machine.</li>
</ul>
</section>
<section id="auth-credentials">
<h2>Auth and credentials stay on the target machine</h2>
<p>
Model-provider credentials, Pi configuration, OAuth state, repositories, and active session runtimes stay
on the selected target machine. The gateway does not copy them into its own Pi configuration.
</p>
<ul>
<li>API-key provider configuration can be proxied through the gateway.</li>
<li>OAuth login should be completed by opening the remote PI WEB directly.</li>
<li>The optional machine bearer token is stored by the gateway and sent to the remote while proxying requests.</li>
</ul>
<p>
Use <strong>Actions → Open Selected Machine PI WEB</strong> when you need to authenticate directly on a
remote machine or inspect it outside the gateway.
</p>
</section>
<section id="plugins">
<h2>Remote plugins are machine-scoped</h2>
<p>
When you select a remote machine, PI WEB tries to load that machine's discovered plugins through the
gateway. Remote plugin actions, workspace panels, and workspace labels only appear while that machine is
selected, and documented file and terminal helpers run against that machine.
</p>
<p>
Remote plugins are still trusted browser-side code. Only federate machines whose PI WEB plugins you are
comfortable loading in the browser.
</p>
<p><a href="plugins.html#remote-machine-plugins">Read the remote machine plugin notes →</a></p>
</section>
<section id="trust-model">
<h2>Trust model</h2>
<p>
Machine federation is for trusted users, trusted PI WEB servers, and trusted network paths. Adding a
machine gives the gateway permission to contact that URL and forward user-initiated PI WEB traffic to it.
</p>
<ul>
<li>Use private networking, an SSH tunnel, or an authenticated reverse proxy.</li>
<li>Do not include credentials in the machine URL itself.</li>
<li>Use bearer tokens or proxy authentication when a remote endpoint needs an extra gate.</li>
</ul>
</section>
<section id="storage-troubleshooting">
<h2>Storage and troubleshooting</h2>
<p>
Remote machine records are stored on the gateway in <code>~/.pi-web/machines.json</code>. If
<code>PI_WEB_DATA_DIR</code> is set, they live under <code>$PI_WEB_DATA_DIR/machines.json</code>.
</p>
<ul>
<li>Use <strong>Actions → Refresh Selected Machine</strong> to re-check health.</li>
<li>Make sure the remote URL is reachable from the gateway server.</li>
<li>Open the remote PI WEB directly to verify it is running and to complete provider login flows.</li>
<li>Check gateway logs with <code>pi-web logs</code> for proxy timeouts or upstream errors.</li>
</ul>
<div class="doc-actions">
<a class="button primary" href="install.html#remote-access">Review remote access setup</a>
<a class="button" href="faq.html#remote-machines">Read remote machine FAQ</a>
</div>
</section>
</div>
</div>
</section>
</main>
<footer class="site-footer">
<div class="container footer-inner">
<span>PI WEB fleet</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="faq.html">FAQ</a>
<a href="https://github.com/jmfederico/pi-web">GitHub</a>
</div>
</div>
</footer>
<script src="site.js"></script>
</body>
</html>
docs/plugins.html
+5 -3
View File
@@ -28,6 +28,7 @@
<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="machines.html">Fleet</a>
<a href="install.html">Install</a>
<a href="plugins.html" aria-current="page">Plugins</a>
<a href="faq.html">FAQ</a>
@@ -297,9 +298,9 @@ After editing, check the manifest endpoint and browser-console failure cases.</c
<section id="remote-machine-plugins">
<h2>Remote machine plugins</h2>
<p>
With machine federation, PI WEB also loads discovered plugins from the selected remote machine. Remote
plugins are trusted browser-side code like local plugins, but their actions, workspace panels, and
workspace labels only appear while that machine is selected.
With <a href="machines.html">machine federation</a>, PI WEB also loads discovered plugins from the selected
remote machine. Remote plugins are trusted browser-side code like local plugins, but their actions,
workspace panels, and workspace labels only appear while that machine is selected.
</p>
<ul>
<li>File and terminal helpers run against the selected remote machine.</li>
@@ -398,6 +399,7 @@ After editing, check the manifest endpoint and browser-console failure cases.</c
<div class="footer-links">
<a href="./">Home</a>
<a href="remote-first.html">Remote-first</a>
<a href="machines.html">Fleet</a>
<a href="install.html">Install</a>
<a href="faq.html">FAQ</a>
<a href="https://github.com/jmfederico/pi-web">GitHub</a>
docs/plugins.md
+1 -1
View File
@@ -131,7 +131,7 @@ Reload the PI WEB browser tab. PI WEB serves plugin modules with an mtime-based
## Remote machine plugins
When machine federation is enabled, PI WEB also loads discovered plugins from the selected remote machine. Remote plugins are trusted browser-side code like local plugins, but their contributions are machine-scoped:
When [machine federation](https://pi-web.dev/machines.html) is enabled, PI WEB also loads discovered plugins from the selected remote machine. Remote plugins are trusted browser-side code like local plugins, but their contributions are machine-scoped:
- actions, workspace panels, and workspace labels only appear while that machine is selected;
- plugin file and terminal helpers run against that machine;
docs/remote-first.html
+2
View File
@@ -31,6 +31,7 @@
<a class="brand" href="./" aria-label="PI WEB home">PI WEB</a>
<div class="nav-links">
<a href="remote-first.html" aria-current="page">Remote-first</a>
<a href="machines.html">Fleet</a>
<a href="install.html">Install</a>
<a href="plugins.html">Plugins</a>
<a href="faq.html">FAQ</a>
@@ -182,6 +183,7 @@
<span>PI WEB · remote-first control for persistent AI agents.</span>
<div class="footer-links">
<a href="./">Home</a>
<a href="machines.html">Fleet</a>
<a href="install.html">Install</a>
<a href="plugins.html">Plugins</a>
<a href="faq.html">FAQ</a>
docs/styles.css
+12 -5
View File
@@ -201,8 +201,10 @@ video {
display: flex;
align-items: center;
gap: 6px;
min-width: 0;
color: var(--muted);
font-size: 0.95rem;
white-space: nowrap;
}
.nav-links a,
@@ -856,6 +858,7 @@ code .comment,
.footer-links {
display: flex;
flex-wrap: wrap;
gap: 14px;
}
@@ -1062,11 +1065,7 @@ html[data-theme="light"] .comment {
}
}
@media (max-width: 680px) {
.container {
width: min(100% - 28px, 1120px);
}
@media (max-width: 820px) {
.nav {
position: relative;
align-items: stretch;
@@ -1085,7 +1084,9 @@ html[data-theme="light"] .comment {
flex-wrap: nowrap;
overflow-x: auto;
width: 100%;
padding-bottom: 2px;
scrollbar-width: none;
-webkit-overflow-scrolling: touch;
}
.nav-links a:not(.github-link) {
@@ -1124,6 +1125,12 @@ html[data-theme="light"] .comment {
.nav-links .theme-toggle [data-theme-label] {
display: none;
}
}
@media (max-width: 680px) {
.container {
width: min(100% - 28px, 1120px);
}
.hero {
padding-top: 52px;