Skip to main content
With holepunching, iroh applications can:
  • Connect directly between devices without manual network configuration
  • Reduce latency by avoiding servers when possible
  • Save bandwidth by keeping data transfer peer-to-peer
  • Improve resilience and reliability by not depending on all traffic being sent through third parties
The best part? All of this happens automatically—you don’t need to understand the technical details to benefit from it.

​
The Problem: NAT Blocks Direct Connections

Imagine you’re trying to video call a friend. Both of you are behind routers at home. When you try to connect directly to each other, your routers’ firewalls block the incoming connection because they don’t recognize it as a response to something you requested. The combination of NAT (which translates addresses) and firewall rules (which filter traffic) makes direct connections challenging. Most home and office networks use NAT, which acts like a one-way door—devices inside the network can reach out to the internet, but the internet can’t easily reach back in. This causes reliance on central servers, which can introduce latency and reliability issues. Traditionally, this problem was solved by:
  • Port forwarding: Manually configuring your router to allow specific connections (tedious and requires technical knowledge)
  • Relay servers: Routing all traffic through a third-party server (slow and expensive)

​
The Innovation: Holepunching

Holepunching is a clever technique that works around NAT and firewall restrictions to allow direct connections between peers without manual configuration or relying entirely on relay servers. iroh uses a sophisticated holepunching implementation built on top of QUIC and integrates with the relay system. The process relies on two key elements: Holepunching works in most network configurations, but some corporate firewalls or cellular networks may still require relay fallback. iroh handles this automatically.

​
How Holepunching Works in iroh

​
1. Initial Contact Through a Relay

Both peers first connect to a shared relay server. The relay acts as a meeting point where peers can coordinate without being able to connect directly yet. The relay server observes each node’s public IP address and port (the address from which it sees incoming traffic). This reflective address can be used by the remote peer to reach through the firewall, provided the firewall considers it expected traffic.

​
2. Sharing Connection Information

Through the relay, peers exchange their:
  • Public IP addresses (how they appear to the outside internet)
  • Port numbers (the specific door number the router assigned them)
  • Local addresses (in case they’re on the same network)
Nodes coordinate their holepunching attempts through the relay as a side channel. Both nodes simultaneously send UDP datagrams to each other’s reflective addresses. Since both are sending on the same 4-tuple (source IP, source port, destination IP, destination port), the firewalls recognize the incoming packets as matching outbound traffic and allow them through. Importantly, the relay server doesn’t actively participate in holepunching — it simply forwards encrypted packets between nodes without knowledge of whether they contain application data or coordination messages.

​
3. Simultaneous Outbound Connection

Here’s the magic: both peers try to connect to each other at the same time. When peer A sends a packet to peer B’s public address, A’s NAT creates a mapping and the firewall creates a temporary rule allowing responses from B. When peer B sends a packet to peer A at the same moment, B’s NAT and firewall do the same. Because both NAT mappings are established and both firewalls now have rules expecting traffic from each other, the packets get through, and a direct connection is established!

​
4. Fallback to Relay

If holepunching fails (some networks use particularly strict NAT configurations), iroh automatically falls back to routing traffic through the relay server. This ensures connections always work, even if they can’t be direct.

​
Read more

For technical details on the implementation, see: