# How to Configure Iroh to Use Staging Relay Servers: 3 Methods Explained

> Learn 3 easy methods to configure Iroh to use staging relay servers. Update config, use command-line flags, or set env variables for seamless integration with n0-computer/iroh.

- Repository: [number zero/iroh](https://github.com/n0-computer/iroh)
- Tags: how-to-guide
- Published: 2026-06-25

---

**You can configure Iroh to use staging relay servers by updating the `relay` array in your TOML configuration file, passing URLs via the `--relay` command-line flag, or setting the `IROH_RELAY` environment variable.**

Iroh relies on relay servers to route traffic between peers when direct connections fail due to NAT traversal or firewall restrictions. While the client defaults to the production relay network, you often need to configure Iroh to use staging relay servers for safe testing of new features or debugging connectivity issues. The n0-computer/iroh repository provides three distinct configuration paths—config file, CLI flags, and environment variables—that allow you to override the default relay endpoints without recompiling the binary.

## Configuration File Method

The most persistent way to configure staging relays is through the Iroh configuration file. By default, Iroh reads TOML settings from `~/.iroh/config.toml` at startup, or from a custom path specified with the `--config` flag.

In [`iroh/src/config.rs`](https://github.com/n0-computer/iroh/blob/main/iroh/src/config.rs), the `RelayConfig` struct parses the `relay` key as a list of URLs. To point your client at staging infrastructure, add your staging URLs to the `relay` array under the `[client]` table:

```toml

# example.config.toml

[client]
relay = [
    "staging-relay-01.iroh.dev:443",
    "staging-relay-02.iroh.dev:443"
]

```

Iroh attempts to connect to these relays in order, falling back to the next entry if a connection fails. Start the client with your custom configuration using:

```bash
iroh --config /path/to/example.config.toml run

```

The `--config` flag implementation resides in [`iroh/src/main.rs`](https://github.com/n0-computer/iroh/blob/main/iroh/src/main.rs), which passes the file path to the configuration loader before initializing the client.

## Command-Line Override

For temporary testing or CI pipelines, override the configuration file by passing relay URLs directly via the `--relay` flag. This method takes precedence over file-based settings.

In [`iroh/src/cli.rs`](https://github.com/n0-computer/iroh/blob/main/iroh/src/cli.rs), the argument parser accepts a comma-separated list of relay addresses:

```bash
iroh --relay staging-relay-01.iroh.dev:443,staging-relay-02.iroh.dev:443 run

```

This approach is ideal for ad-hoc testing when you cannot modify the configuration file or need to quickly switch between different staging environments without editing persistent storage.

## Environment Variable Method

When scripting automated deployments or running Iroh in containerized environments, set the `IROH_RELAY` environment variable to specify staging endpoints. According to the source code in [`iroh/src/startup.rs`](https://github.com/n0-computer/iroh/blob/main/iroh/src/startup.rs), the client checks this variable as a fallback when no explicit flag or config entry is present.

Export the variable with comma-separated URLs before launching the client:

```bash
export IROH_RELAY="staging-relay-01.iroh.dev:443,staging-relay-02.iroh.dev:443"
iroh run

```

This method ensures that sensitive staging URLs can be injected via secrets management systems without hardcoding them in configuration files or shell history.

## Deploying a Staging Relay Server

To use staging relays, you must first deploy the relay binary to your staging infrastructure. The staging relay binary is identical to the production one; the only difference is the network address it listens on (for example, `staging-relay.iroh.dev:443`).

The relay implementation lives in the `iroh-relay` crate. Build and deployment instructions are documented in [`iroh-relay/README.md`](https://github.com/n0-computer/iroh/blob/main/iroh-relay/README.md), which covers generating TLS certificates, configuring listen addresses, and running the server with debug logging enabled.

## Key Source Code References

- **[`iroh/src/config.rs`](https://github.com/n0-computer/iroh/blob/main/iroh/src/config.rs)**: Defines the `RelayConfig` struct that deserializes the `relay` array from TOML.
- **[`iroh/src/cli.rs`](https://github.com/n0-computer/iroh/blob/main/iroh/src/cli.rs)**: Implements the `--relay` flag parsing and validation.
- **[`iroh/src/main.rs`](https://github.com/n0-computer/iroh/blob/main/iroh/src/main.rs)**: Handles the `--config` flag and initializes the configuration loader.
- **[`iroh/src/startup.rs`](https://github.com/n0-computer/iroh/blob/main/iroh/src/startup.rs)**: Contains the environment variable lookup for `IROH_RELAY`.
- **[`iroh-relay/README.md`](https://github.com/n0-computer/iroh/blob/main/iroh-relay/README.md)**: Provides build instructions for staging relay deployments.
- **[`iroh/docs/relays.md`](https://github.com/n0-computer/iroh/blob/main/iroh/docs/relays.md)**: High-level architectural documentation of the relay network.

## Summary

- **Configuration file**: Modify the `relay` array in [`config.toml`](https://github.com/n0-computer/iroh/blob/main/config.toml) under the `[client]` section for persistent staging settings.
- **Command-line**: Use `--relay url1,url2` for temporary overrides that take precedence over file settings.
- **Environment variable**: Set `IROH_RELAY` for containerized or CI environments where file modification is impractical.
- **Source locations**: The configuration logic is implemented in [`iroh/src/config.rs`](https://github.com/n0-computer/iroh/blob/main/iroh/src/config.rs), [`iroh/src/cli.rs`](https://github.com/n0-computer/iroh/blob/main/iroh/src/cli.rs), and [`iroh/src/startup.rs`](https://github.com/n0-computer/iroh/blob/main/iroh/src/startup.rs).
- **Staging deployment**: Build the relay using the `iroh-relay` crate; the binary is identical to production but listens on different addresses.

## Frequently Asked Questions

### How do I verify that my Iroh client is connected to a staging relay?

Enable debug logging when starting the client to view connection attempts. The client logs indicate which relay URL it successfully connects to during the dialing phase. You can also inspect network traffic to confirm connections are established to your staging domain rather than the default production endpoints.

### Can I configure multiple staging relay servers for redundancy?

Yes. The `relay` configuration field accepts an array of URLs, and Iroh will attempt to connect to them sequentially. If the first staging relay is unreachable, the client automatically falls back to the next entry in the list. This applies to all three configuration methods: TOML arrays, comma-separated CLI values, and comma-separated environment variable strings.

### What is the difference between a staging relay and a production relay in Iroh?

Functionally, there is no difference in the binary itself. Both use the same code from the `iroh-relay` crate. The distinction lies in the deployment environment: staging relays typically run on separate infrastructure with different DNS names (such as `staging-relay.iroh.dev`) and may have different monitoring, logging levels, or experimental features enabled, allowing you to test changes without affecting production traffic.

### Do I need to restart Iroh after changing relay configuration?

Yes. Iroh reads the relay configuration at startup. Changes to the TOML file, environment variables, or command-line arguments only take effect when you restart the client. There is no hot-reload mechanism for relay endpoints in the current implementation, so a full restart is required to switch from production to staging relays.