diff --git a/.changeset/document-machine-federation.md b/.changeset/document-machine-federation.md new file mode 100644 index 0000000..bb57440 --- /dev/null +++ b/.changeset/document-machine-federation.md @@ -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. diff --git a/README.md b/README.md index 1a91c11..e7aff9e 100644 --- a/README.md +++ b/README.md @@ -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. diff --git a/docs/404.html b/docs/404.html index 7821ce7..766b4f1 100644 --- a/docs/404.html +++ b/docs/404.html @@ -29,6 +29,7 @@ PI WEB
Remote-first + Fleet Install Plugins FAQ @@ -75,6 +76,7 @@
PI WEB · remote control for persistent Pi Coding Agent sessions.
+ Fleet Install Plugins FAQ diff --git a/docs/faq.html b/docs/faq.html index 240b8e9..ba14122 100644 --- a/docs/faq.html +++ b/docs/faq.html @@ -28,6 +28,7 @@ PI WEB
Remote-first + Fleet Install Plugins FAQ @@ -71,6 +72,7 @@ User service manager is unavailable I cannot open the web UI Can I expose this publicly? + How do remote machines work? Laptop or server? Can I use local plugins? Sessions stop unexpectedly @@ -189,6 +191,23 @@

+
+

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?

@@ -251,6 +270,7 @@

Home Remote-first + Fleet Install Plugins Issues diff --git a/docs/index.html b/docs/index.html index ea0ea08..ef9505d 100644 --- a/docs/index.html +++ b/docs/index.html @@ -35,6 +35,7 @@ PI WEB
Remote-first + Fleet Install Plugins FAQ @@ -298,6 +299,7 @@ PI WEB · remote control for persistent Pi Coding Agent sessions.
Remote-first + Fleet Install Plugins FAQ diff --git a/docs/install.html b/docs/install.html index c469876..9644398 100644 --- a/docs/install.html +++ b/docs/install.html @@ -28,6 +28,7 @@ PI WEB
Remote-first + Fleet Install Plugins FAQ @@ -70,6 +71,7 @@ Install through Pi WSL / manual run Remote access + Federated machines Manage services Configure Uninstall @@ -189,11 +191,28 @@
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 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.

@@ -289,6 +308,7 @@
Home Remote-first + Fleet Plugins FAQ GitHub diff --git a/docs/machines.html b/docs/machines.html new file mode 100644 index 0000000..ab70d8c --- /dev/null +++ b/docs/machines.html @@ -0,0 +1,277 @@ + + + + + + PI WEB fleet + + + + + + + + + + + +
+ +
+ +
+
+
+

PI WEB fleet

+

Connect trusted PI WEB runtimes when one machine is not enough.

+

+ 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. +

+
+
+ +
+
+ + +
+
+

What machine federation is

+

+ 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. +

+

+ 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. +

+
+
+ Federated shape + +
+ 
Browser
+  ↓
+PI WEB gateway you opened
+  ↓ gateway proxy
+Remote PI WEB runtime
+  ↓
+Remote projects, workspaces, sessions, terminals, plugins
+
+
+ +
+

When to use federation

+

+ Federation is useful when you have more than one place where agents should work, but you want one stable + browser entrypoint. +

+
+
+
▦
+

Many dev boxes

+

Register a workstation, home server, cloud VM, or client-specific host without moving repositories.

+
+
+
⇄
+

One gateway

+

Open one trusted PI WEB URL and switch machines instead of juggling browser tabs and tunnels.

+
+
+
⌁
+

Local ownership

+

Each target machine keeps its own Pi auth, sessions, worktrees, terminal state, and plugins.

+
+
+
+ +
+

Prepare the target machines

+

+ 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. +

+
+
+ Install on each target + +
+ 
$ npm install -g @jmfederico/pi-web
+$ pi-web install
+$ pi-web doctor
+
+

+ 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 + https://devbox.example.test/pi-web. +

+
+ Do not expose PI WEB directly to the public internet. Register machines only over trusted network paths + and only when you trust the endpoint. +
+
+ +
+

Add a remote machine

+
    +
  1. Open the PI WEB instance you want to use as the gateway.
    2. +
  2. Open Actions → Add Machine.
    3. +
  3. Enter the remote PI WEB base URL, including http:// or https://.
    4. +
  4. Accept the suggested name or enter a friendlier sidebar label.
    5. +
  5. Paste an optional bearer token if the remote endpoint requires one.
    6. +
+

+ The Machines section appears when there is more than one machine. Select a machine, then add projects, + workspaces, and sessions on that selected machine. +

+
+ 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. +
+
+ +
+

What is proxied

+

+ 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. +

+
    +
  • Projects and workspaces.
    • +
  • Files, previews, git status, and diffs.
    • +
  • Pi sessions, transcripts, prompts, model controls, and commands.
    • +
  • Activity indicators and realtime updates.
    • +
  • Terminals and terminal command runs.
    • +
  • Remote plugins from the selected machine.
    • +
+
+ +
+

Auth and credentials stay on the target machine

+

+ 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. +

+
    +
  • API-key provider configuration can be proxied through the gateway.
    • +
  • OAuth login should be completed by opening the remote PI WEB directly.
    • +
  • The optional machine bearer token is stored by the gateway and sent to the remote while proxying requests.
    • +
+

+ Use Actions → Open Selected Machine PI WEB when you need to authenticate directly on a + remote machine or inspect it outside the gateway. +

+
+ +
+

Remote plugins are machine-scoped

+

+ 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. +

+

+ Remote plugins are still trusted browser-side code. Only federate machines whose PI WEB plugins you are + comfortable loading in the browser. +

+

Read the remote machine plugin notes →

+
+ +
+

Trust model

+

+ 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. +

+
    +
  • Use private networking, an SSH tunnel, or an authenticated reverse proxy.
    • +
  • Do not include credentials in the machine URL itself.
    • +
  • Use bearer tokens or proxy authentication when a remote endpoint needs an extra gate.
    • +
+
+ +
+

Storage and troubleshooting

+

+ Remote machine records are stored on the gateway in ~/.pi-web/machines.json. If + PI_WEB_DATA_DIR is set, they live under $PI_WEB_DATA_DIR/machines.json. +

+
    +
  • Use Actions → Refresh Selected Machine to re-check health.
    • +
  • Make sure the remote URL is reachable from the gateway server.
    • +
  • Open the remote PI WEB directly to verify it is running and to complete provider login flows.
    • +
  • Check gateway logs with pi-web logs for proxy timeouts or upstream errors.
    • +
+
+ Review remote access setup + Read remote machine FAQ +
+
+
+
+
+
+ + + + + diff --git a/docs/plugins.html b/docs/plugins.html index 7963d6b..ea29827 100644 --- a/docs/plugins.html +++ b/docs/plugins.html @@ -28,6 +28,7 @@ PI WEB
Remote-first + Fleet Install Plugins FAQ @@ -297,9 +298,9 @@ After editing, check the manifest endpoint and browser-console failure cases.

Remote machine plugins

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

  • File and terminal helpers run against the selected remote machine.
    • @@ -398,6 +399,7 @@ After editing, check the manifest endpoint and browser-console failure cases. Home Remote-first + Fleet Install FAQ GitHub diff --git a/docs/plugins.md b/docs/plugins.md index 54e6871..9e8d501 100644 --- a/docs/plugins.md +++ b/docs/plugins.md @@ -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; diff --git a/docs/remote-first.html b/docs/remote-first.html index c75f4dc..b864c69 100644 --- a/docs/remote-first.html +++ b/docs/remote-first.html @@ -31,6 +31,7 @@ PI WEB
    Remote-first + Fleet Install Plugins FAQ @@ -182,6 +183,7 @@ PI WEB · remote-first control for persistent AI agents.
    Home + Fleet Install Plugins FAQ diff --git a/docs/styles.css b/docs/styles.css index 681fedd..3660062 100644 --- a/docs/styles.css +++ b/docs/styles.css @@ -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;