Integration4 min read

Use a proxy with curl

Test an HTTP proxy with curl, separate proxy authentication from destination authentication, and read connection failures without exposing credentials.

On this page

The starting point

Start with one bounded request. Establish that the gateway works before adding a browser, concurrency or application code.

Keep the gateway and destination separate

Obtain your provider's proxy scheme, host, port and authentication method. A destination beginning with https:// does not automatically mean the proxy address also begins with https://. Those are separate connections.

The example below uses curl 8.3 or later and HTTP Basic proxy authentication. Have your secret manager populate PROXY_USERNAME and PROXY_PASSWORD in the process environment. Set PROXY_URL to your provider's gateway; https://proxy.example.invalid:8443 is an illustrative value that deliberately cannot connect. Use the scheme and port your provider actually supports.

Send one request with a deadline

Save this as proxy-check.sh and run it with sh proxy-check.sh. curl imports credentials itself so the expanded password is not a shell argument. The command prints the destination's status, the CONNECT status and elapsed time; it discards the response body.

proxy-check.sh · curl 8.3+
: "${PROXY_URL:?Set your provider proxy URL}"
curl --disable --silent --show-error --fail \
  --noproxy '' \
  --proxy "$PROXY_URL" \
  --variable %PROXY_USERNAME \
  --variable %PROXY_PASSWORD \
  --expand-proxy-user '{{PROXY_USERNAME}}:{{PROXY_PASSWORD}}' \
  --connect-timeout 10 --max-time 30 \
  --output /dev/null \
  --write-out 'http=%{http_code} connect=%{http_connect} seconds=%{time_total}\n' \
  'https://example.com/'

Find the failing layer

A successful response proves this request completed; it does not establish a particular exit country or carrier. For that, use your provider's documented diagnostic endpoint or an endpoint you control that reports the observed source IP.

Keep the same destination and credentials when comparing your application with curl. Changing three settings at once makes a successful retry hard to explain. Share the exit code, timing and sanitized status with support, rather than a verbose trace containing authentication data.

  • Name-resolution or connection failure: check gateway spelling, port and outbound connectivity first.
  • CONNECT 407: investigate proxy authentication before changing destination headers.
  • Certificate failure: check the hostname, trust chain and clock. Keep certificate verification enabled.

From reading to doing

Before you ship

  • Use an actual gateway from your provider.
  • Inject credentials privately; do not paste secrets into shell history.
  • Record one bounded baseline before testing parallel traffic.

Sources & further reading

Technical references used for this guide. Check the documentation for your installed version and your provider’s supported configuration.