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, Pi package settings, and plugins.

What Fleet does

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, terminals, and Pi package-management operations to the browser UI.

Fleet shape 
Browser
  ↓
PI WEB gateway you opened
  ├─ [ Local runtime ]
  │
  ├─ [ Remote PI WEB runtime A ]
  │     ↓ selected machine
  │     projects, workspaces, sessions, terminals, Pi packages, plugins
  │
  └─ [ Remote PI WEB runtime B ]

When to use it

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, Pi package settings, and plugins.

Set up another runtime

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 --allow-scripts=node-pty
$ 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. The machine registry normalizes the trailing slash; when opening that deployment directly in a browser, use its canonical https://devbox.example.test/pi-web/ URL and configure the proxy to redirect the slashless form.

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 machine

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

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 works remotely

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.
  • Pi package listing, install, remove, and update from Settings → Pi packages when supported by the target PI WEB runtime.
  • Remote plugins from the selected machine.

Credentials stay on the target machine

Model-provider credentials, Pi configuration, Pi package-manager settings, 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.

Plugins follow the selected machine

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 boundaries

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.

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