# RelayMode Default vs Disabled vs Custom in iroh: Endpoint Connection Modes Explained

> Understand iroh's RelayMode Default NoRelay and Custom. Learn how to configure endpoint connection modes for NAT traversal and direct peer-to-peer connections.

- Repository: [number zero/iroh](https://github.com/n0-computer/iroh)
- Tags: deep-dive
- Published: 2026-06-24

---

**`RelayMode::Default`** uses iroh's built-in production relays for NAT traversal, **`RelayMode::Disabled`** (sometimes referred to as "NoRelay") blocks all relay traffic to enforce direct peer-to-peer connections only, and **`RelayMode::Custom`** accepts an explicit `RelayMap` for private relay infrastructure.

The `RelayMode` enum in the [n0-computer/iroh](https://github.com/n0-computer/iroh) repository controls how an `Endpoint` discovers and utilizes relay servers during connection establishment. Defined in [[`iroh/src/endpoint.rs`](https://github.com/n0-computer/iroh/blob/main/iroh/src/endpoint.rs)](https://github.com/n0-computer/iroh/blob/main/iroh/src/endpoint.rs), this configuration determines whether your application relies on public relay servers, operates without relay assistance, or connects to specific self-hosted relays.

## RelayMode::Default: Production Relay Infrastructure

**`RelayMode::Default`** configures the endpoint to use the production relay map embedded in the library. According to the source code at [line 1929](https://github.com/n0-computer/iroh/blob/main/iroh/src/endpoint.rs#L1929-L1932), this variant invokes `crate::defaults::prod::default_relay_map()` to retrieve the list of public relays operated by the iroh team.

Use this mode for general internet-facing applications where you require reliable, globally-available relays without manual configuration. When direct hole-punching fails due to restrictive NATs or firewalls, the endpoint automatically falls back to these production relays to maintain connectivity.

## RelayMode::Disabled: Direct-Only Communication

**`RelayMode::Disabled`** disables all relay functionality entirely. As implemented in the [source branch at lines 1929-1930](https://github.com/n0-computer/iroh/blob/main/iroh/src/endpoint.rs#L1929-L1930), the endpoint will never attempt to hole-punch or forward traffic through relay servers. All connection attempts must succeed via direct peer-to-peer paths or fail immediately.

Select this mode when operating in trusted, fully reachable networks such as internal LANs or VPNs where you want to eliminate relay traffic entirely. This configuration is also available via the presets module in [[`iroh/src/endpoint/presets.rs`](https://github.com/n0-computer/iroh/blob/main/iroh/src/endpoint/presets.rs)](https://github.com/n0-computer/iroh/blob/main/iroh/src/endpoint/presets.rs) for quick "no relay" endpoint setup.

## RelayMode::Custom: Private Relay Deployments

**`RelayMode::Custom(RelayMap)`** accepts an explicit relay map containing your own relay URLs. The variant definition at [lines 1922-1924](https://github.com/n0-computer/iroh/blob/main/iroh/src/endpoint.rs#L1922-L1924) wraps a user-provided `RelayMap`, and the helper constructor `RelayMode::custom()` ([lines 51-53](https://github.com/n0-computer/iroh/blob/main/iroh/src/endpoint.rs#L51-L53)) simplifies construction from any iterator of URLs.

This mode is essential for private deployments, corporate environments with specific firewall requirements, or edge-located relays. Unlike `Default`, which pulls from `iroh/defaults/prod`, `Custom` uses exactly the relays you specify via the `RelayUrl` type defined in [[`iroh-base/src/relay_url.rs`](https://github.com/n0-computer/iroh/blob/main/iroh-base/src/relay_url.rs)](https://github.com/n0-computer/iroh/blob/main/iroh-base/src/relay_url.rs).

## Key Differences in Network Behavior

The three modes differ fundamentally in their source of relay URLs and fallback behavior:

- **Source of URLs** – `Default` pulls the built-in production list; `Custom` uses your provided list; `Disabled` uses none.
- **Connection Resilience** – With `Default` or `Custom`, the endpoint can fall back to relays when direct paths fail. With `Disabled`, connection failures are terminal.
- **Configuration Complexity** – `Default` requires no additional code; `Custom` requires building a `RelayMap`; `Disabled` is a single variant value.

## Configuring Your Endpoint: Code Examples

The following patterns from [[`iroh/examples/listen.rs`](https://github.com/n0-computer/iroh/blob/main/iroh/examples/listen.rs)](https://github.com/n0-computer/iroh/blob/main/iroh/examples/listen.rs#L31) demonstrate practical usage of each relay mode:

```rust
use iroh::{Endpoint, RelayMode};

fn main() -> anyhow::Result<()> {
    // Default: Use production relays shipped with iroh
    let endpoint_default = Endpoint::builder()
        .relay_mode(RelayMode::Default)
        .bind()?;
    
    // Disabled (No Relay): Direct connections only
    let endpoint_disabled = Endpoint::builder()
        .relay_mode(RelayMode::Disabled)
        .bind()?;
    
    // Custom: Specific private relay servers
    let custom_map = iroh::RelayMap::from_iter([
        "https://relay1.example.com/".parse()?,
        "https://relay2.example.com/".parse()?,
    ]);
    let endpoint_custom = Endpoint::builder()
        .relay_mode(RelayMode::Custom(custom_map))
        .bind()?;
    
    Ok(())
}

```

For convenience, the `RelayMode::custom()` helper (lowercase) automatically wraps your URLs into a `RelayMap`, while the `RelayMode::Custom` variant (uppercase) accepts a pre-constructed map directly.

## Summary

- **`RelayMode::Default`** leverages the built-in production relay map (`defaults::prod`) for automatic NAT traversal without configuration.
- **`RelayMode::Disabled`** eliminates all relay functionality, requiring successful direct peer-to-peer paths or failing the connection.
- **`RelayMode::Custom`** requires a manually constructed `RelayMap` for complete control over relay server selection in private networks.

## Frequently Asked Questions

### What is the difference between RelayMode::Disabled and NoRelay?

`RelayMode::Disabled` is the actual enum variant name in [[`iroh/src/endpoint.rs`](https://github.com/n0-computer/iroh/blob/main/iroh/src/endpoint.rs)](https://github.com/n0-computer/iroh/blob/main/iroh/src/endpoint.rs), while "NoRelay" is the conceptual description used in documentation and the `presets` module. Both refer to the same behavior: completely disabling relay assistance and forcing direct connections only.

### When should I use RelayMode::Custom instead of Default?

Use **RelayMode::Custom** when operating in restricted network environments, testing self-hosted relay infrastructure, or deploying within corporate networks that block external relay endpoints. **RelayMode::Default** is preferable for general applications requiring the global availability of iroh's public relay fleet without configuration overhead.

### How does RelayMode affect connection establishment?

**RelayMode::Disabled** attempts only direct connections, failing fast when peers are unreachable. **RelayMode::Default** and **RelayMode::Custom** may increase initial connection latency while attempting UDP hole-punching, but ultimately succeed by falling back to relay servers when direct paths fail.

### Can I change RelayMode on an existing Endpoint?

No. The `RelayMode` is fixed during `Endpoint` construction via the builder pattern and cannot be modified dynamically. To alter relay behavior, you must create a new `Endpoint` instance with the desired configuration using `Endpoint::builder()`.