iroh

less net work for networks

## What is iroh? Iroh gives you an API for dialing by public key. You say “connect to that phone”, iroh will find & maintain the fastest connection for you, regardless of where it is. ### Hole-punching The fastest route is a direct connection, so if necessary, iroh tries to hole-punch. Should this fail, it can fall back to an open ecosystem of public relay servers. To ensure these connections are as fast as possible, we [continuously measure iroh][iroh-perf]. ### Built on [QUIC] Iroh uses [noq] to establish [QUIC] connections between endpoints. This way you get authenticated encryption, concurrent streams with stream priorities, a datagram transport and avoid head-of-line-blocking out of the box. ## Compose Protocols Use pre-existing protocols built on iroh instead of writing your own: - [iroh-blobs] for [BLAKE3]-based content-addressed blob transfer scaling from kilobytes to terabytes - [iroh-gossip] for establishing publish-subscribe overlay networks that scale, requiring only resources that your average phone can handle - [iroh-docs] for an eventually-consistent key-value store of [iroh-blobs] blobs ## Getting Started ### Rust Library It's easiest to use iroh from rust. Install it using `cargo add iroh`, then on the connecting side: ``` … ``` And on the accepting side: ```rs let endpoint = Endpoint::bind().await?; let router = Router::builder(endpoint) .accept(ALPN.to_vec(), Arc::new(Echo)) .spawn() .await?; // The protocol definition: #[derive(Debug, Clone)] struct Echo; impl ProtocolHandler for Echo { async fn accept(&self, connection: Connection) -> Result<()> { let (mut send, mut recv) = connection.accept_bi().await?; // Echo any bytes received back directly. let bytes_sent = tokio::io::copy(&mut recv, &mut send).await?; send.finish()?; connection.closed().await; Ok(()) } } ``` The full example code with more comments can be found at [`echo.rs`][echo-rs]. Or use one of the pre-existing protocols, e.g. [iroh-blobs] or [iroh-gossip]. ### Other Languages If you want to use iroh from other languages, make sure to check out [iroh-ffi], the repository for FFI bindings. ### Links - [Introducing Iroh (video)][iroh-yt-video] - [Iroh Documentation][docs] - [Iroh Examples] - [Iroh Experiments] ## Repository Structure This repository contains a workspace of crates: - `iroh`: The core library for hole-punching & communicating with relays. - `iroh-relay`: The relay client and server implementation. This is the code we run in production for the public relays (and you can, too!). - `iroh-base`: Common types like `EndpointId` or `RelayUrl`. - `iroh-dns-server`: DNS server implementation powering the DNS/Pkarr address lookup for EndpointIds, running at dns.iroh.link. ## License Copyright 2025 N0, INC. This project is licensed under either of * Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or https://www.apache.org/licenses/LICENSE-2.0) * MIT license ([LICENSE-MIT](LICENSE-MIT) or https://opensource.org/licenses/MIT) at your option. ## Contribution Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this project by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions. [QUIC]: https://en.wikipedia.org/wiki/QUIC [BLAKE3]: https://github.com/BLAKE3-team/BLAKE3 [noq]: https://github.com/n0-computer/noq [iroh-blobs]: https://github.com/n0-computer/iroh-blobs [iroh-gossip]: https://github.com/n0-computer/iroh-gossip [iroh-docs]: https://github.com/n0-computer/iroh-docs [iroh-doctor]: https://github.com/n0-computer/iroh-doctor [willow protocol]: https://willowprotocol.org [iroh-ffi]: https://github.com/n0-computer/iroh-ffi [iroh-yt-video]: https://www.youtube.com/watch?v=RwAt36Xe3UI_ [Iroh Examples]: https://github.com/n0-computer/iroh-examples [Iroh Experiments]: https://github.com/n0-computer/iroh-experiments [echo-rs]: /iroh/examples/echo.rs [iroh-perf]: https://perf.iroh.computer [docs]: https://docs.iroh.computer