iroh

iroh is a Rust library that adds QUIC-based peer-to-peer networking with NAT traversal to applications, letting them establish direct connections to other peers by dialing a stable public key instead of a fragile, frequently-changing IP address. It handles the hard parts of P2P connectivity — hole punching, relay fallback when a direct connection isn’t possible, and multipath/connection migration as network conditions change — behind an API that otherwise feels like using QUIC directly.

The project is a Cargo workspace maintained by n0 (the team behind the project, formerly at Number Zero), split into iroh (the core endpoint/connection library), iroh-relay (a relay server for peers that can’t connect directly), iroh-dns/iroh-dns-server (a DNS-based node discovery mechanism), and iroh-base (shared low-level types), giving applications a complete toolkit for building direct, encrypted, address-independent peer connections.

What You Get

• An Endpoint API for dialing and accepting peer-to-peer QUIC connections identified by public key rather than network address
• Automatic NAT traversal and hole punching, with transparent fallback to relay servers when a direct connection can’t be established
• iroh-relay — a relay server implementation for peers behind restrictive NATs/firewalls that can’t connect directly
• iroh-dns/iroh-dns-server — DNS-based node discovery so peers can be found without a centralized rendezvous service
• Connection migration/multipath support so an active connection can survive network changes (e.g. moving from Wi-Fi to cellular)
• WASM target support (the iroh crate builds as both a regular lib and a cdylib for wasm32-unknown-unknown)

Common Use Cases

• Building peer-to-peer file-sync or file-transfer applications that need direct connections without relying on a central server for data transfer
• Adding real-time collaborative or multiplayer features to an application where peers should connect directly when possible
• Building decentralized applications that need stable peer addressing (by public key) that survives IP address changes, NAT rebinding, or peer mobility
• Any Rust or WASM application needing encrypted, low-latency direct connections between nodes without operating its own STUN/TURN-equivalent infrastructure

Under The Hood

Architecture — The iroh crate’s src/ is organized around endpoint.rs/endpoint/ (the core dial/accept API), net_report.rs/net_report/ (network condition and NAT-type detection used to decide direct vs. relay connectivity), address_lookup.rs/address_lookup/ (resolving a public key to reachable network addresses via relay/DNS discovery), portmapper.rs (UPnP/NAT-PMP port mapping for improving direct connectivity odds), socket.rs/socket/ (the underlying UDP socket abstraction QUIC runs over), and tls.rs/tls/ (the key-based TLS identity layer that replaces traditional certificate-authority trust). The broader workspace separates concerns further: iroh-relay runs as its own relay server, iroh-dns-server runs the discovery service, and iroh-base holds shared types used across all of them.

Tech Stack — Rust throughout, built on QUIC (a modern transport that multiplexes streams over UDP with built-in TLS 1.3), with blake3 for content hashing/identity, derive_more for reducing boilerplate on domain types, and backon for retry/backoff logic during connection establishment. The library also compiles to WASM (crate-type = ["lib", "cdylib"]), a notable feature for a P2P networking library, since browser environments have much more restricted networking primitives.

Code Quality — The workspace enforces missing_debug_implementations = "warn" at the lint level across all members, a deliberate discipline choice for a networking library where debuggability of connection/endpoint state matters. The project maintains a dedicated iroh/bench workspace member for connection benchmarking, and splits concerns (relay, DNS discovery, base types) into separately versioned crates rather than one monolith, which limits blast radius when any one component changes.

API Design — The core mental model — dial a public key, get back a connection, use it like a QUIC stream — is a deliberate simplification over raw QUIC/UDP APIs, hiding NAT traversal and relay fallback behind the same Endpoint::connect call regardless of what path the connection actually takes. This design choice (a self-aware README tagline: “IP addresses break, dial keys instead”) is the library’s central value proposition and keeps the common-case API surface small even though the underlying connectivity logic is substantial.