Understanding iroh Presets: N0, N0DisableRelay, Minimal, and Empty

The iroh networking library provides four built-in Endpoint presets—Empty, Minimal, N0, and N0DisableRelay—that implement the Preset trait to configure Endpoint::Builder with sensible defaults ranging from manual configuration to full public network connectivity.

The n0-computer/iroh crate uses presets to streamline Endpoint configuration for developers building peer-to-peer applications. These presets implement the Preset trait and apply default settings to an Endpoint::Builder, allowing you to choose between complete manual control and ready-to-use configurations optimized for the public Number 0 network.

What Are iroh Presets?

In iroh/src/endpoint/presets.rs, a preset is defined as any type implementing the Preset trait:

pub trait Preset {
    fn apply(self, builder: Builder) -> Builder;
}

When passed to Endpoint::builder(preset), the preset receives the builder, mutates it, and returns the updated instance. This architecture separates configuration logic from endpoint instantiation, enabling composable defaults.

The Four Built-in iroh Presets

The crate ships with four concrete implementations, each serving distinct connectivity requirements from bare-bones to full public network participation.

Empty

The Empty preset performs no configuration. In iroh/src/endpoint/presets.rs (lines 36-43), its apply method returns the builder unchanged:

impl Preset for Empty {
    fn apply(self, builder: Builder) -> Builder {
        builder
    }
}

Use this when you need maximum control over the crypto provider, relay mode, and address lookup services, setting each mandatory option manually.

Minimal

The Minimal preset (requires tls-ring or tls-aws-lc-rs feature) configures only the mandatory TLS crypto provider. According to the source in iroh/src/endpoint/presets.rs (lines 62-79), it automatically selects ring when both TLS features are enabled, otherwise falling back to the available provider. This guarantees a working endpoint without imposing opinions on network discovery or relay usage.

N0

The N0 preset delivers the full "Number 0 defaults" experience. As implemented in iroh/src/endpoint/presets.rs (lines 115-140), it builds on Minimal and adds:

• PKARR publisher via PkarrPublisher::n0_dns()
• Address lookup via PkarrResolver::n0_dns() for WebAssembly browsers or DnsAddressLookup::n0_dns() for native builds
• Default relay mode via default_relay_mode()

This preset is ideal for applications requiring immediate connectivity to iroh's public relay infrastructure and DNS services.

N0DisableRelay

The N0DisableRelay preset inherits all N0 defaults but forces RelayMode::Disabled. In iroh/src/endpoint/presets.rs (lines 177-183), it delegates to N0.apply() then overrides the relay setting:

impl Preset for N0DisableRelay {
    fn apply(self, builder: Builder) -> Builder {
        presets::N0.apply(builder).relay_mode(RelayMode::Disabled)
    }
}

Use this for LAN-only deployments or direct peer-to-peer scenarios where relay servers are unnecessary but you still want PKARR publishing and DNS lookup services.

How to Use iroh Presets in Your Code

Import the presets module and pass your chosen preset to Endpoint::builder():

use iroh::{Endpoint, endpoint::presets};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // Complete manual control
    let ep_empty = Endpoint::builder(presets::Empty)
        .crypto_provider(my_crypto_provider())
        .relay_mode(iroh::RelayMode::Enabled)
        .bind()
        .await?;

    // TLS only, no network defaults
    let ep_minimal = Endpoint::builder(presets::Minimal).bind().await?;

    // Full public network connectivity
    let ep_n0 = Endpoint::builder(presets::N0).bind().await?;

    // Public defaults without relay servers
    let ep_n0_no_relay = Endpoint::builder(presets::N0DisableRelay).bind().await?;

    Ok(())
}

Real-world usage appears in iroh/tests/patchbay/util.rs, where presets::Minimal configures test endpoints without external network dependencies.

Summary

• Empty: Returns the builder unchanged; requires manual configuration of all mandatory fields including crypto provider and relay mode.
• Minimal: Sets the TLS crypto provider automatically; available when tls-ring or tls-aws-lc-rs features are enabled.
• N0: Applies full Number 0 network defaults including PKARR publishing, DNS address lookup, and public relay servers.
• N0DisableRelay: Uses all N0 defaults but forces RelayMode::Disabled for direct peer-to-peer connections.

Frequently Asked Questions

What feature flags are required for iroh presets?

The Minimal, N0, and N0DisableRelay presets require either the tls-ring or tls-aws-lc-rs feature flag to be enabled. These features determine which TLS implementation backs the crypto provider selection logic in iroh/src/endpoint/presets.rs. The Empty preset has no feature requirements.

Can I combine multiple presets or customize them after applying?

Presets mutate the Builder through the apply method, and you can chain additional builder methods after the preset is applied. For example, Endpoint::builder(presets::N0).relay_mode(RelayMode::Custom(...)) overrides the default relay while preserving PKARR and DNS settings.

When should I use N0DisableRelay instead of Empty?

Choose N0DisableRelay when you want the crypto provider, PKARR publishing, and DNS lookup services configured automatically, but need to prohibit relay-assisted connections. Use Empty only when you must configure every component—including the crypto provider and discovery services—manually from scratch.

Where is the Preset trait defined in the iroh source code?

The Preset trait and all four built-in implementations reside in iroh/src/endpoint/presets.rs. The Endpoint::builder() method that consumes these presets is defined in iroh/src/endpoint.rs, which delegates to the preset's apply method to configure the builder.

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