Ruby Proxy Configuration Examples

This page explains Ruby proxy configuration for HTTP clients through ProxyMesh: pick a library, set a proxy URL, and use credentials or IP authentication.

For basic proxy routing only: set the client's proxy URL (and credentials or IP authentication). Custom headers (for example X-ProxyMesh-Country, X-ProxyMesh-IP) on HTTPS need the ruby-proxy-headers gem (Ruby 3.1+)—see custom proxy headers.

See basic-proxy scripts per library in proxy-examples (Ruby). Those scripts do not use ruby-proxy-headers.

Background: HTTP proxy overview, proxy headers, and HTTPS and CONNECT.

Proxy URL and authentication

Use an http:// proxy URL for both HTTP and HTTPS targets. With username/password auth:

proxy_url = 'http://USERNAME:PASSWORD@PROXYHOST:31280'

With IP authentication, omit USERNAME:PASSWORD@. Many tools honor HTTP_PROXY / HTTPS_PROXY:

export HTTPS_PROXY="http://USERNAME:PASSWORD@PROXYHOST:31280"

Ruby HTTP clients at a glance

Use this table to choose a client and see if ruby-proxy-headers can send or read ProxyMesh headers on HTTPS CONNECT. Examples include Faraday proxy setup, Net HTTP proxy configuration, HTTParty proxy options, Excon proxy usage, rest-client proxy configuration, Typhoeus proxy integration, and custom CONNECT proxy headers. See per-library guides on Ruby proxy devdocs.

Client	Proxy setup	CONNECT headers	Example · guide
Net::HTTP	`Net::HTTP.new(host, port, proxy_host, proxy_port, user, pass)`	Send and read via `NetHTTP.patch!`	net-http-proxy.rb Net::HTTP guide
Faraday	`Faraday.new(proxy: proxy_url)`	Send and read via `FaradayIntegration`	faraday-proxy.rb Faraday guide
HTTParty	`http_proxyaddr`, `http_proxyport`, user, pass	Send and read via patched Net::HTTP adapter	httparty-proxy.rb HTTParty guide
Excon	`Excon.get(url, proxy: proxy_url)`	Send only via `ExconIntegration`; cannot read CONNECT response headers	excon-proxy.rb Excon guide
HTTP.rb	`HTTP.via(host, port, user, pass)`	`RubyProxyHeaders::HTTPGem` (Net::HTTP-backed)	http-rb-proxy.rb HTTP.rb guide
Typhoeus	`Typhoeus::Request.new(url, proxy: proxy_url)`	`RubyProxyHeaders::Typhoeus` when needed (no libcurl CONNECT headers)	typhoeus-proxy.rb Typhoeus guide
RestClient	`RestClient.proxy = proxy_url`	`RubyProxyHeaders::RestClient` when `proxy_headers` set on HTTPS	rest-client-proxy.rb RestClient guide
HTTPClient	`HTTPClient.new(proxy_url)`	Basic proxy only; use Net::HTTP or Faraday for custom headers	httpclient-proxy.rb HTTPClient guide
Mechanize	`agent.set_proxy(host, port, user, pass)`	Basic proxy only	mechanize-proxy.rb Mechanize guide
Nokogiri	Parse HTML/XML from a response fetched with another client	Use Net::HTTP or Faraday for the fetch when headers matter	nokogiri-proxy.rb Nokogiri guide

Basic proxy (no custom headers)

These examples route only traffic through the proxy. The examples do not set X-ProxyMesh-* on CONNECT. For country or sticky IP headers on HTTPS, use the custom proxy headers section.

Faraday

Library: Faraday. Proxy: Faraday.new(proxy: proxy_url). See also faraday-proxy.rb in proxy-examples.

require 'faraday'

proxy_url = 'http://USERNAME:PASSWORD@PROXYHOST:31280'

conn = Faraday.new(proxy: proxy_url) do |f|
  f.adapter Faraday.default_adapter
end

response = conn.get('https://api.ipify.org?format=json')
puts response.body

Net::HTTP

Library: Net::HTTP (stdlib). Proxy: proxy host, port, user, and password on Net::HTTP.new. See also net-http-proxy.rb in proxy-examples.

require 'net/http'
require 'openssl'
require 'uri'

proxy = URI('http://USERNAME:PASSWORD@PROXYHOST:31280')
uri = URI('https://api.ipify.org?format=json')

http = Net::HTTP.new(uri.host, uri.port, proxy.host, proxy.port, proxy.user, proxy.password)
http.use_ssl = true

response = http.request(Net::HTTP::Get.new(uri))
puts response.body

Custom proxy headers (ruby-proxy-headers)

On plain HTTP, set ProxyMesh headers as with any request header.

On HTTPS, the client sends a proxy CONNECT first. Put custom headers on that CONNECT request. The CONNECT response returns values such as X-ProxyMesh-IP (see proxy headers).

gem install ruby-proxy-headers

Or add gem 'ruby-proxy-headers' to your Gemfile. Install the HTTP client gems you use (for example faraday and faraday-net_http ).

Net::HTTP — send and read

Send: http.proxy_connect_request_headers . Read: http.last_proxy_connect_response_headers .

require 'uri'
require 'openssl'
require 'ruby_proxy_headers/net_http'

RubyProxyHeaders::NetHTTP.patch!

uri = URI('https://api.ipify.org?format=json')
proxy = URI('http://USERNAME:PASSWORD@PROXYHOST:31280')

http = Net::HTTP.new(uri.host, uri.port, proxy.host, proxy.port, proxy.user, proxy.password)
http.use_ssl = true
http.proxy_connect_request_headers = { 'X-ProxyMesh-Country' => 'US' }

res = http.request(Net::HTTP::Get.new(uri))
puts res.body
puts http.last_proxy_connect_response_headers['X-ProxyMesh-IP']

Faraday — send and read

Proxy: FaradayIntegration.connection(proxy: ...) . Send: proxy_connect_headers . Read: res.headers['X-ProxyMesh-IP'] .

require 'ruby_proxy_headers/faraday'

conn = RubyProxyHeaders::FaradayIntegration.connection(
  proxy: 'http://USERNAME:PASSWORD@PROXYHOST:31280',
  proxy_connect_headers: { 'X-ProxyMesh-Country' => 'US' }
)

res = conn.get('https://api.ipify.org?format=json')
puts res.headers['X-ProxyMesh-IP']

HTTParty — send and read

Proxy: http_proxyaddr / http_proxyport (+ user/pass). Send: proxy_connect_request_headers with ProxyHeadersConnectionAdapter . Read: RubyProxyHeaders.proxy_connect_response_headers .

require 'httparty'
require 'ruby_proxy_headers/httparty'

RubyProxyHeaders::NetHTTP.patch!

proxy = URI('http://USERNAME:PASSWORD@PROXYHOST:31280')
HTTParty.get(
  'https://api.ipify.org?format=json',
  http_proxyaddr: proxy.host,
  http_proxyport: proxy.port,
  http_proxyuser: proxy.user,
  http_proxypass: proxy.password,
  proxy_connect_request_headers: { 'X-ProxyMesh-Country' => 'US' },
  connection_adapter: RubyProxyHeaders::ProxyHeadersConnectionAdapter
)

puts RubyProxyHeaders.proxy_connect_response_headers['X-ProxyMesh-IP']

Excon — send only

Proxy: proxy_url: on ExconIntegration.get . Send: proxy_connect_headers (maps to :ssl_proxy_headers ). Excon does not expose CONNECT response headers on the origin response—use Net::HTTP or Faraday to read X-ProxyMesh-IP .

require 'ruby_proxy_headers/excon'

RubyProxyHeaders::ExconIntegration.get(
  'https://api.ipify.org?format=json',
  proxy_url: 'http://USERNAME:PASSWORD@PROXYHOST:31280',
  proxy_connect_headers: { 'X-ProxyMesh-Country' => 'US' }
)

RestClient, Typhoeus, HTTP.rb

Use RubyProxyHeaders::RestClient, RubyProxyHeaders::Typhoeus, or RubyProxyHeaders::HTTPGem with proxy_headers on HTTPS. Plain Typhoeus::Request / Hydra and plain RestClient do not add custom CONNECT headers. See gem docs: RestClient, Typhoeus, HTTP.rb.

Limitations:

Excon: can send CONNECT headers; cannot read CONNECT response headers on the tunneled response.
Typhoeus: libcurl path supports basic proxy routing only; gem adapter uses Net::HTTP for HTTPS + headers (not parallel Hydra).
RestClient: gem adapter applies when proxy_headers is non-empty on HTTPS.
HTTPClient / Mechanize: basic proxy routing only—use Net::HTTP or Faraday for custom headers.
Nokogiri: parsing only; fetch with a client that supports CONNECT headers.

Common pitfalls

Proxy URL scheme: use http:// on the proxy host even for https:// targets.
HTTPS custom headers: require ruby-proxy-headers (or an adapter in the table above)—a plain client with only proxy: will not send X-ProxyMesh-Country on CONNECT.
Reading X-ProxyMesh-IP: use Net::HTTP, Faraday, or HTTParty patterns above; Excon send-only.
Connection failures: see connection troubleshooting.

Further reading

Back to HTTP proxy overview