Frequently Asked Questions

Iroh is a modular networking stack in Rust that provides an API for dialing by public key instead of IP addresses. It handles the complexity of finding and maintaining the fastest connections between endpoints, regardless of their location. Iroh uses techniques like hole-punching and falls back to public relay servers when needed, all built on top of QUIC for secure, efficient communication.

Iroh solves the fundamental problem of establishing direct connections in today's complex network environments. Traditional IP-based networking struggles with NAT traversal, firewalls, and dynamic addresses. Iroh abstracts away these challenges by allowing applications to connect using public keys, automatically finding the optimal path between endpoints. This simplifies peer-to-peer communication and makes applications more resilient to network changes.

Iroh is designed for developers building peer-to-peer applications, distributed systems, and secure communication tools. It's particularly valuable for:

• Rust developers looking for a robust networking foundation
• Teams building decentralized applications
• Developers needing secure, efficient data transfer
• Creators of mesh networks and overlay systems
• Anyone wanting to simplify network connectivity in their applications

Iroh works through a multi-step connection establishment process:

1. Key-based dialing: Applications initiate connections using public keys instead of IP addresses
2. Discovery: Iroh discovers available endpoints through DNS/Pkarr lookup
3. Hole-punching: Attempts direct connections by punching through NATs and firewalls
4. Relay fallback: If direct connection fails, uses public relay servers
5. Optimization: Continuously measures and selects the fastest available path

All communication is secured using QUIC with authenticated encryption and stream multiplexing.

Hole-punching is a technique used to establish direct connections between devices behind NAT (Network Address Translation) firewalls. When two peers want to connect:

• They simultaneously send packets to each other's public addresses
• This "punches a hole" in their respective NATs
• Allows direct communication without going through relay servers

Iroh implements sophisticated hole-punching algorithms to maximize successful direct connections, providing lower latency and better performance than relay-only connections.

Iroh is built on several key protocols:

• QUIC: For secure, multiplexed connections with authenticated encryption
• noq: The QUIC implementation used by iroh
• BLAKE3: For content-addressed blob transfers in iroh-blobs
• Pkarr: For decentralized DNS resolution of endpoint IDs
• Custom protocols: Built on top of QUIC for specific use cases

Iroh provides several ready-to-use protocols that build on its core networking capabilities:

• iroh-blobs: BLAKE3-based content-addressed blob transfer system that scales from kilobytes to terabytes
• iroh-gossip: Publish-subscribe overlay networks designed to scale efficiently on resource-constrained devices
• iroh-docs: Eventually-consistent key-value store that uses iroh-blobs for data storage
• iroh-doctor: Network diagnostic and testing tools

These protocols provide high-level functionality that developers can use directly without implementing networking logic from scratch.

Getting started with iroh is straightforward:

1. Add iroh to your Rust project: cargo add iroh
2. Read the documentation at docs.iroh.computer
3. Check out examples in the iroh-examples repository
4. Join our Discord community for help

The simplest way to start is using the pre-built protocols like iroh-blobs or iroh-gossip, which provide high-level functionality for common networking tasks.

Here's a basic example of using iroh to establish a connection:

const ALPN: &[u8] = b"iroh-example/echo/0";

let endpoint = Endpoint::bind().await?;

// Open a connection to the accepting endpoint
let conn = endpoint.connect(addr, ALPN).await?;

// Open a bidirectional QUIC stream
let (mut send, mut recv) = conn.open_bi().await?;

// Send data
send.write_all(b"Hello, world!").await?;
send.finish()?;

// Receive response
let response = recv.read_to_end(1000).await?;
assert_eq!(&response, b"Hello, world!");

// Close connection
conn.close(0u32.into(), b"bye!");
endpoint.close().await;

For more detailed examples, see the iroh-examples repository.

Yes! Iroh provides FFI (Foreign Function Interface) bindings for other languages through the iroh-ffi repository. This allows developers to use iroh from languages like Python, JavaScript, Go, and others. The FFI bindings provide the same core functionality as the Rust library but with language-specific interfaces.

Check the iroh-ffi repository for language-specific documentation and examples.

Examples are available in several places:

• iroh-examples repository on GitHub
• Documentation at docs.iroh.computer
• Examples in the main iroh repository
• Video tutorials on our YouTube channel

Examples cover basic connections, using built-in protocols, and advanced networking patterns.

The iroh repository is organized as a Rust workspace with several interdependent crates:

• iroh: Core library providing hole-punching and relay communication
• iroh-relay: Relay client and server implementation (used for public relays)
• iroh-base: Common types like EndpointId and RelayUrl
• iroh-dns-server: DNS server implementation for endpoint ID resolution (running at dns.iroh.link)

This modular structure allows components to be used independently while maintaining interoperability.

Iroh implements multiple layers of security:

• QUIC encryption: All communication uses authenticated encryption with forward secrecy
• Key-based authentication: Connections are established using cryptographic key pairs
• Content integrity: Uses BLAKE3 for content-addressed transfers
• Secure relays: Public relay servers use TLS and authentication
• Minimal attack surface: Modular design allows security features to be used selectively

Security is a first-class consideration in all iroh components.

Contributions are welcome! Here's how you can help:

• Report bugs or request features on GitHub Issues
• Submit pull requests to the main repository
• Contribute to examples or documentation
• Help answer questions in our Discord community
• Create and share projects built with iroh

All contributions are dual-licensed under both Apache 2.0 and MIT licenses.

Help is available through several channels:

• Discord server for real-time discussion
• GitHub Issues for bug reports and feature requests
• Documentation with comprehensive guides
• GitHub Discussions for community Q&A

For urgent issues, join our Discord community for immediate assistance.

Iroh is dual-licensed under both the Apache License 2.0 and the MIT license. This means you can choose the license that best suits your project needs. The full license texts are available in the repository:

• LICENSE-APACHE
• LICENSE-MIT

Yes! Both the Apache 2.0 and MIT licenses allow for commercial use. You can use iroh in proprietary, closed-source commercial applications without any restrictions. The only requirements are:

• Include the appropriate license notice in your product
• For Apache 2.0: provide a copy of the license with your distribution
• For MIT: include the original copyright and license notice

Iroh is designed for both open-source and commercial use cases.