Overview
The Peer module pairs two TermFlow instances running on different machines over your LAN, so they can share terminal access and let an AI agent route commands to another machine — not just the one it's already plugged into. This section covers how pairing works, how you control what a peer is allowed to do, and how the Fleet capability turns a paired machine into a remote target an agent can command.
What pairing gives you
- Pairing — two TermFlow instances establish trust with a short pairing code and a pinned per-device identity; the data plane is mTLS. No cloud account or relay involved.
- Grants — once paired, you decide which of your terminals a peer can View (read-only) or Control (read + drive) on a per-terminal basis.
- Fleet — an agent driving one instance can target a specific remote terminal, a specific paired machine, or "whichever paired machine runs macOS" and have the command run there, with the result and a live screen streamed back.
Everything is managed from Settings → Peers.
Peering is a Pro feature — the Peers panel carries a "Pro" badge. TermFlow's core app runs fully without it: if the peering component isn't installed, the Peers panel reads "Peering is not installed" and every remote Fleet operation returns HTTP 501 { "error": "peering not installed" } — except the machine roster, which still returns self, so local-only tooling (like list_machines) keeps working either way.
How a command reaches another machine
The agent never talks to the remote machine directly. It calls the local instance's MCP server or REST API as usual; the local core resolves the target and, if it's remote, forwards the request over the mTLS connection established during pairing. The response — including a live screen — flows back the same way.
In this section
| Page | Covers |
|---|---|
| Pairing machines | The pairing-code flow, mTLS identity, OS capture, and what "Peering is not installed" means |
| Grants & consent | Per-terminal View/Control grants vs. the per-peer "Allow fleet commands" consent toggle |
| Fleet commands | Targeting precedence, the persistent remote terminal, and the long-poll execution model |
| Fleet API & MCP | The /api/fleet/* REST endpoints and the fleet-aware MCP tools |
Next steps
- Pairing machines — pair your first two instances.
- MCP Tools — the full MCP tool reference, including the fleet-aware tools.