Iroh Node Configuration Options: Complete Builder API Reference

TLDR: All iroh node configuration is controlled through the Builder struct in iroh/src/endpoint.rs, which provides fluent methods for setting cryptographic keys, ALPN protocols, relay modes, address lookup services, TLS settings, and transport parameters before calling bind().await to instantiate the Endpoint.

The n0-computer/iroh repository implements a peer-to-peer networking stack where every node is represented by the Endpoint type. According to the source code in iroh/src/endpoint.rs, all runtime behavior is decided when the node is built via the Builder struct, which exposes a comprehensive set of configuration options covering cryptography, transport, relay usage, address discovery, and security extensions.

Identity and Protocol Configuration

Every iroh node is identified by a cryptographic keypair and advertises support for specific application protocols via ALPN identifiers.

Node Identity with Secret Keys

The secret_key method sets the node's cryptographic identity. By default, the builder generates a random SecretKey, but you can specify a deterministic key for persistent identity across restarts.

use iroh::endpoint::Builder;

let builder = Builder::empty()
    .secret_key(my_persistent_key);  // iroh/src/endpoint.rs#L524-L527

Application Protocol Negotiation

The alpns method defines which Application-Layer Protocol Negotiation (ALPN) identifiers the node accepts on inbound connections. This controls which protocols the node can speak.

let builder = Builder::empty()
    .alpns(vec![b"iroh/1".to_vec(), b"custom-app/2".to_vec()]);  // iroh/src/endpoint.rs#L529-L537

Network Transport and Relay Configuration

Control how the node creates sockets, uses relay servers, and manages low-level QUIC parameters.

Relay Mode Selection

The relay_mode method determines how the node discovers and uses relay servers for NAT traversal. The RelayMode enum (defined in iroh/src/relay.rs) supports Disabled, Default, Staging, or Custom with a specific RelayMap.

use iroh::relay::RelayMode;

let builder = Builder::empty()
    .relay_mode(RelayMode::Disabled);  // iroh/src/endpoint.rs#L557-L577

Transport Layer Management

The builder maintains a vector of TransportConfig objects in the transports field (iroh/src/endpoint.rs#L443-L447) that drive underlying QUIC socket creation. By default, IPv4 and IPv6 transports are included. Use clear_ip_transports or clear_relay_transports to remove defaults before binding.

let builder = Builder::empty()
    .clear_ip_transports()     // iroh/src/endpoint.rs#L503-L511
    .clear_relay_transports(); // iroh/src/endpoint.rs#L503-L511

For experimental extensions, register custom transport implementations using add_custom_transport (requires the unstable-custom-transports feature) at iroh/src/endpoint.rs#L813-L815.

QUIC Transport Parameters

Pass a pre-configured QuicTransportConfig via transport_config to fine-tune TLS and QUIC socket behavior, including maximum packet sizes and congestion control.

let builder = Builder::empty()
    .transport_config(my_quic_config);  // iroh/src/endpoint.rs#L669-L672

Address Discovery and NAT Traversal

Configure how the node publishes its reachability information and handles network address translation.

Address Lookup Services

Register custom address resolution implementations using address_lookup. The builder stores these as AddressLookupBuilder objects, converting them to AddressLookupServices at bind time. Common options include PKARR DHT or DNS-based discovery.

let builder = Builder::empty()
    .address_lookup(iroh_dns::PkarrResolver::default())  // iroh/src/endpoint.rs#L605-L608
    .user_data_for_address_lookup(my_custom_data);       // iroh/src/endpoint.rs#L639-L642

Address Filtering and Advertisement

Restrict discovered addresses using addr_filter (e.g., restricting to IPv4 only) at iroh/src/endpoint.rs#L617-L620, or advertise additional external addresses via external_addr for complex NAT scenarios at iroh/src/endpoint.rs#L651-L654.

Automatic Port Mapping

Enable UPnP or PMAP for automatic NAT traversal through portmapper_config, defined in iroh/src/portmapper.rs and exposed at iroh/src/endpoint.rs#L786-L788.

Security and TLS Configuration

Customize TLS trust anchors, session handling, and cryptographic providers.

TLS Trust Configuration

Configure how the node validates relay server certificates using ca_tls_config or ca_roots_config. For development environments, use CaTlsConfig::insecure_skip_verify() to bypass verification.

use iroh::tls::CaTlsConfig;

let builder = Builder::empty()
    .ca_tls_config(CaTlsConfig::insecure_skip_verify());  // iroh/src/endpoint.rs#L713-L720

TLS Session Management

Control TLS session resumption with max_tls_tickets (defaulting to DEFAULT_MAX_TLS_TICKETS) at iroh/src/endpoint.rs#L742-L745. Enable debugging via keylog, which writes session keys to the SSLKEYLOGFILE location for Wireshark inspection.

let builder = Builder::empty()
    .max_tls_tickets(10)  // iroh/src/endpoint.rs#L742-L745
    .keylog(true);        // iroh/src/endpoint.rs#L731-L734

Cryptographic Providers

Inject custom rustls crypto implementations using crypto_provider at iroh/src/endpoint.rs#L761-L763.

Proxy and DNS Configuration

Configure outbound connection routing and name resolution.

HTTP Proxy Settings

Force all outbound connections through a specific proxy using proxy_url at iroh/src/endpoint.rs#L690-L692, or automatically detect settings from environment variables (HTTP_PROXY, HTTPS_PROXY) with proxy_from_env at iroh/src/endpoint.rs#L701-L703.

Custom DNS Resolution

On non-Wasm builds, substitute the system resolver using dns_resolver at iroh/src/endpoint.rs#L684-L686.

Debugging and Extension Hooks

Advanced options for monitoring and customizing node behavior.

Endpoint Lifecycle Hooks

Register callback implementations via hooks to execute code during connection establishment and teardown. The EndpointHooks trait receives events during the connection lifecycle.

let builder = Builder::empty()
    .hooks(my_custom_hooks);  // iroh/src/endpoint.rs#L776-L779

Network Reporting

Enable metrics collection and statistics through net_report_config, defined in iroh/src/net_report.rs and exposed at iroh/src/endpoint.rs#L798-L800.

Path Selection

Replace the default path-selection algorithm with a custom implementation using path_selector at iroh/src/endpoint.rs#L840-L842.

Configuration Examples

Minimal Configuration

Create a node with random identity and default settings:

use iroh::endpoint::Builder;

let endpoint = Builder::new(iroh::endpoint::presets::Default)
    .bind()
    .await?;

Production Configuration

Comprehensive setup with custom relay, TLS debugging, address filtering, and cryptographic provider:

use iroh::endpoint::Builder;
use iroh::relay::RelayMode;
use iroh::tls::CaTlsConfig;
use std::net::SocketAddr;

let endpoint = Builder::empty()
    .secret_key(my_secret_key)                                    // iroh/src/endpoint.rs#L524-L527
    .alpns(vec![b"iroh/1".to_vec()])                              // iroh/src/endpoint.rs#L529-L537
    .relay_mode(RelayMode::Custom(my_relay_map))                  // iroh/src/endpoint.rs#L557-L577
    .addr_filter(AddrFilter::Ipv4Only)                           // iroh/src/endpoint.rs#L617-L620
    .external_addr("203.0.113.42:0".parse::<SocketAddr>()?)       // iroh/src/endpoint.rs#L651-L654
    .ca_tls_config(CaTlsConfig::insecure_skip_verify())          // iroh/src/endpoint.rs#L713-L720
    .keylog(true)                                                // iroh/src/endpoint.rs#L731-L734
    .crypto_provider(my_crypto_provider)                          // iroh/src/endpoint.rs#L761-L763
    .bind()
    .await?;

Summary

• Identity and protocols are controlled via secret_key (iroh/src/endpoint.rs#L524-L527) and alpns (iroh/src/endpoint.rs#L529-L537).
• Relay behavior is configured through relay_mode (iroh/src/endpoint.rs#L557-L577), with clear_ip_transports and clear_relay_transports (iroh/src/endpoint.rs#L503-L511) available for custom transport stacks.
• Address discovery uses address_lookup (iroh/src/endpoint.rs#L605-L608) and addr_filter (iroh/src/endpoint.rs#L617-L620), while external_addr (iroh/src/endpoint.rs#L651-L654) helps with NAT traversal.
• TLS settings include ca_tls_config (iroh/src/endpoint.rs#L713-L720), max_tls_tickets (iroh/src/endpoint.rs#L742-L745), and keylog (iroh/src/endpoint.rs#L731-L734).
• Network routing supports proxy_url (iroh/src/endpoint.rs#L690-L692), proxy_from_env (iroh/src/endpoint.rs#L701-L703), and custom dns_resolver (iroh/src/endpoint.rs#L684-L686).
• Extensions like hooks (iroh/src/endpoint.rs#L776-L779), net_report_config (iroh/src/endpoint.rs#L798-L800), and path_selector (iroh/src/endpoint.rs#L840-L842) enable advanced monitoring and customization.

Frequently Asked Questions

How do I completely disable relay servers in iroh?

Call .relay_mode(RelayMode::Disabled) on the builder before binding. This prevents the node from attempting to discover or use relay servers for NAT traversal, as implemented in iroh/src/endpoint.rs#L557-L577.

What is the difference between clear_ip_transports and clear_relay_transports?

clear_ip_transports removes the default IPv4 and IPv6 socket configurations from the internal transports vector, while clear_relay_transports removes relay-specific transport entries. Both are located at iroh/src/endpoint.rs#L503-L511 and allow you to build a completely custom transport stack before bind().

Can I use a custom DNS resolver with an iroh node?

Yes. Use the dns_resolver method on the Builder to inject any implementation compatible with the DNS resolver trait. This option is available for non-Wasm builds at iroh/src/endpoint.rs#L684-L686.

How do I enable TLS debugging for connection issues?

Set .keylog(true) on the builder to enable writing TLS session keys to the SSLKEYLOGFILE environment variable location. This allows packet inspection in tools like Wireshark. See iroh/src/endpoint.rs#L731-L734 for implementation details.

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