How to Set Up iroh for Development: Complete Rust Workspace Guide

To set up iroh for development, clone the n0-computer/iroh repository, install Rust ≥1.74 and the protobuf compiler, then build the workspace with cargo build --workspace --all-features and run examples like cargo run --example echo.

The iroh project provides a peer-to-peer QUIC library, relay implementation, and DNS utilities organized as a Rust workspace. Setting up iroh for development involves building multiple interconnected crates—including iroh, iroh-relay, and iroh-dns-server—from the n0-computer/iroh repository and verifying the installation through the provided example programs and test suites.

Prerequisites

Before building the workspace, ensure your system meets the following requirements:

• Rust toolchain (stable ≥ 1.74): Install via rustup update stable
• Cargo: Included with the Rust toolchain
• Git: Required for cloning the repository
• protobuf compiler (protoc): Needed for generated relay protocol files; install with sudo apt install protobuf-compiler (Linux) or via package manager on macOS
• Optional: Nightly Rust: Required for building documentation with the iroh_docsrs configuration; install with rustup toolchain install nightly
• Optional: cargo nextest: Fast parallel test runner used by CI; install with cargo install cargo-nextest

Clone the Repository and Build

The iroh repository is a Cargo workspace defined in the top-level Cargo.toml, containing crates such as iroh, iroh-relay, iroh-base, and iroh-dns-server.

Clone the repository and build the entire workspace:

git clone https://github.com/n0-computer/iroh.git
cd iroh

# Build with default features

cargo build --workspace

# Build with all Cargo features (recommended for development)

cargo build --workspace --all-features

Building with --all-features enables the full API surface, including unstable features like unstable-net-report and unstable-rustls that are gated behind feature flags in iroh/src/lib.rs and related modules.

Running Examples

The iroh/examples directory contains demonstration programs that verify your development setup. The echo example in iroh/examples/echo.rs provides a minimal client-server implementation:

Run the echo server:

cargo run --example echo

Run the client component in another terminal:

cargo run --example echo-no-router

The core pattern for creating an endpoint and establishing connections follows this structure from iroh/examples/echo.rs:

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

#[tokio::main]
async fn main() -> Result<()> {
    // Bind a local endpoint using the default relay preset
    let ep = Endpoint::bind(presets::N0).await?;
    
    // Connect to a remote endpoint using its address and ALPN
    let conn = ep.connect(remote_addr, b"iroh-example/echo/0").await?;
    
    // Open a bidirectional stream
    let (mut send, mut recv) = conn.open_bi().await?;
    send.write_all(b"Hello, iroh!").await?;
    send.finish()?;
    
    let response = recv.read_to_end(1024).await?;
    println!("Received: {}", String::from_utf8_lossy(&response));
    Ok(())
}

Testing the Workspace

Verify your development setup by running the integration tests located in iroh/tests/integration.rs:

# Standard Cargo test runner

cargo test --workspace

# Faster parallel execution with nextest (requires installation)

cargo nextest run --workspace

For feature-specific testing, pass the feature flag explicitly:

cargo test --workspace --features unstable-net-report

Working with Relays

The iroh-relay crate provides the relay protocol that transports encrypted traffic between endpoints when direct connections fail. The entry point is defined in iroh-relay/src/main.rs.

Run a local relay server for development:

cargo run -p iroh-relay -- --listen 0.0.0.0:4433

Configure a client endpoint to use your local relay by providing a custom RelayUrl via the builder API:

use iroh::{Endpoint, endpoint::Builder, RelayUrl};

let relay = RelayUrl::parse("https://127.0.0.1:4433")?;
let ep = Builder::new().relay(relay).bind().await?;

Generate Local Documentation

Build the complete API documentation matching docs.rs, including all feature-gated items:

RUSTDOCFLAGS="--cfg iroh_docsrs" cargo +nightly doc --workspace --no-deps --all-features

Open target/doc/iroh/index.html in your browser to view the generated documentation, which includes the public API exports from iroh/src/lib.rs and module documentation for iroh/src/endpoint/mod.rs.

Summary

• Install Rust ≥1.74 and protoc before attempting to build the workspace
• Clone the n0-computer/iroh repository and use cargo build --workspace --all-features to compile all crates including iroh, iroh-relay, and iroh-dns-server
• Run examples with cargo run --example <name> to verify connectivity and understand the API patterns in iroh/examples/echo.rs
• Execute tests using cargo test --workspace or cargo nextest run --workspace to ensure the hole-punching and relay functionality works correctly
• Build documentation with nightly Rust and the iroh_docsrs cfg flag to access feature-gated APIs

Frequently Asked Questions

What Rust version is required to build iroh?

You need Rust stable ≥1.74 to compile the iroh workspace. Install or update via rustup update stable. Some documentation builds require nightly Rust for the iroh_docsrs configuration.

How do I run the iroh relay server locally?

Use cargo run -p iroh-relay -- --listen 0.0.0.0:4433 to start a local relay instance. The binary defined in iroh-relay/src/main.rs supports TLS configuration and HTTP-to-QUIC upgrades via the iroh-relay/src/tls.rs module.

What is the purpose of the --all-features flag?

The --all-features flag enables optional Cargo features such as unstable-net-report and unstable-rustls, exposing the complete API surface and documentation. This matches the configuration used for the published crates on docs.rs and is recommended for comprehensive development.

How do I build the API documentation locally?

Run RUSTDOCFLAGS="--cfg iroh_docsrs" cargo +nightly doc --workspace --no-deps --all-features. This command requires nightly Rust and generates documentation in target/doc/ that includes all public modules from iroh/src/lib.rs and feature-gated items.

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