# How to Configure Proxy Settings in iroh: HTTP(S) Proxy Setup Guide

> Configure proxy settings in iroh easily. Learn to set HTTP(S) proxy via explicit URL or environment variables for seamless network integration in your iroh applications.

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

---

**To configure proxy settings in iroh, set an optional `proxy_url` field on the `Endpoint` builder using `Endpoint::builder().proxy_url(url)` for explicit configuration, or call `proxy_from_env()` to automatically read from the `http_proxy` and `https_proxy` environment variables.**

The iroh networking library from n0-computer supports routing all HTTP(S) traffic through a proxy server. This configuration allows iroh nodes to operate in restricted network environments where direct internet access requires an intermediary proxy.

## Setting the Proxy URL on the Endpoint Builder

The primary configuration interface resides in [`iroh/src/endpoint.rs`](https://github.com/n0-computer/iroh/blob/main/iroh/src/endpoint.rs), where the `Endpoint` struct maintains an optional `proxy_url: Option<Url>` field. You can populate this field through two distinct builder methods before calling `bind()`.

### Explicit Proxy Configuration

Use `proxy_url()` when you know the proxy address at compile time or receive it from application configuration. This method accepts any valid `Url` and stores it for all subsequent relay connections.

```rust
use iroh::endpoint::Endpoint;
use url::Url;

// Configure proxy explicitly
let proxy = Url::parse("http://proxy.example.com:3128").unwrap();
let endpoint = Endpoint::builder()
    .proxy_url(proxy)
    .bind().await?;

```

### Environment-Based Proxy Configuration

For deployments where proxy settings vary by environment, use `proxy_from_env()`. This method checks the `http_proxy` and `https_proxy` environment variables and automatically applies the first valid URL found.

```rust
use iroh::endpoint::Endpoint;

// Load proxy from environment variables
let endpoint = Endpoint::builder()
    .proxy_from_env()
    .bind().await?;

```

The underlying helper `proxy_url_from_env()` implements the lookup logic, prioritizing `https_proxy` when available.

## Proxy Authentication and Connection Schemes

iroh supports **HTTP Basic Authentication** embedded directly in the proxy URL. When the URL contains user-info (e.g., `user:password@`), iroh extracts these credentials and includes them in the `Proxy-Authorization` header during the `CONNECT` handshake.

```rust
use iroh::endpoint::Endpoint;
use url::Url;

// Proxy with basic authentication
let proxy = Url::parse("http://user:password@proxy.example.com:3128").unwrap();
let endpoint = Endpoint::builder()
    .proxy_url(proxy)
    .bind().await?;

```

The implementation respects the URL scheme:
*   **`http`** – Establishes a plain TCP tunnel to the proxy
*   **`https`** – Wraps the proxy connection itself in TLS before issuing the `CONNECT` request

## Internal Proxy Routing Implementation

When `proxy_url` is `Some(...)`, the connection logic switches from direct dialing to the `dial_url_proxy` routine located in [`iroh-relay/src/client/tls.rs`](https://github.com/n0-computer/iroh/blob/main/iroh-relay/src/client/tls.rs). This function creates a TCP stream to the proxy address, performs TLS handshake if needed, and sends an HTTP `CONNECT` request to establish the tunnel.

The proxy URL propagates through the transport stack:
1.  [`iroh/src/endpoint.rs`](https://github.com/n0-computer/iroh/blob/main/iroh/src/endpoint.rs) stores the URL in the `Endpoint` configuration
2.  [`iroh/src/socket/transports/relay/actor.rs`](https://github.com/n0-computer/iroh/blob/main/iroh/src/socket/transports/relay/actor.rs) passes the URL to the relay transport builder via `builder.proxy_url(proxy_url)`
3.  [`iroh-relay/src/client.rs`](https://github.com/n0-computer/iroh/blob/main/iroh-relay/src/client.rs) handles the client-side tunnel establishment, including error handling for invalid URLs and TLS server name verification

If `proxy_url` remains `None`, the client connects directly to the target endpoint, bypassing all proxy logic.

## Summary

*   Configure proxy settings in iroh using `Endpoint::builder().proxy_url(url)` or `proxy_from_env()` before binding
*   The `proxy_url` field in [`iroh/src/endpoint.rs`](https://github.com/n0-computer/iroh/blob/main/iroh/src/endpoint.rs) accepts standard HTTP(S) URLs with optional embedded credentials
*   Environment variables `http_proxy` and `https_proxy` are supported via the `proxy_from_env()` builder method
*   Internal routing uses HTTP `CONNECT` tunneling implemented in [`iroh-relay/src/client/tls.rs`](https://github.com/n0-computer/iroh/blob/main/iroh-relay/src/client/tls.rs) with automatic TLS wrapping for HTTPS proxies
*   Direct connections occur when no proxy URL is configured

## Frequently Asked Questions

### Does iroh support SOCKS5 proxies?

No, the current implementation only supports HTTP(S) proxies using the `CONNECT` method. The proxy handling code in [`iroh-relay/src/client/tls.rs`](https://github.com/n0-computer/iroh/blob/main/iroh-relay/src/client/tls.rs) specifically implements `dial_url_proxy` for HTTP tunneling, not SOCKS protocols.

### Can I configure a proxy without modifying source code?

Yes. Set the `http_proxy` or `https_proxy` environment variable in your deployment environment, then use `Endpoint::builder().proxy_from_env()` when constructing your endpoint. This requires no hardcoded URLs in your application.

### How does iroh handle proxy authentication?

When the proxy URL includes user-info (username and password), iroh automatically extracts these credentials and encodes them into a `Proxy-Authorization` header using Basic authentication. This occurs during the `CONNECT` request phase in the relay client implementation.

### What happens if the proxy URL is invalid?

The `Url::parse()` method will fail during construction if the format is invalid. If a malformed URL somehow reaches the connection layer, [`iroh-relay/src/client.rs`](https://github.com/n0-computer/iroh/blob/main/iroh-relay/src/client.rs) returns an error during the dial phase, preventing the connection from attempting to route through an invalid proxy.