How to Build iroh from Source: Complete Guide to Compiling the Rust Networking Stack

To build iroh from source, install the Rust toolchain, clone the n0-computer/iroh repository, and run cargo build --release --workspace to compile the core library and binary crates including the relay server and DNS server.

The iroh project is a Rust workspace that implements public-key dialing, QUIC transport, and high-level networking APIs. Whether you are developing applications with the core library or deploying infrastructure components, building iroh from source provides access to the latest features in the n0-computer/iroh repository.

Prerequisites

Before compiling iroh, ensure your system has the required dependencies. The build process requires OpenSSL development libraries and CMake for compiling native code dependencies like the QUIC implementation.

On Debian or Ubuntu systems, install the required packages:

sudo apt update
sudo apt install libssl-dev cmake

You also need the Rust toolchain. Install it using rustup:

curl https://sh.rustup.rs -sSf | sh -s -- -y
source $HOME/.cargo/env

Understanding the Workspace Structure

The iroh repository is organized as a Cargo workspace defined in the root Cargo.toml. The workspace contains multiple crates that share a unified dependency graph.

Key components include:

• iroh – The core library implementing the public-key dialing and QUIC transport API (iroh/src/lib.rs)
• iroh-relay – Relay client and server for the public relay network (iroh-relay/src/main.rs)
• iroh-dns-server – DNS server resolving EndpointId-based names (iroh-dns-server/src/main.rs)
• iroh-base – Shared types like EndpointId and RelayUrl (iroh-base/src/lib.rs)

Building the Complete Workspace

To compile all crates in the workspace, clone the repository and run the build command.

First, clone the source:

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

For development builds with debug symbols:

cargo build

For optimized, production-ready binaries:

cargo build --release --workspace

The release command generates optimized binaries in target/release/, including:

• target/release/iroh – Main command-line client
• target/release/iroh-relay – Relay server executable
• target/release/iroh-dns-server – DNS server executable

Installing the Client Binary

To install the main iroh binary to your Cargo bin directory (~/.cargo/bin), use:

cargo install --path .

This makes the iroh command available in your PATH, assuming ~/.cargo/bin is in your environment.

Building Specific Components

When you only need individual components rather than the entire workspace, target specific packages with the -p flag.

To build only the relay server:

cargo build -p iroh-relay --release

To build only the DNS server:

cargo build -p iroh-dns-server --release

This approach reduces compile times when you do not need the complete suite of tools.

Cross-Compilation

The iroh CI pipeline uses cross for building non-native targets. To cross-compile for platforms like ARM64 Linux, first install the tool:

cargo install cross

Then specify the target triple and package:

cross build --release --target aarch64-unknown-linux-gnu -p iroh-relay

This produces an ARM64 binary without requiring a local ARM toolchain.

Running the Echo Example

The repository includes an example demonstrating the core API. Located at examples/echo.rs, this program starts a server and client, opens a QUIC stream, and echoes data between them.

After building the workspace, run the example:

cargo run --example echo

The example code showcases how to use the iroh library to establish connections:

// Minimal client using the iroh core library
use iroh::{Endpoint, Router, ProtocolHandler, Connection};
use std::sync::Arc;

const ALPN: &[u8] = b"iroh-example/echo/0";

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // Bind a local endpoint
    let endpoint = Endpoint::bind().await?;

    // Connect to a remote peer (replace with a real address)
    let conn = endpoint.connect("127.0.0.1:9999".parse()?, ALPN).await?;

    // Open a bidirectional QUIC stream
    let (mut send, mut recv) = conn.open_bi().await?;

    // Send a message and read the echo
    send.write_all(b"Hello, iroh!").await?;
    send.finish()?;
    let response = recv.read_to_end(1024).await?;
    assert_eq!(response, b"Hello, iroh!");

    // Close everything cleanly
    conn.close(0u32.into(), b"bye!");
    endpoint.close().await;
    Ok(())
}

Summary

Building iroh from source requires the Rust toolchain and standard development dependencies. Key takeaways include:

• Run cargo build --release --workspace to compile all binaries including iroh, iroh-relay, and iroh-dns-server
• Use cargo install --path . to add the iroh client to your local Cargo bin directory
• Target individual crates with -p iroh-relay or -p iroh-dns-server to reduce build times
• Install libssl-dev and cmake before building to satisfy native dependencies
• Execute cargo run --example echo to verify your build and explore the API

Frequently Asked Questions

What version of Rust is required to build iroh?

Iroh requires the Rust stable channel. The project maintains compatibility with recent stable releases, and you should ensure your toolchain is up to date by running rustup update before building from source.

How do I build only the iroh relay server without the other components?

Use the package-specific build flag: cargo build -p iroh-relay --release. This compiles only the iroh-relay crate and its dependencies, producing the binary at target/release/iroh-relay without building the DNS server or other workspace members.

Where are the compiled binaries located after building iroh from source?

Debug builds place binaries in target/debug/, while release builds place them in target/release/. The main client binary appears as target/release/iroh, with additional executables for iroh-relay and iroh-dns-server in the same directory.

Can I build iroh without OpenSSL?

OpenSSL is required for optional TLS features within the codebase. While you may be able to compile certain crates without it, a full build of the workspace including networking components requires the OpenSSL development libraries (libssl-dev on Debian/Ubuntu) to be present on your system.

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