Remote Pi
TutorialsDocsGitHub Install
Tutorial · 3 of 4

Remote mesh

The local mesh stops at one machine. Turn on the relay and the same agent_send reaches agents on other PCs — your laptop talking to your desktop, a build box, a server. The tools are identical; only the addressing changes.

1. Put both machines on one mesh

Cross-PC routing rides the relay. Every machine paired under the same Owner key forms one logical mesh — there is no central server, just a relay forwarding between paired peers. To get there:

  • On each machine, run /remote-pi and answer Yes to using the relay.
  • Pair both machines to the same Owner so they share one mesh. The mesh-membership details — how the Owner key signs the device list — live in PROTOCOL.md.

Point both machines at the same relay. The default is the community relay; for your own, see the relay reference.

2. Address peers across PCs

Once both machines are on the mesh, list_peers()shows local agents plus remote ones, each prefixed with the source machine's label:

any agent · tool call — text
list_peers()
→ frontend                 # local — same machine
  MacMini:backend          # remote — agent "backend" on PC "MacMini"
  build-box:tests          # remote — agent "tests" on PC "build-box"

To message a remote peer, use its full pc_label:peername verbatim — that's the only difference from a local send:

frontend · tool call — text
agent_send({
  to: "MacMini:backend",
  body: { task: "run the integration suite and report failures" }
})
→ Delivered to MacMini:backend

The reply arrives the same way a local one does — in your inbox on a future turn, carrying re=<your-send-id>.

3. "Delivered" is not "alive"

This is the one thing to internalize about remote sends. A Delivered ACK means the remote broker accepted the envelope — nothing more. It does not mean the peer is alive, processed the message, or will ever answer.

Validate by roundtrip
Don't treat Delivered as proof the other agent is working. list_peers can even list a peer that has gone stale. The only real confirmation is a reply you actually receive: ask the remote agent to respond, then wait for that envelope in your inbox. If it never comes, the peer may be offline regardless of what the ACK said.

When a forwarded message genuinely can't be delivered, the relay returns a transport_error envelope with re=<your-send-id> — watch your inbox for that too.

What the relay sees

The relay is the only network-touching piece, so it's worth being precise about what it protects and what it doesn't:

Encrypted in transit — payloads are not
Connections to the relay are encrypted in transit (TLS), and devices authenticate each other with Ed25519 pairing. But message payloads are not encrypted at the application layer — the relay operator could in principle read plaintext in memory while forwarding. If you need confidentiality from the relay operator, self-host the relay behind a VPN.

The community relay does not log, persist, or inspect payloads, but self-hosting is the way to get cryptographic-grade isolation. The full trust model is in PROTOCOL.md.

What it's for

Cross-PC messaging lets you split work across roles that live on different machines — a frontend on your laptop handing tasks to a backend on a beefier box, or a tests agent on a build server reporting back. Same tools, same envelope; the relay just carries it between machines.

Keep them reachable

Cross-PC coordination is most useful when the remote agents are always up. That's the next guide: run them as 24/7 daemons.