15% off your first purchase with code WELCOME15, up to 25 GB.

See pricing
ARC Proxies

Integration · HTTP clients

Use a proxy in Docker containers

To send a container's traffic through a proxy, pass HTTPS_PROXY, HTTP_PROXY and NO_PROXY into it: docker run -e HTTPS_PROXY=http://user:pass@host:port …. For builds, the same names are predefined build arguments. Docker itself does not route anything; the HTTP clients inside the container read the variables. The daemon's own proxy setting is a separate thing that only affects image pulls.

Reviewed 30 Oct 2026

your proxy, as a URL
http://USERNAME_pool-arcfast_country-de:PASSWORD@proxy.arcproxies.io:8000

The short answer

  • Containers: -e HTTPS_PROXY=… (and HTTP_PROXY, NO_PROXY), or proxies in ~/.docker/config.json for every new container.
  • Builds: --build-arg HTTPS_PROXY=…; predefined proxy args stay out of docker history and the image.
  • The daemon proxy (daemon.json) is for pulling images, not for your containers' traffic.
  • docker inspect shows -e values in plain text, credentials included.

Setup

Set up Docker with a proxy, step by step

  1. 01

    Run one container through the gateway

    Set the variable in the container and check the exit IP. The image's HTTP client must honour the variables; curl, Python's standard library, Go and most package managers do, while Node.js needs extra setup.

    shell
    docker run --rm \  -e HTTPS_PROXY="http://USERNAME_pool-arcfast_country-de:PASSWORD@proxy.arcproxies.io:8000" \  -e HTTP_PROXY="http://USERNAME_pool-arcfast_country-de:PASSWORD@proxy.arcproxies.io:8000" \  -e NO_PROXY="localhost,127.0.0.1" \  python:3.12-slim \  python -c "import urllib.request; print(urllib.request.urlopen('https://api.ipify.org?format=json', timeout=20).read())"
  2. 02

    Keep the credentials in an env file

    An env file keeps the password out of shell history. Set lowercase variants too: some tools read only one case, and curl reads plain-HTTP proxies only from lowercase http_proxy.

    shell
    cat > arc.env <<'EOF'HTTPS_PROXY=http://USERNAME_pool-arcfast_country-de:PASSWORD@proxy.arcproxies.io:8000https_proxy=http://USERNAME_pool-arcfast_country-de:PASSWORD@proxy.arcproxies.io:8000HTTP_PROXY=http://USERNAME_pool-arcfast_country-de:PASSWORD@proxy.arcproxies.io:8000http_proxy=http://USERNAME_pool-arcfast_country-de:PASSWORD@proxy.arcproxies.io:8000NO_PROXY=localhost,127.0.0.1no_proxy=localhost,127.0.0.1EOFchmod 600 arc.envdocker run --rm --env-file arc.env curlimages/curl -s https://api.ipify.org
  3. 03

    Use the proxy during a build

    Pass it as a build argument. HTTP_PROXY, HTTPS_PROXY, NO_PROXY and their lowercase forms are predefined, so the Dockerfile needs no ARG line; Docker excludes them from docker history and does not cache them, so a changed value does not rebuild cached layers. Never use ENV for a proxy: that bakes it into the image.

    shell
    docker build \  --build-arg HTTPS_PROXY="http://USERNAME_pool-arcfast_country-de:PASSWORD@proxy.arcproxies.io:8000" \  --build-arg NO_PROXY="localhost,127.0.0.1" \  -t my-scraper .
  4. 04

    Configure services in Compose

    Keep the URL in a .env file next to the Compose file and reference it. List the other services' names in NO_PROXY, or calls from the scraper to your own API or database admin UI go out through the gateway too.

    compose.yaml
    # .env:  ARC_PROXY_URL=http://USERNAME_pool-arcfast_country-de:PASSWORD@proxy.arcproxies.io:8000services:  scraper:    build:      context: .      args:        HTTPS_PROXY: ${ARC_PROXY_URL}    environment:      HTTPS_PROXY: ${ARC_PROXY_URL}      HTTP_PROXY: ${ARC_PROXY_URL}      NO_PROXY: localhost,127.0.0.1,api,db  api:    image: my-api  db:    image: postgres:17
  5. 05

    Give each container its own exit or market

    The username is per container, so containers can hold different sticky sessions or countries. Cities come from the published list, lowercased without spaces.

    shell
    for market in de-berlin gb-london us-chicago; do  cc=${market%%-*}; city=${market#*-}  user="USERNAME_pool-arcfast_country-${cc}_city-${city}_session-${cc}${city}_sesstime-30"  docker run -d --name "worker-${market}" \    -e HTTPS_PROXY="http://${user}:PASSWORD@proxy.arcproxies.io:8000" \    my-scraperdone

Container, build and daemon proxies are three different settings

SettingWhereAffects
Container environmentdocker run -e, --env-file, Compose environmentHTTP clients inside that container
Client configproxies.default in ~/.docker/config.jsonSets the variables in every new container and build
Build argumentsdocker build --build-arg, Compose build.argsRUN steps during the build only
Daemondaemon.json proxies or a systemd drop-inImage pulls and pushes by dockerd; ignored by Docker Desktop

Docker Desktop has its own proxy settings under Settings → Resources → Proxies. Pulling images through a per-GB residential proxy rarely makes sense; leave the daemon on a direct connection and proxy only the scraping traffic.

What the variables do and do not cover

There is no standard for proxy variables, and Docker's documentation says so. Most clients read HTTPS_PROXY for https:// URLs and send a CONNECT request with the credentials from the URL; NO_PROXY formats differ, for example whether .example.com matches subdomains or CIDR ranges are understood. Headless browsers are configured through their automation library's proxy option instead; the Playwright and scrapy-playwright guides show those.

Rotating plans authenticate by username and password only, with no IP allowlisting, so every container needs the credentials. Treat them as secrets: Docker stores container environment variables in plain text, readable with docker inspect and preserved by docker commit.

The problem

Common pitfalls

ENV in the Dockerfile

ENV HTTPS_PROXY=... ends up in the image and every container started from it. Use --build-arg for builds and runtime variables for containers.

Service names missing from NO_PROXY

Containers call each other by service name. Without those names in NO_PROXY, internal calls go to the gateway and fail or cost bandwidth.

Configuring the daemon and expecting containers to follow

daemon.json proxies affect dockerd's own pulls. Containers only see a proxy through their environment or the client config.

Special characters in the password

The password sits in a URL. Percent-encode @, : and /; in a systemd drop-in for the daemon, Docker's docs say the escapes need a doubled %%.

FAQ

Questions

Something not covered? Write to contact@arcproxies.io.

How do I set a proxy for a Docker container?

Pass the variables when you start it: docker run -e HTTPS_PROXY=http://user:pass@host:port -e HTTP_PROXY=... -e NO_PROXY=localhost image. Or set proxies in ~/.docker/config.json to add them to every new container.

How do I use a proxy during docker build?

Use docker build --build-arg HTTPS_PROXY=http://user:pass@host:port .. The proxy variables are predefined build arguments, available to RUN steps and excluded from docker history.

Does the Docker daemon proxy apply to containers?

No. The daemon proxy in daemon.json or a systemd drop-in is what dockerd uses to pull images. Container traffic uses the variables passed into the container.

Are proxy credentials safe in Docker environment variables?

They are stored in plain text in the container configuration and visible through docker inspect and the API. Limit who can talk to the Docker daemon, prefer env files over command-line values, and never bake the proxy into an image.

Sources & review

Last reviewed by the ARC Proxies team. Prices are read from the live catalog at build time.

  1. [1]Docker Docs: Use a proxy server with the Docker CLI
  2. [2]Docker Docs: Daemon proxy configuration
  3. [3]Docker Docs: Dockerfile reference: Predefined ARGs
  4. [4]curl: curl man page: Environment

Next

What people build with it

Use caseProxies for web scraping and data collectionA second provider that just works — Scrapy, requests, Crawlee or Playwright, self-serve, no sales call, bandwidth that never expires.Use caseResidential proxies for AI agentsBring your own residential IPs to browser-use, Playwright, Crawl4AI, n8n and any MCP tool — one sticky session per task, billed per GB.Use caseProxies for QA, app and localisation testingSee your own site the way a user in Tokyo, São Paulo or Munich sees it — currency, language, consent banner, CDN edge and all — before they report it.GlossaryHTTP CONNECTHTTP CONNECT is the HTTP request method a client sends to a proxy to ask for a tunnel to a host and port; once the proxy answers with a 2xx status it blindly forwards bytes in both directions, which is how HTTPS passes through an HTTP proxy with TLS intact end to end (RFC 9110, section 9.3.6).GlossarySticky sessionA sticky session is a setting on a rotating proxy that keeps the same exit IP address for a chosen period, usually by attaching a session identifier to the connection, so a multi-step task appears to come from one address from start to finish.IntegrationcurlSend curl through an authenticated proxy with -x and -U, check the exit IP, test sticky sessions and countries, use socks5h, and read 407 failures.IntegrationPlaywrightSet up an authenticated proxy in Playwright for Python and Node: launch and per-context proxies, sticky sessions, geo-targeting and handling proxy errors.Integrationscrapy-playwrightSet a proxy for scrapy-playwright: PLAYWRIGHT_LAUNCH_OPTIONS, a sticky session per browser context, markets as contexts and what a 407 looks like.

Integrations

Other http clients

Python requestsUse an authenticated proxy with Python requests: the proxies argument, sticky sessions per task, geo-targeting, SOCKS5 and retries that skip 407 errors.HTTPXConfigure an authenticated proxy in HTTPX 0.28: the proxy= argument that replaced proxies=, mounts per domain, async clients, SOCKS5 and error handling.aiohttpUse an authenticated proxy with aiohttp: proxy= per request or per session, why proxy_auth is deprecated, SOCKS5 through aiohttp-socks, and 407 handling.AxiosUse an authenticated proxy with Axios in Node.js: the proxy option on 1.16.1+, https-proxy-agent for older versions, sticky sessions, SOCKS5 and 407s.Node.js fetchNode's built-in fetch has no proxy option. Use undici's ProxyAgent as the dispatcher, or NODE_USE_ENV_PROXY, with sticky sessions, SOCKS5 and 407 handling.curlSend curl through an authenticated proxy with -x and -U, check the exit IP, test sticky sessions and countries, use socks5h, and read 407 failures.GoRoute Go's net/http through an authenticated proxy: Transport.Proxy with url.UserPassword, a sticky session per request context, SOCKS5 and 407 checks.RubyUse an authenticated proxy in Ruby: Net::HTTP proxy arguments, Faraday proxy options, sticky sessions per task, geo-targeting and 407 handling.PHP GuzzleRoute PHP Guzzle and plain cURL through an authenticated proxy: the proxy option, sticky sessions, geo-targeting, retries that stop on a 407.Java HttpClientUse an authenticated proxy with java.net.http.HttpClient: ProxySelector, Authenticator, the Basic-over-CONNECT setting, sticky sessions and 407s.C# HttpClientUse an authenticated proxy in .NET: WebProxy and NetworkCredential on SocketsHttpHandler, a client per sticky session, SOCKS5 and 407 handling.Rust reqwestRoute Rust reqwest through an authenticated proxy: Proxy::all with basic_auth, a Client per sticky session, socks5h, timeouts and 407 errors.wgetRun GNU Wget through an authenticated proxy: https_proxy, --proxy-user, a .wgetrc for credentials, sticky sessions for mirrors and exit codes.PostmanSend Postman requests through an authenticated proxy: the custom proxy settings, Proxy auth, checking the exit IP, sessions, countries and Newman.

Get started

Get credentials and paste them in.

Sign up, buy a gigabyte, generate a username in the dashboard. Code WELCOME15 takes 15% off your first purchase; bandwidth never expires.

Create your accountQuestions first? contact@arcproxies.io