Proxy Setup

Changedetection.io supports comprehensive proxy configuration at both the system level and per-watch level. You can use standard HTTP/HTTPS proxies, SOCKS5 proxies, and integrate with premium proxy services like Bright Data and Oxylabs.

System-Level Proxy Configuration

Set global proxy settings using environment variables. These apply to all watches unless overridden at the watch level.

string

HTTP proxy URL for non-SSL requestsExample:

HTTP_PROXY=http://proxy.example.com:8080

string

HTTPS proxy URL for SSL requestsExample:

HTTPS_PROXY=https://proxy.example.com:8443

string

Comma-separated list of domains/IPs to exclude from proxyExample:

NO_PROXY="localhost,192.168.0.0/24,example.local"

Useful for excluding notification URLs and internal services from proxying.

Docker Compose Example

services:
  changedetection:
    image: ghcr.io/dgtlmoon/changedetection.io
    environment:
      - HTTP_PROXY=socks5h://10.10.1.10:1080
      - HTTPS_PROXY=socks5h://10.10.1.10:1080
      - NO_PROXY="localhost,192.168.0.0/24"
    volumes:
      - changedetection-data:/datastore
    ports:
      - 127.0.0.1:5000:5000

SOCKS5 Proxy Support

Changedetection.io supports SOCKS5 proxies for the basic HTTP fetcher (requests library).

SOCKS5 with Authentication

HTTP_PROXY=socks5://user:pass@host:port
HTTPS_PROXY=socks5://user:pass@host:port

SOCKS5 DNS Resolution

Use socks5h:// to perform DNS resolution through the proxy:

HTTP_PROXY=socks5h://10.10.1.10:1080
HTTPS_PROXY=socks5h://10.10.1.10:1080

Playwright/Puppeteer Limitation: SOCKS5 with authentication is not yet supported for browser-based fetchers (Playwright/Puppeteer). You can use SOCKS5 without authentication or use HTTP/HTTPS proxies with authentication instead.

Per-Watch Proxy Configuration

Configure proxies for individual watches through the web UI or API.

Using proxies.json

Create a proxies.json file in your datastore directory to define reusable proxy profiles:

[
  {
    "proxy_name": "proxy1",
    "proxy_url": "http://proxy1.example.com:8080"
  },
  {
    "proxy_name": "socks5proxy",
    "proxy_url": "socks5://user:pass@socks5.example.com:1080"
  },
  {
    "proxy_name": "brightdata-residential",
    "proxy_url": "http://customer-USER-zone-ZONE:PASS@brd.superproxy.io:22225"
  }
]

Mount proxies.json in Docker

services:
  changedetection:
    image: ghcr.io/dgtlmoon/changedetection.io
    volumes:
      - changedetection-data:/datastore
      - ./proxies.json:/datastore/proxies.json

Select Proxy in Watch Settings

Once defined in proxies.json, proxies appear in the watch edit page:

Edit a watch
Go to the Request tab
Select your proxy from the Proxy dropdown
Save the watch

Bright Data Proxy Integration

Changedetection.io supports Bright Data (formerly Luminati) proxy services. Bright Data will match any first deposit up to $150 using our signup link.

Bright Data Configuration

string

Bright Data proxy URL with zone and credentialsFormat:

http://customer-USERNAME-zone-ZONENAME:PASSWORD@brd.superproxy.io:22225

Example:

{
  "proxy_name": "brightdata-residential",
  "proxy_url": "http://customer-myuser-zone-residential:mypass123@brd.superproxy.io:22225"
}

Bright Data Proxy Types

Residential - Port 22225 (rotating residential IPs)
Datacenter - Port 22225 (datacenter IPs)
Mobile - Port 22225 (mobile carrier IPs)
ISP - Port 22225 (ISP-assigned IPs)

Refer to Bright Data documentation for detailed configuration.

Authentication with Playwright/Puppeteer

For browser-based fetchers (Playwright/Puppeteer), proxy authentication is handled automatically via the page.authenticate() method when credentials are present in the proxy URL:

await page.authenticate({
  username: 'customer-myuser-zone-residential',
  password: 'mypass123'
});

The deprecated Proxy-Authentication header approach is no longer used. Modern browsers handle authentication via the CDP (Chrome DevTools Protocol) authenticate() method.

Playwright and WebDriver Proxy Settings

When using browser-based fetchers, additional proxy configuration options are available.

Playwright Proxy Environment Variables

string

Proxy server URL for PlaywrightExample:

playwright_proxy_server=http://proxy.example.com:8080

string

Comma-separated domains to bypass proxyExample:

playwright_proxy_bypass=*.example.com,localhost

string

Proxy authentication username for Playwright

string

Proxy authentication password for Playwright

WebDriver/Selenium Proxy Settings

string

Proxy type: MANUAL, PAC, DIRECT, AUTODETECT, SYSTEM

string

FTP proxy address

string

Addresses that should bypass the proxy

string

URL for proxy auto-config (PAC) file

boolean

Whether to autodetect proxy settings

string

SOCKS proxy address and port

string

SOCKS proxy username

string

SOCKS proxy password

integer

SOCKS version (4 or 5)

Refer to Selenium proxy documentation for more details.

Oxylabs Proxy Integration

Changedetection.io also supports Oxylabs proxy services, offering Residential, ISP, Rotating and many other proxy types.

Oxylabs Configuration Example

{
  "proxy_name": "oxylabs-residential",
  "proxy_url": "http://customer-USERNAME:PASSWORD@pr.oxylabs.io:7777"
}

Troubleshooting

Proxy Connection Failed

If you see Proxy connection failed? SOCKSHTTPSConnectionPool errors:

Verify the proxy URL format is correct
Check that the proxy server is accessible from your changedetection.io container

Test the proxy with curl:

curl -x socks5://user:pass@host:port https://example.com

DNS Resolution Issues

If you need DNS to be resolved through the proxy (e.g., for accessing internal hostnames), use socks5h:// instead of socks5://:

HTTPS_PROXY=socks5h://proxy:1080  # DNS through proxy
HTTPS_PROXY=socks5://proxy:1080   # DNS locally

Proxy Not Working with Playwright

For Playwright/Puppeteer fetchers:

Ensure the proxy doesn’t require SOCKS5 authentication (not yet supported)
Use HTTP/HTTPS proxies with authentication instead
Check the container can reach the proxy server

Best Practices

Use per-watch proxies for sites that block datacenter IPs
Rotate proxies by creating multiple proxy profiles
Set NO_PROXY to exclude notification services and local resources
Test proxies before deploying to production
Monitor proxy usage through your proxy provider’s dashboard

Environment Variables - All system environment variables
Notifications Setup - Configure NO_PROXY for notification URLs
API Documentation - Programmatic proxy configuration

Get Started

Installation

Core Features

Content Extraction

Browser Integration

Configuration

Advanced

System-Level Proxy Configuration

Docker Compose Example

SOCKS5 Proxy Support

SOCKS5 with Authentication

SOCKS5 DNS Resolution

Per-Watch Proxy Configuration

Using proxies.json

Mount proxies.json in Docker

Select Proxy in Watch Settings

Bright Data Proxy Integration

Bright Data Configuration

Bright Data Proxy Types

Authentication with Playwright/Puppeteer

Playwright and WebDriver Proxy Settings

Playwright Proxy Environment Variables

WebDriver/Selenium Proxy Settings

Oxylabs Proxy Integration

Oxylabs Configuration Example

Troubleshooting

Proxy Connection Failed

DNS Resolution Issues

Proxy Not Working with Playwright

Best Practices

​System-Level Proxy Configuration

​Docker Compose Example

​SOCKS5 Proxy Support

​SOCKS5 with Authentication

​SOCKS5 DNS Resolution

​Per-Watch Proxy Configuration

​Using proxies.json

​Mount proxies.json in Docker

​Select Proxy in Watch Settings

​Bright Data Proxy Integration

​Bright Data Configuration

​Bright Data Proxy Types

​Authentication with Playwright/Puppeteer

​Playwright and WebDriver Proxy Settings

​Playwright Proxy Environment Variables

​WebDriver/Selenium Proxy Settings

​Oxylabs Proxy Integration

​Oxylabs Configuration Example

​Troubleshooting

​Proxy Connection Failed

​DNS Resolution Issues

​Proxy Not Working with Playwright

​Best Practices

​Related Documentation

System-Level Proxy Configuration

Docker Compose Example

SOCKS5 Proxy Support

SOCKS5 with Authentication

SOCKS5 DNS Resolution

Per-Watch Proxy Configuration

Using proxies.json

Mount proxies.json in Docker

Select Proxy in Watch Settings

Bright Data Proxy Integration

Bright Data Configuration

Bright Data Proxy Types

Authentication with Playwright/Puppeteer

Playwright and WebDriver Proxy Settings

Playwright Proxy Environment Variables

WebDriver/Selenium Proxy Settings

Oxylabs Proxy Integration

Oxylabs Configuration Example

Troubleshooting

Proxy Connection Failed

DNS Resolution Issues

Proxy Not Working with Playwright

Best Practices

Related Documentation