# Iroh Node Configuration Options: Complete Builder API Reference

> Explore the comprehensive iroh node configuration options using the Builder API in iroh/src/endpoint.rs. Master keys, ALPN, relays, TLS, and more for optimal node setup.

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

---

**TLDR:** All iroh node configuration is controlled through the `Builder` struct in [`iroh/src/endpoint.rs`](https://github.com/n0-computer/iroh/blob/main/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`](https://github.com/n0-computer/iroh/blob/main/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.

```rust
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.

```rust
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`](https://github.com/n0-computer/iroh/blob/main/iroh/src/relay.rs)) supports `Disabled`, `Default`, `Staging`, or `Custom` with a specific `RelayMap`.

```rust
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.

```rust
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.

```rust
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.

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

```rust
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.

```rust
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.

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

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

```rust
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.