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

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, 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.

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.

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.

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. 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 stores the URL in the Endpoint configuration
2. 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 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 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 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 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 returns an error during the dial phase, preventing the connection from attempting to route through an invalid proxy.

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