# How to Set Up iroh for Local Development

> Set up iroh for local development by cloning the repository, installing Rust and protobuf, then building the peer-to-peer QUIC library, relay server, and DNS utilities with Cargo.

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

---

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

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

```

The top-level [`Cargo.toml`](https://github.com/n0-computer/iroh/blob/main/Cargo.toml) defines the workspace containing all crates. Build the entire workspace with default features:

```bash
cargo build --workspace

```

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

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

```bash
cargo run --example echo

```

In another terminal, run the client side:

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

```

The echo example in [`iroh/examples/echo.rs`](https://github.com/n0-computer/iroh/blob/main/iroh/examples/echo.rs) demonstrates the standard pattern for establishing a connection:

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

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

```

The relay configuration resides in [`iroh-relay/src/main.rs`](https://github.com/n0-computer/iroh/blob/main/iroh-relay/src/main.rs) and reads defaults from [`iroh-relay/defaults.rs`](https://github.com/n0-computer/iroh/blob/main/iroh-relay/defaults.rs). To connect a client to your local relay, configure the endpoint builder with a custom `RelayUrl`:

```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?;

```

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

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

```bash

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

```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 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`](https://github.com/n0-computer/iroh/blob/main/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`](https://github.com/n0-computer/iroh/blob/main/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`](https://github.com/n0-computer/iroh/blob/main/iroh/src/lib.rs), which re-exports modules from [`iroh/src/endpoint/mod.rs`](https://github.com/n0-computer/iroh/blob/main/iroh/src/endpoint/mod.rs) (connection handling), [`iroh/src/address_lookup/mod.rs`](https://github.com/n0-computer/iroh/blob/main/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.