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

> Easily set up iroh for development. Follow our guide to clone the repository, install dependencies, and build the Rust workspace for seamless development.

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

---

**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`](https://github.com/n0-computer/iroh/blob/main/Cargo.toml), containing crates such as `iroh`, `iroh-relay`, `iroh-base`, and `iroh-dns-server`.

Clone the repository and build the entire workspace:

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

Run the echo server:

```bash
cargo run --example echo

```

Run the client component in another terminal:

```bash
cargo run --example echo-no-router

```

The core pattern for creating an endpoint and establishing connections follows this structure from [`iroh/examples/echo.rs`](https://github.com/n0-computer/iroh/blob/main/iroh/examples/echo.rs):

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

```bash

# 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:

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

Run a local relay server for development:

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

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

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

```

Open [`target/doc/iroh/index.html`](https://github.com/n0-computer/iroh/blob/main/target/doc/iroh/index.html) in your browser to view the generated documentation, which includes the public API exports from [`iroh/src/lib.rs`](https://github.com/n0-computer/iroh/blob/main/iroh/src/lib.rs) and module documentation for [`iroh/src/endpoint/mod.rs`](https://github.com/n0-computer/iroh/blob/main/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`](https://github.com/n0-computer/iroh/blob/main/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`](https://github.com/n0-computer/iroh/blob/main/iroh-relay/src/main.rs) supports TLS configuration and HTTP-to-QUIC upgrades via the [`iroh-relay/src/tls.rs`](https://github.com/n0-computer/iroh/blob/main/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`](https://github.com/n0-computer/iroh/blob/main/iroh/src/lib.rs) and feature-gated items.