How to Run an iroh Node Locally: Complete Development Setup Guide

To run an iroh node locally, build the workspace binaries from the n0-computer/iroh repository, start a local relay server with the --dev flag, and launch the node with a configuration file pointing to your local relay URL.

The iroh library provides a Rust-based peer-to-peer networking stack built on QUIC, enabling direct device connections even across NATs. Running an iroh node locally is essential for development, testing, and experimentation before deploying to production. This guide covers the exact steps to compile from source, configure the necessary relay infrastructure, and start your node using commands and configuration options defined in the official codebase.

Prerequisites

Before you begin, ensure your environment meets the following requirements:

• Rust toolchain (version 1.73 or newer) with Cargo installed
• Git for cloning the repository
• A Unix-like environment or Windows with appropriate build tools

Clone the repository and enter the workspace:

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

The repository is organized as a Cargo workspace containing multiple crates. The two primary components for local development are the iroh crate (core library) and the iroh-relay crate (relay server), as listed in the workspace members defined in the root README.md.

Building the Workspace Binaries

Compile all necessary binaries using Cargo's workspace flag. From the repository root, run:

cargo build --workspace

This command produces two essential debug binaries in target/debug/:

• iroh – The main node binary exposing the CLI interface
• iroh-relay – The relay server that facilitates peer discovery

For system-wide installation, alternatively use cargo install --path . after building.

Starting the Local Relay Server

The relay server is required for nodes to discover each other when operating behind NATs. The iroh codebase includes a development mode that disables TLS for simplified local testing.

Generate a configuration file and start the relay in development mode:

# Generate config (run once)

cargo run --features="server" --bin iroh-relay -- --config-path=./local-relay.toml --dev

# Start the relay

cargo run --features="server" --bin iroh-relay -- --config-path=./local-relay.toml --dev

The --dev flag disables TLS encryption, binding to port 3340 for HTTP and port 3478 UDP for QUIC discovery. The configuration structure and command-line options are defined in iroh-relay/src/server.rs, which contains the Config struct handling TOML parsing. Detailed relay setup instructions are also documented in iroh/docs/local_relays.md.

Configuring the Node

Create a TOML configuration file (e.g., local-node.toml) to point your node at the local relay:

# local-node.toml

relay_url = "http://127.0.0.1:3340"

# Optional: Persist identity between restarts

# secret_key_path = "node.key"

The relay_url field accepts standard HTTP URLs as defined in iroh-base/src/relay_url.rs. The core node configuration follows the builder pattern exposed in iroh/src/lib.rs, where the Endpoint::builder API processes these settings. The iroh crate's README provides additional context on available configuration parameters for the Endpoint builder.

Launching the iroh Node

With the relay running and configuration file created, start your local node:

cargo run --bin iroh -- --config-path=./local-node.toml

Upon successful startup, the console displays log entries confirming the node status:

2026-07-04T12:34:56.789Z INFO  iroh > node started
2026-07-04T12:34:56.790Z INFO  iroh > using relay http://127.0.0.1:3340

The node is now operational and registered with your local relay.

Testing Connectivity

Verify your local setup using the bundled echo example or CLI commands.

Echo Protocol Test:

In separate terminals, run:

# Terminal 1: Start listener

cargo run --example echo -- --listen

# Terminal 2: Connect using the displayed public key

cargo run --example echo -- --connect <LISTENER_PUBLIC_KEY>

This example utilizes the Endpoint API demonstrated in the repository's README.

CLI Inspection:

The iroh binary provides subcommands implemented in iroh/src/bin/iroh.rs:

# List active connections and peer IDs

iroh node connections

# Display node's public key and network addresses

iroh node info

Production Considerations

When moving beyond local development, omit the --dev flag when starting the relay and provide a [tls] section in your relay configuration for certificate management. Enable persistent storage by uncommenting secret_key_path in your node configuration to maintain identity across restarts. Additional production settings for bandwidth limits and protocol extensions are documented in the iroh-base crate.

Summary

• Build the workspace with cargo build --workspace to generate iroh and iroh-relay binaries
• Start the local relay using --dev mode on ports 3340 (HTTP) and 3478 (UDP)
• Configure your node with a TOML file specifying relay_url = "http://127.0.0.1:3340"
• Launch the node binary pointing to your configuration file
• Verify functionality using iroh node connections or the echo example

Frequently Asked Questions

Do I need to run a relay server to run iroh node locally?

Yes, for local development you should run the iroh-relay binary alongside your node. The relay facilitates NAT hole punching and peer discovery. While direct connections are possible on local networks, the relay ensures consistent behavior matching production deployments. Run it in --dev mode to disable TLS requirements during testing.

What ports does the iroh relay use by default?

The relay server binds to port 3340 for HTTP signaling traffic and port 3478 for UDP-based QUIC discovery. These ports are defined in the default configuration generated when running the relay with the --dev flag. You can customize these via the configuration file located in iroh-relay/src/server.rs.

How do I persist my node's identity between restarts?

Add the secret_key_path field to your node configuration TOML file, specifying a file path where the node should store its cryptographic identity. Without this setting, the node generates a new ephemeral key on each startup, changing its public node ID and requiring updates to any hardcoded peer addresses in your test environment.

Can I run multiple iroh nodes on the same machine?

Yes, you can run multiple nodes locally by creating separate configuration files for each instance with distinct secret_key_path values. Each node should reference the same local relay URL. Use different terminal sessions or background processes to manage multiple nodes simultaneously for testing P2P connectivity.

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