How to Build iroh from Source: Complete Rust Workspace Guide

Clone the n0-computer/iroh repository, install OpenSSL and CMake, then run cargo build --release to compile the workspace. This produces optimized binaries including iroh, iroh-relay, and iroh-dns-server in the target/release/ directory.

iroh is a Rust-based peer-to-peer networking library developed by n0-computer. Building from source requires the Cargo package manager to compile the workspace, which contains the core library and several binary crates located in iroh/src/lib.rs, iroh-relay/src/main.rs, and iroh-dns-server/src/main.rs.

Prerequisites

Before compiling iroh, ensure you have the required system dependencies. The build process requires OpenSSL for optional TLS features and CMake for compiling native C code dependencies like the noq QUIC implementation.

On Debian/Ubuntu systems, install these with:

sudo apt install libssl-dev cmake

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

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

Cloning the Repository

Clone the official repository and enter the workspace directory:

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

The workspace manifest is located at Cargo.toml in the repository root, defining all members including iroh, iroh-relay, iroh-base, and iroh-dns-server.

Building the Workspace

Development Builds

For development and debugging, compile debug artifacts for all workspace members:

cargo build

This creates unoptimized binaries in target/debug/.

Production-Ready Binaries

To create optimized release binaries:

cargo build --release --workspace

This produces executables in target/release/:

• 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 iroh binary to ~/.cargo/bin for system-wide access:

cargo install --path .

Building Individual Components

You can compile specific crates independently using the -p flag.

Compiling the Relay Server

The relay server source is located at iroh-relay/src/main.rs. Build it separately with:

cargo build -p iroh-relay --release

Compiling the DNS Server

The DNS server, which resolves EndpointId-based names like dns.iroh.link, resides in iroh-dns-server/src/main.rs. Build it with:

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

Cross-Compilation

For non-native targets, the CI pipeline uses cross. Install it and specify a target triple:

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

Running the Echo Example

The repository includes an echo protocol demonstrating the core API. The implementation is in examples/echo.rs. After building the workspace, run:

cargo run --example echo

This example starts a server and client, opens a QUIC stream, echoes data, and closes the connection.

Using the Core Library

When building applications that depend on iroh, reference the core library from iroh/src/lib.rs. Here is a minimal client example:

// 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

• iroh is a Rust workspace requiring Cargo to build from source according to the n0-computer/iroh repository structure
• Install system dependencies: OpenSSL (libssl-dev) and CMake before compiling
• Use cargo build --release to compile all binaries to target/release/
• Build individual components with -p iroh-relay or -p iroh-dns-server
• Key source files include iroh/src/lib.rs, iroh-relay/src/main.rs, and iroh-dns-server/src/main.rs
• Run the echo example with cargo run --example echo to verify the build

Frequently Asked Questions

What Rust version is required to build iroh?

iroh requires the stable Rust channel. The project tracks the latest stable releases, so ensure you have an up-to-date toolchain by running rustup update before building.

Can I build iroh without OpenSSL?

While the core library may compile, OpenSSL is required for TLS features used by the relay and DNS server components. Install libssl-dev on Debian/Ubuntu or the equivalent package for your operating system to ensure full functionality.

Where are the compiled binaries located?

Debug builds appear in target/debug/, while release builds are placed in target/release/. When running cargo install --path ., the binaries are copied to ~/.cargo/bin/ (or your system's equivalent Cargo bin directory).

How do I build only the iroh client binary without the relay server?

Use the -p flag to specify the package: cargo build -p iroh --release. This compiles only the core library and associated binary, skipping the relay and DNS server crates.

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