Use case

Peers behind home routers.

Most pairs connect directly through their NATs, with a little help from the node that stored the announcement. For the pairs that cannot, a relay you run yourself can join them.

The pieces

The libraries this needs. Each has install steps and a compiled example in its docs.

How it goes

  1. Announce and look up

    A peer announces its topic with a signed record at the servers closest to it, and looks up the others the same way.

  2. Punch through

    The server that stored the record relays a connect request, and the two peers open a direct path through their NATs. Nothing relays application data.

  3. A relay, only if you ask

    When both NATs pick random ports, the direct path fails with an error. Your app can then pass the address and key of a kolo-relay you run, and the peers connect end to end through it.

Good to know

Nothing in Kolo picks a relay or falls back to one on its own. The relay forwards ciphertext it cannot read, but it sees which keys talk, when and how much. A relay with no allow list lets anyone use its bandwidth. Kolo is IPv4 only.

Next