Routing Ruby HTTP Requests Through an Authenticated Proxy

· Updated:

In Ruby's standard library you set a proxy by passing its address, port, username and password as the third to sixth arguments of Net::HTTP.start or Net::HTTP.new. Faraday and HTTParty wrap the same mechanism with friendlier options. The part that surprises people is the environment: Net::HTTP reads http_proxy even for HTTPS requests and never looks at https_proxy.

Fixed IPs for Ruby and Rails jobs

The Ruby Net::HTTP proxy arguments

The proxy goes into positional arguments after the target host and port, in the order address, port, user, password. Keyword options such as use_ssl follow. This script makes one HTTPS request and prints the IP the server saw:

require 'net/http'
require 'json'

uri = URI('https://proxyv4.com/api/my-ip')

Net::HTTP.start(uri.host, uri.port,
                '203.0.113.10', PORT, 'USER', 'PASS',
                use_ssl: true, open_timeout: 10, read_timeout: 30) do |http|
  res = http.request(Net::HTTP::Get.new(uri))
  puts "#{res.code} exit IP: #{JSON.parse(res.body)['ip']}"
end

If the printed IP is your server's own address, the arguments were probably shifted by one position, a mistake that is easy to make with six positional values. Check http.proxy? and http.proxy_address inside the block when in doubt.

Net::HTTP.new and the no-proxy argument

Net::HTTP.new takes the same proxy arguments, plus a seventh: a comma-separated list of hosts that should bypass the proxy. That is handy when one code path talks to both an external API and an internal service.

http = Net::HTTP.new('example.com', 443,
                     '203.0.113.10', PORT, 'USER', 'PASS',
                     'localhost,.internal.example') # p_no_proxy
http.use_ssl = true
http.proxy?            # => true
http.proxy_address     # => "203.0.113.10"

The Net::HTTP::Proxy class factory

Older code often uses Net::HTTP::Proxy(addr, port, user, pass), which returns a subclass of Net::HTTP with the proxy baked in. It still works, but passing the arguments to start or new is clearer and does not create a new class per proxy.

What :ENV does, and why https_proxy is ignored

The proxy address argument defaults to the symbol :ENV. In that mode Net::HTTP asks URI to find a proxy for the target, and it builds that lookup with the http scheme regardless of use_ssl. The result: only http_proxy (and no_proxy) is consulted, even for HTTPS. Many deploys set just https_proxy, as curl expects, and are then confused when Ruby goes direct.

  • Set http_proxy=http://USER:[email protected]:PORT for Net::HTTP to pick up the environment. Use the lowercase name; the uppercase one is skipped in CGI-style environments.
  • Credentials inside the variable are used and URL-decoded, so percent-encode @, : and / in the password.
  • no_proxy entries match host suffixes and are honored in :ENV mode.
  • Faraday, by contrast, picks the variable that matches the target scheme, so it does read https_proxy for HTTPS URLs.

Turning the environment off

Pass nil as the proxy address to make a connection ignore the variables entirely. This is worth doing for health checks and internal calls in containers where a platform injects http_proxy globally.

# Ignore http_proxy / no_proxy completely for this connection
http = Net::HTTP.new('example.com', 443, nil)

# Or rely on the environment explicitly (this is the default)
http = Net::HTTP.new('example.com', 443, :ENV)

Faraday proxy configuration

Faraday accepts a proxy option as a URL string or a hash with uri, user and password keys. Credentials in the URL are fine as long as they are percent-encoded. With the raise_error middleware, HTTP errors become exceptions, which makes proxy problems loud rather than silent:

require 'faraday'

conn = Faraday.new(
  url: 'https://proxyv4.com',
  proxy: 'http://USER:[email protected]:PORT',
  request: { open_timeout: 10, timeout: 30 }
) do |f|
  f.response :raise_error
end

puts conn.get('/api/my-ip').body

When no proxy option is given, Faraday falls back to the environment variables and respects no_proxy. To make code paths predictable in a large app, switch that off globally and pass the proxy explicitly where you want it:

# Stop every Faraday connection from reading proxy variables
Faraday.ignore_env_proxy = true

The proxy option works with the default net_http adapter and with most others; adapter-specific limits are noted in each adapter gem's documentation.

HTTParty proxy options

HTTParty hands four options straight to Net::HTTP: http_proxyaddr, http_proxyport, http_proxyuser and http_proxypass. Use them per call, or declare the proxy once on a class that includes HTTParty:

require 'httparty'

# Per request
res = HTTParty.get('https://proxyv4.com/api/my-ip',
  http_proxyaddr: '203.0.113.10',
  http_proxyport: PORT,
  http_proxyuser: 'USER',
  http_proxypass: 'PASS',
  timeout: 30)
puts res.parsed_response['ip']

# Or for every call made through a client class
class PartnerApi
  include HTTParty
  base_uri 'https://api.example.com'
  http_proxy '203.0.113.10', PORT, 'USER', 'PASS'
end

Because HTTParty sits on Net::HTTP, the http_proxy-only environment rule from the previous section applies whenever you do not pass the options. Setting them explicitly avoids that trap.

Ruby SOCKS proxy options

Neither Net::HTTP nor Faraday's default adapter speaks SOCKS. The usual add-on is the socksify gem, which adds a Net::HTTP.socks_proxy class method returning a proxied subclass; recent versions take username: and password: keywords for SOCKS5 login.

# gem install socksify
require 'socksify/http'

uri = URI('https://proxyv4.com/api/my-ip')
proxied = Net::HTTP.socks_proxy('203.0.113.10', PORT,
                                username: 'USER', password: 'PASS')

proxied.start(uri.host, uri.port, use_ssl: true) do |http|
  puts http.get(uri.path).body
end

Avoid the global socksify switch

socksify can also patch TCPSocket globally so every connection in the process goes through SOCKS. In a Rails app that includes database and Redis connections, so prefer the per-class socks_proxy form shown above.

Or skip SOCKS entirely

For plain web requests, an HTTP proxy gives the same exit IP and the same end-to-end TLS with zero extra gems. If your provider lets you enable both protocols on one port, use HTTP mode for Net::HTTP, Faraday and HTTParty, and keep SOCKS5 for tools that need it. The trade-offs are laid out in the HTTP vs SOCKS5 guide.

Static IPs for Rails background workers

Sidekiq or Active Job workers that call partner APIs are a classic place for a fixed outbound IP: the partner registers one address, rate limits follow that address, and autoscaled worker hosts all leave through it. A ProxyV4 private datacenter IPv4 is used by one tenant for the whole term and keeps the same address when you renew before expiry, so the registration does not break between deploys. Traffic is not metered, which suits workers that sync large exports.

Every proxy supports HTTP(S) and SOCKS5 with username and password, and per order you choose HTTP only, SOCKS5 only or both on one port. Switching modes can move the proxy to a new port, so update your credentials store from the order page after a change. It is not the right product if a target accepts only mobile IPs or if you need a new address per request, because rotating proxies are not on sale; IPv6 proxies are a separate product that only works on IPv6-ready sites. Buy a single IP from live pricing, point one worker at it, and scale once it behaves. A proxy that fails for a technical reason is covered by the refund policy as account credit.

Exceptions worth rescuing

Proxy failures surface in a small set of exception classes. Rescue them separately so logs say whether the proxy refused you or could not be reached:

begin
  Net::HTTP.start(uri.host, uri.port, PROXY_IP, PROXY_PORT, USER, PASS,
                  use_ssl: true, open_timeout: 10) { |h| h.get(uri.path) }
rescue Net::HTTPClientException => e
  warn "proxy refused the tunnel: #{e.message}"   # 407 "Proxy Authentication Required"
rescue Errno::ECONNREFUSED, Net::OpenTimeout => e
  warn "proxy unreachable: #{e.class}: #{e.message}"
end
  • Net::HTTPClientException with 407 "Proxy Authentication Required": the proxy rejected the CONNECT login on an HTTPS request. Ruby before 2.6 calls this class Net::HTTPServerException. For plain http:// targets you get a Net::HTTPProxyAuthenticationRequired response object instead of an exception. The 407 error page lists every cause.
  • Errno::ECONNREFUSED with Failed to open TCP connection to 203.0.113.10:PORT: wrong port, or the proxy moved after a mode change.
  • Net::OpenTimeout: the proxy port never answered, usually a firewall. Without open_timeout, the default is 60 seconds per attempt; see the proxy timeout guide.
  • Faraday::ConnectionFailed and Faraday::ProxyAuthError: Faraday's wrappers for the same two situations.

Frequently asked questions

Why does Ruby ignore my https_proxy variable?

Net::HTTP looks up the environment proxy using the http scheme, so it only reads http_proxy and no_proxy. Set http_proxy as well, or pass the proxy explicitly.

How do I check which proxy a Net::HTTP connection uses?

Call http.proxy?, http.proxy_address and http.proxy_port on the connection object, then request an IP echo endpoint to confirm the exit address.

Can I use a different proxy for each Sidekiq job?

Yes. Pass the proxy arguments when you open the connection inside the job, choosing from a list in your config. Avoid global settings such as environment variables if jobs need different IPs.

Does Ruby support SOCKS5 proxies with authentication?

Not in the standard library. The socksify gem adds SOCKS support to Net::HTTP, and recent versions accept a username and password; ProxyV4 proxies accept SOCKS5 logins when that mode is enabled on the order.

Will my proxy IP change when I renew it?

Not with ProxyV4: renewing before expiry keeps the same address, so partner registrations tied to the IP keep working.

Fixed IPs for Ruby and Rails jobs

Give your workers a private IPv4 that only you use and that stays the same on renewal, with HTTP(S) and SOCKS5 login and unmetered traffic. Start with one IP and add more as jobs grow.

Get a static IP

Related articles

Proxy setup
Python requests through an authenticated proxy, step by step
Send Python requests through an authenticated HTTP(S) proxy: build the proxies dict, attach it to a Session, encode odd passwords, rotate a list, check the IP.
Proxy errors
Fixing a 407 from your proxy: a credentials checklist
407 Proxy Authentication Required means the proxy refused your login. The causes in one table, and fixes for Chrome, curl, Python, Selenium and antidetect apps.
Free tools
Check proxies in bulk: status, exit IP and latency
Free online proxy checker: paste up to 100 ip:port:user:pass lines and see which proxies work, their exit IP and latency, plus what each failure result means.
Products
Dedicated datacenter proxies: one private IPv4 per customer
Private IPv4 proxies in the US, Vietnam, Japan, South Korea, Singapore, the UK and Hong Kong. One tenant per IP, HTTP(S) and SOCKS5, no traffic metering.
Proxy setup
Set up your proxy, tool by tool
Proxy setup instructions you can follow with the dashboard open: antidetect browsers, operating systems, browser extensions and scraping libraries, all with authenticated HTTP(S) or SOCKS5.
Knowledge base
Setting Up wget Behind a Proxy That Needs a Login
Set a wget proxy username and password with flags, http_proxy and https_proxy variables or wgetrc, then fix 407 errors and handle SOCKS5 downloads.
Knowledge base
How to Run git clone Through a Proxy (HTTPS and SSH Remotes)
Git clone through a proxy: set http.proxy globally, per repo or per host, use socks5h for HTTPS remotes, and route git over SSH with a ProxyCommand.
Knowledge base
Using pip install Behind a Proxy, From One Command to a Saved Config
pip install through a proxy: the --proxy flag, pip.conf and pip.ini paths per OS, env vars, encoding passwords with special characters, and conda settings.
Products
Static ISP proxies: residential IPs on consumer networks
Static ISP proxies in the United States and Vietnam: fixed IPs registered to consumer internet providers, rented to one customer, with unmetered traffic.
Pricing
Proxy prices per IP, by location and volume
Current per-IP rates for private IPv4 and static ISP proxies in the US, Vietnam, Japan, South Korea, Singapore, the UK and Hong Kong, with volume discounts.