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

> Learn how to run an iroh node locally. Follow our complete development setup guide to build binaries, start a relay server, and launch your node using the n0-computer/iroh repository.

- Repository: [number zero/iroh](https://github.com/n0-computer/iroh)
- Tags: how-to-guide
- Published: 2026-07-04

---

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

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

## Building the Workspace Binaries

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

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

```bash

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

## Configuring the Node

Create a TOML configuration file (e.g., [`local-node.toml`](https://github.com/n0-computer/iroh/blob/main/local-node.toml)) to point your node at the local relay:

```toml

# 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`](https://github.com/n0-computer/iroh/blob/main/iroh-base/src/relay_url.rs). The core node configuration follows the builder pattern exposed in [`iroh/src/lib.rs`](https://github.com/n0-computer/iroh/blob/main/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:

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

```bash

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

```bash

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