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

> Explore the n0-computer/iroh repository for 14+ production-ready Iroh examples. Discover QUIC echo servers, PQC key exchange, and custom transport implementations.

- Repository: [number zero/iroh](https://github.com/n0-computer/iroh)
- Tags: getting-started
- Published: 2026-07-06

---

**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`](https://github.com/n0-computer/iroh/blob/main/iroh/examples/listen.rs), binding works as follows:

```rust
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`](https://github.com/n0-computer/iroh/blob/main/echo.rs) example shows registration:

```rust
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`](https://github.com/n0-computer/iroh/blob/main/iroh/examples/echo.rs):

```rust
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:

```bash
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`](https://github.com/n0-computer/iroh/blob/main/iroh/examples/echo.rs) shows the minimal implementation:

```rust
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`](https://github.com/n0-computer/iroh/blob/main/iroh/examples/connect.rs), connecting to a remote endpoint:

```rust
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`](https://github.com/n0-computer/iroh/blob/main/custom-transport.rs) example demonstrates pluggable transports:

```rust
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`](https://github.com/n0-computer/iroh/blob/main/iroh/src/endpoint/mod.rs) | Endpoint lifecycle and address handling |
| [`iroh/src/protocol/mod.rs`](https://github.com/n0-computer/iroh/blob/main/iroh/src/protocol/mod.rs) | Router and ProtocolHandler definitions |
| `iroh/src/transport/` | Transport resolution logic |
| [`Cargo.toml`](https://github.com/n0-computer/iroh/blob/main/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`](https://github.com/n0-computer/iroh/blob/main/pq-only-key-exchange.rs) and [`prefer-pq-key-exchange.rs`](https://github.com/n0-computer/iroh/blob/main/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`](https://github.com/n0-computer/iroh/blob/main/echo.rs) example uses the **Router** abstraction to handle ALPN-based protocol dispatch, while [`echo-no-router.rs`](https://github.com/n0-computer/iroh/blob/main/echo-no-router.rs) demonstrates lower-level connection handling without the Router middleware, showing direct `endpoint.accept()` usage.