How to Set Up iroh for Local Development

Clone the n0-computer/iroh repository, install Rust ≥1.74 and the protobuf compiler, then run cargo build --workspace --all-features to compile the peer-to-peer QUIC library, relay server, and DNS utilities.

Setting up iroh for local development requires building a Rust workspace that provides a peer-to-peer QUIC library, a relay implementation for hole-punching, and DNS utilities. The repository at n0-computer/iroh contains multiple crates—including iroh (core), iroh-relay, and iroh-dns-server—that you can compile, test, and run locally using standard Cargo commands.

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 protobuf files (sudo apt install protobuf-compiler on Ubuntu/Debian)
• Optional: Nightly Rust for building documentation with the iroh_docsrs configuration (rustup toolchain install nightly)
• Optional: cargo nextest for faster parallel test execution (cargo install cargo-nextest)

Clone and Build the Workspace

Start by cloning the repository and entering the workspace directory:

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

The top-level Cargo.toml defines the workspace containing all crates. Build the entire workspace with default features:

cargo build --workspace

For development, build with all features enabled to access the complete API surface, including unstable components:

cargo build --workspace --all-features

This command compiles the core library (iroh), the relay binary (iroh-relay), and the DNS server binary (iroh-dns-server).

Run the Example Programs

The iroh/examples directory contains practical demonstrations of endpoint creation and stream handling. Run the echo server example to verify your build:

cargo run --example echo

In another terminal, run the client side:

cargo run --example echo-no-router

The echo example in iroh/examples/echo.rs demonstrates the standard pattern for establishing a connection:

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 and exchange data
    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(())
}

As implemented in iroh/src/endpoint/mod.rs, the Endpoint::bind method initializes the QUIC sockets and configures relay interaction.

Run a Local Relay and DNS Server

To test hole-punching and relay functionality locally, run the relay server binary:

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

The relay configuration resides in iroh-relay/src/main.rs and reads defaults from iroh-relay/defaults.rs. To connect a client to your local relay, configure the endpoint builder with a custom RelayUrl:

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

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

For address lookup and DNS resolution, build and run the DNS server:

cargo build -p iroh-dns-server
cargo run -p iroh-dns-server -- --config iroh-dns-server/config.dev.toml --listen 127.0.0.1:53

The DNS server implementation in iroh-dns-server/src/server.rs publishes EndpointId mappings and resolves them via the Pkarr system.

Testing and Documentation

Run the integrated test suite to verify hole-punching and protocol compliance:

# Standard test runner

cargo test --workspace

# Fast parallel runner (requires cargo-nextest)

cargo nextest run --workspace

Generate the complete API documentation locally using nightly Rust to render 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 docs, which mirror the published documentation at docs.rs.

Summary

• Clone the repository from n0-computer/iroh and ensure you have Rust ≥1.74 and protoc installed.
• Build the workspace with cargo build --workspace --all-features to compile all crates including unstable features.
• Run example programs like echo to test endpoint creation and stream handling using the code in iroh/examples/echo.rs.
• Launch a local relay with cargo run -p iroh-relay or a DNS server with cargo run -p iroh-dns-server for development testing.
• Test changes using cargo test --workspace or cargo nextest run, and generate docs with the nightly toolchain and iroh_docsrs cfg.

Frequently Asked Questions

What Rust version is required to build iroh?

You need Rust stable ≥1.74, as specified in the workspace requirements. While the project compiles with stable Rust, building the full documentation requires the nightly toolchain to enable the iroh_docsrs configuration flag.

How do I run the integration tests locally?

Execute cargo test --workspace for the standard test runner, or install cargo-nextest and run cargo nextest run --workspace for faster parallel execution. The integration tests located in iroh/tests/integration.rs verify end-to-end connectivity, hole-punching, and relay behavior.

Can I run a private relay server for development?

Yes. Build the relay binary with cargo build -p iroh-relay and run it with cargo run -p iroh-relay -- --listen 0.0.0.0:4433. Configure your client endpoint to use this local relay by passing the custom RelayUrl to the Endpoint::builder before calling bind(), as shown in the relay client configuration examples.

Where is the public API defined in the source code?

The public API is exported from iroh/src/lib.rs, which re-exports modules from iroh/src/endpoint/mod.rs (connection handling), iroh/src/address_lookup/mod.rs (DNS discovery), and related components. The core Endpoint struct and its builder pattern are implemented in the endpoint module.

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