At the core of iroh is a network where any two nodes within the network can establish a connection.


An iroh network is a collection of nodes. A node is a running process that might accept connections from other nodes on a given port. Multiple nodes can be run on the same physical device, but not the same port.

A node has a cryptographic keypair used for signing messages. Nodes are uniquely identified by the public portion of their keypair.


An iroh connection is a QUIC connection running on a Magic Socket. QUIC is a modern transport protocol that provides a reliable, encrypted, multiplexed connection between two nodes. QUIC is built on top of UDP, and is designed to be used in situations where TCP is not a good fit (such as mobile networks).


Connections in iroh have a MagicSocket sitting between QUIC and the operating system socket (the "real socket"). The MagicSocket simulates a connection for the quic transport, and dynamically optimizes the connection path between two nodes as connections are negotiated & optimized. The MagicSocket will perform interactive connectivity establishment (ICE), using an advertised set of connection details to audition connections. The magicsocket will perform latency probes for any viable connections, switching to find the fastest ping.


Sometimes it isn't possible to establish a direct connection between two nodess, often because of strict firewall rules or NAT configurations. In these cases the only fallback is to relay traffic through a third node that both nodes can connect to. Instead of sending packets directly from one node to the other, packets in either direction are first sent to the relay node, which forwards packets on to their destination. All QUIC traffic is encrypted, and relayed traffic is no exception. The relaying server cannot inspect the contents of the packets being forwarded,