Pair a client

Pairing is how two machines learn to trust each other. It happens once per device pair; every later connection authenticates automatically from pinned keys.

Pairing over the internet? Enrol your rendezvous first. A pairing token carries the rendezvous details the host knew at the moment it was minted, so one generated before the bundle is enrolled only works on your own network. Do it in order — deploy the rendezvous, enrol its bundle, then mint tokens. On your own LAN this doesn’t apply; carry on below.

Pair

PIN pairing is for a client on the same network as the host. From anywhere else — the internet, a Tailscale or other overlay address, a relayed connection — the host refuses a PIN request outright, and you pair with a pairing token minted on the host’s Pairing page instead. That keeps a stranger who can reach the host from putting approval prompts on your screen.

1. In the client — Windows, Mac, or iOS — add the host by address: <host-ip>:48010, the address from ipconfig / your network settings.
2. The client mints a 6-digit PIN and shows it on its own screen.
3. On the host, approve the PIN within 60 seconds via the admin UI at https://127.0.0.1:48011/pairing — the pending request appears in a table; type the digits and click Approve. From an admin shell, nearzero-host pair approve <pin> does the same.
4. Both peers pin each other’s identity and the client immediately reconnects to stream.

The PIN is never sent over the network. Each side proves inside the handshake that it knows it — a wrong PIN fails cryptographically, on both ends, with a clean error.

First-time pairing, by PIN or by token, uses a password-authenticated key exchange, so a PIN or code only ever allows one guess per attempt.

Why you never re-pair

The pairing stores the host’s identity, not its address. If the client later reaches the same host at a different IP — LAN at home, Tailscale from a café, DHCP handing out something new — it recognises the pinned identity automatically and remembers the new address alongside the old. Multi-network setups never trigger a second pairing.

If something refuses to connect

• Host and client must be on the same line: the leftmost non-zero number of their versions, 0.9 today. The rest of their numbers need not match, and usually will not. See which versions work together.
• Five wrong password attempts in a row earns a 1-minute ban, ten in ten minutes earns ten. The client shows one clean error, not a hang.
• The host closes a PIN request straight away? The client is not on the host’s network as the host sees it — a public, overlay or relayed address. Mint a pairing token on the host and use that.
• Pairing is refused over a version? Host and client are on different lines. Update whichever is behind; if the client says the host is too old, that is the host.
• Pairing from outside your network times out with no error? The token was almost certainly minted before the rendezvous bundle reached the host, or the rendezvous has no public address. Both cases are called out on the host’s Pairing page — fix the address, restart the rendezvous, wait about a minute for the host to reconnect, then mint a fresh token. Existing tokens don’t gain the rendezvous retroactively.

Next: put a connection password on top, or reach your host across the internet.