How to

Pair two nodes

Pairing makes two nodes (a server and a laptop, two servers) one Mandala.

The simplest way to add a node is to join it with a code from its first screen: Join a device with a code. This page pairs two nodes by hand, by device key, for nodes that already have data or no screen.

Pair on both sides.

1. Get each device's key

On each node, open Settings → Devices and sync. This device → Device key shows 64 hex characters. Copy it.

2. Pair from each side

On node A, under Pair a device:

Name — "MacBook Pro".
Its device key — node B's key.
Where to reach it — one of:
- iroh: find it anywhere by its key, through the device mesh (direct connections with hole punching; see Ports and network);
- its address on your tailnet: http://macbook.<tailnet>.ts.net:8787;
- empty, if only B can reach A (a laptop behind a home router pairing with a server).

Press Pair. Then do the same on node B with node A's key.

3. Check

Under Your other devices, the peer shows Syncing (this node visits it) or Trusted (it visits this node), and how many of its changes are held here. Changes appear on the other node within about 20 seconds.

What pairing does

Pairing enrolls the device as yours: the enrollment record syncs, so every one of your nodes trusts it, including nodes it never paired with directly. Each pull is signed by the device's key, because changes carry personal data.

Forget a device

Forget revokes it everywhere: your nodes refuse its new changes. Do this at once for a lost or sold machine.

With root keys

Once you have a root key, only devices it certified are trusted. Certify a new device in Settings → Root keys → Devices. See Keys and recovery.