Relays

Relays are servers that temporarily route encrypted traffic until a direct, P2P connection is feasible. Once this direct path is set up, the relay server steps back, and the data flows directly between devices. This approach allows Iroh to maintain a secure, low-latency connection, even in challenging network situations. There are situations where a direct connection can’t be established, and in those cases traffic falls back to running through the relay. Relay servers do not have access to the data being transmitted, as it’s encrypted end-to-end. Relays serve two roles in iroh:

1. NAT Traversal. When two endpoints first connect, they exchange network information through the relay to attempt a direct P2P connection.
2. Encrypted traffic fallback. If a direct connection can’t be established (due to strict NATs, firewalls, or other network conditions), traffic flows through the relay instead.

Once a direct path is established, the relay steps back and data flows peer-to-peer. Relay servers cannot read any of the traffic they handle; it’s encrypted end-to-end. In practice, roughly 9 out of 10 networking conditions allow a direct connection. iroh’s NAT traversal implementation is deterministic: if it works between two devices once, it will continue to work as long as their networking setup stays stable.

​

Deploy your own relay

​

Why relays are better

Unlike traditional servers, relay servers are stateless. They don’t store your application data; they just facilitate connections.

• No database synchronization. Nothing to replicate across relay instances.
• No state migration. When a relay goes down, clients reconnect to another with no data loss.
• Simple scaling. Spin relay instances up or down like any lightweight service.
• Automatic failover. Iroh can attempt to connect to multiple relays automatically; as long as one is reachable, your peers find each other.

This inverts the traditional model: relays are disposable connection facilitators, while your clients own all the application state and logic.

​

Public relays

Iroh hardcodes a set of public relays provided by n0.computer, free to use. Public relays:

• Rate-limit traffic to prevent abuse
• Carry no uptime or performance guarantees
• Are shared across all iroh developers worldwide

Public relays are suitable for development and testing. For production, use dedicated relays.

​

Dedicated relays

Dedicated relays are relay servers provisioned exclusively for your project, either managed through Iroh Services or self-hosted. They offer:

• Authenticated by default: only your project’s endpoints can connect, authenticated automatically with your API key. You can turn authentication off from the dashboard if you want any endpoint that has the URL to be able to use it.
• Isolation: no noisy neighbors; your traffic is yours alone
• Uptime guarantees: SLAs available via Iroh Services
• Version locking: stay on a specific iroh version or run blue/green deployments
• Multi-region & multi-cloud: deploy relays across regions and providers for resilience

​

Authentication

Dedicated relays require authentication by default, so a relay only carries traffic for endpoints that belong to your project. Authentication is built in — there’s nothing extra to wire up beyond your API key. Here’s how it works:

1. Your relay knows your project. When Iroh Services provisions a relay, it tells the relay which of your project’s API keys are allowed to use it. This allow-set is kept in sync as you create or revoke keys.
2. Your endpoint presents a token, not the key itself. When you build an endpoint with the iroh_services::preset() builder and your API key, the SDK mints a short-lived, signed access token scoped to that endpoint’s identity. The endpoint presents this token when it connects to the relay. Your API key never leaves your application.
3. The relay verifies and admits. The relay checks that the token was signed by one of your project’s allowed keys and hasn’t expired, then admits the connection. An endpoint with no token, an expired token, or a token from a revoked key is refused at the handshake.

A few things worth knowing:

• Revocation is live. Delete an API key and its access is withdrawn from your relays right away, including connections that are already open. The relay will kick off clients using that key, and they won’t be able to reconnect until they have a valid token again.
• Authentication is a toggle, not a different relay. Turning authentication off from the dashboard tells the relay to admit any endpoint without a token. Turn it back on and the token check resumes for new connections. See Turn authentication off.
• Turning authentication off doesn’t make a relay discoverable. Your relay is never listed or advertised anywhere. With authentication off, any endpoint that already knows the relay’s URL can use it, but it still has to know the URL.
• Authentication is about access, not privacy. All relay traffic is end-to-end encrypted regardless. Authentication controls who may use your relay; it doesn’t change what the relay can see (it still can’t read your traffic).

Self-hosted relays you run outside of Iroh Services manage their own access, so this is handled for you only on managed relays. See API Keys for where your key comes from.

​

Deploy your own relay

Or self-host using the open-source relay binary:

• Relay source code
• Relay binary releases
• Dedicated infrastructure guide