Iroh Examples: A Complete Guide to the n0-computer/iroh Code Samples

The n0-computer/iroh repository ships 14+ production-ready examples in iroh/examples/ that demonstrate everything from basic QUIC echo servers to post-quantum key exchange and custom transport implementations.

The Iroh networking library provides a comprehensive set of runnable examples that demonstrate its core Rust APIs. These examples, located in the iroh/examples/ directory, cover the three fundamental abstractions: the Endpoint, Router, and Connection types. Whether you are implementing reliable streams or unreliable datagrams, the Iroh examples provide copy-pasteable patterns for production use.

Complete List of Iroh Examples

The repository organizes examples by networking concept.

Basic Connection Handling

• echo.rs and echo-no-router.rs: Minimal client/server implementations showing the Router → ProtocolHandler flow with bidirectional streams.
• listen.rs: Demonstrates Endpoint creation, address publishing, and hole-punching via default relay servers.
• connect.rs: Shows how to parse an EndpointAddr and establish outgoing connections.

Unreliable Datagrams

• listen-unreliable.rs and connect-unreliable.rs: UDP-style communication using open_uni() and accept_uni() over QUIC.

Advanced Networking

• custom-transport.rs: Registers a custom Transport implementation via TransportMap to override default IP resolution.
• incoming-filter.rs: Uses the Router to filter inbound connections by metadata.
• monitor-connections.rs: Demonstrates runtime statistics gathering via router.metrics().

Specialized Protocols

• remote-info.rs: Queries endpoint metadata through the Iroh DNS server.
• search.rs: Implements a distributed key-value search service.
• transfer.rs: High-throughput bulk data transfer protocol.
• 0rtt.rs: Zero-RTT session resumption for reduced latency.

Cryptography

• pq-only-key-exchange.rs and prefer-pq-key-exchange.rs: Post-quantum key exchange using the tls-aws-lc-rs feature flag.

Core Architectural Patterns

Iroh examples map directly to three architectural layers.

Endpoint Management

The Endpoint represents a node identified by a public key and manages NAT traversal. In iroh/examples/listen.rs, binding works as follows:

use iroh::{Endpoint, endpoint::presets};

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

Protocol Routing

The Router dispatches incoming connections based on ALPN strings. The echo.rs example shows registration:

use iroh::protocol::{Router, ProtocolHandler};

let router = Router::builder(endpoint)
    .accept(ALPN, Echo)
    .spawn();

Stream Handling

Connections provide typed streams. Reliable bidirectional communication uses open_bi() and accept_bi() as shown in iroh/examples/echo.rs:

let (mut send, mut recv) = conn.accept_bi().await?;
tokio::io::copy(&mut recv, &mut send).await?;

Running the Examples

Execute any example using Cargo from the repository root:

cargo run --example <name> --release --all-features

The --all-features flag is required for post-quantum cryptography examples that depend on tls-aws-lc-rs.

Practical Code Snippets from Iroh Examples

Echo Server with Protocol Handler

This complete pattern from iroh/examples/echo.rs shows the minimal implementation:

use iroh::{Endpoint, endpoint::presets};
use iroh::protocol::{ProtocolHandler, Router, AcceptError};

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

#[derive(Clone)]
struct Echo;

#[async_trait::async_trait]
impl ProtocolHandler for Echo {
    async fn accept(&self, conn: iroh::protocol::Connection) -> Result<(), AcceptError> {
        let (mut send, mut recv) = conn.accept_bi().await?;
        tokio::io::copy(&mut recv, &mut send).await?;
        send.finish()?;
        Ok(())
    }
}

#[tokio::main]
async fn main() -> n0_error::Result<()> {
    let endpoint = Endpoint::bind(presets::N0).await?;
    let router = Router::builder(endpoint).accept(ALPN, Echo).spawn();
    router.shutdown().await?;
    Ok(())
}

Client Connection

From iroh/examples/connect.rs, connecting to a remote endpoint:

use iroh::{Endpoint, endpoint::presets};
const ALPN: &[u8] = b"iroh-example/echo/0";

let endpoint = Endpoint::bind(presets::N0).await?;
let remote_addr = "<REMOTE_ENDPOINT_ADDR>".parse()?;
let conn = endpoint.connect(remote_addr, ALPN).await?;
let (mut send, mut recv) = conn.open_bi().await?;
send.write_all(b"hello").await?;
send.finish()?;

Custom Transport Registration

The custom-transport.rs example demonstrates pluggable transports:

use iroh::{
    Endpoint,
    transport::{Transport, TransportMap},
    endpoint::presets,
};

let mut map = TransportMap::new();
map.insert("my", MyTransport);
let endpoint = Endpoint::builder(presets::N0)
    .transport_map(map)
    .bind()
    .await?;

Key Source Files to Explore

Path	Purpose
iroh/examples/	All runnable demonstration code
iroh/src/endpoint/mod.rs	Endpoint lifecycle and address handling
iroh/src/protocol/mod.rs	Router and ProtocolHandler definitions
iroh/src/transport/	Transport resolution logic
Cargo.toml	Feature flags including tls-aws-lc-rs

Summary

• The n0-computer/iroh repository provides 14+ runnable examples covering QUIC streams, datagrams, NAT traversal, and cryptography.
• Examples demonstrate the three core abstractions: Endpoint (node identity), Router (protocol dispatch), and Connection (stream handling).
• Run examples with cargo run --example <name> --release --all-features.
• Post-quantum examples require the tls-aws-lc-rs feature flag.
• All examples are self-contained and located in iroh/examples/.

Frequently Asked Questions

Where are the Iroh examples located?

All examples reside in the iroh/examples/ directory of the n0-computer/iroh repository. Each .rs file is a standalone binary that can be executed directly with Cargo.

What features do I need to enable for the post-quantum examples?

The post-quantum key exchange examples (pq-only-key-exchange.rs and prefer-pq-key-exchange.rs) require the tls-aws-lc-rs feature. Run these with --all-features to ensure the AWS libcrypto bindings are available.

How do I run the basic echo example?

Execute cargo run --example echo --release from the repository root. The server will print its address, which you can use with cargo run --example connect --release to test the connection.

What is the difference between echo.rs and echo-no-router.rs?

The echo.rs example uses the Router abstraction to handle ALPN-based protocol dispatch, while echo-no-router.rs demonstrates lower-level connection handling without the Router middleware, showing direct endpoint.accept() usage.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}