How to configure a proxy in Camoufox

Configure the proxy launch option on Camoufox with a server URL and, when needed, username and password. Read an IP-check response and a required target marker through the same browser; neither check guarantees that another request will use the same exit address or that a target will accept it.

Prerequisites

Use Python 3.12 and an authorized target URL that returns a known marker. The example uses the synchronous API on macOS and Linux. Install Python from the official Python downloads page. Camoufox is a Firefox-based browser launched through Playwright’s Python API.

Warning: Proxy credentials are sensitive. Keep them in a runtime secret store, avoid logging proxy configuration, and use an endpoint on a trusted network. The example uses an HTTP or SOCKS5 proxy server URL supported by the Playwright Firefox backend. Run against a permitted test target; remove any temporary secret binding after the check.

Install the tested package and fetch its browser build:

python3.12 -m venv .venv
. .venv/bin/activate
python -m pip install 'camoufox[geoip]==0.5.6'
python -m camoufox fetch

Set PROXY_SERVER to the provider's scheme, host, and port, such as http://proxy.example:8080. Set PROXY_USERNAME, PROXY_PASSWORD, IP_CHECK_URL, TARGET_URL, and EXPECTED_MARKER in the runtime environment. IP_CHECK_URL should be an HTTPS IP echo endpoint returning JSON with an origin field. Never put real credentials in a source file or shell command.

Run one bounded browser check

Save this complete example as camoufox-check.py. It opens one browser, checks the route, then checks the target response and a marker. The IP endpoint and target are separate requests; a rotating proxy can return different exit addresses between them. IP_CHECK_URL should return a JSON object whose origin field is one IPv4 or IPv6 address.

import ipaddress
import json
import os
from urllib.parse import urlsplit

from camoufox.sync_api import Camoufox


PROXY_SERVER = os.environ["PROXY_SERVER"]
PROXY_USERNAME = os.environ.get("PROXY_USERNAME", "")
PROXY_PASSWORD = os.environ.get("PROXY_PASSWORD", "")
IP_CHECK_URL = os.environ["IP_CHECK_URL"]
TARGET_URL = os.environ["TARGET_URL"]
EXPECTED_MARKER = os.environ["EXPECTED_MARKER"].strip()
MAX_TEXT_CHARS = 12_000

proxy_parts = urlsplit(PROXY_SERVER)
try:
    proxy_port = proxy_parts.port
except ValueError:
    proxy_port = None
if (
    proxy_parts.scheme not in {"http", "socks5"}
    or not proxy_parts.hostname
    or proxy_port is None
    or not 1 <= proxy_port <= 65_535
    or proxy_parts.username
    or proxy_parts.password
    or proxy_parts.path not in {"", "/"}
    or proxy_parts.query
    or proxy_parts.fragment
):
    raise SystemExit("Set PROXY_SERVER to a supported proxy scheme, host, and port without credentials")
if not EXPECTED_MARKER:
    raise SystemExit("EXPECTED_MARKER must not be empty")

proxy = {"server": PROXY_SERVER}
if PROXY_USERNAME or PROXY_PASSWORD:
    if not PROXY_USERNAME or not PROXY_PASSWORD:
        raise SystemExit("Set both proxy credential variables or leave both empty")
    proxy.update(username=PROXY_USERNAME, password=PROXY_PASSWORD)

with Camoufox(headless=True, proxy=proxy) as browser:
    page = browser.new_page()
    page.set_default_timeout(10_000)
    try:
        ip_response = page.goto(
            IP_CHECK_URL,
            wait_until="domcontentloaded",
            timeout=20_000,
        )
        if ip_response is None or ip_response.status != 200:
            raise RuntimeError("IP check did not return HTTP 200")
        ip_payload = json.loads(page.locator("body").inner_text(timeout=10_000))
        observed_ip = ip_payload.get("origin")
        if not isinstance(observed_ip, str):
            raise RuntimeError("IP check returned no origin value")
        ipaddress.ip_address(observed_ip.strip())

        target_response = page.goto(
            TARGET_URL,
            wait_until="domcontentloaded",
            timeout=20_000,
        )
        if target_response is None or target_response.status != 200:
            raise RuntimeError("Target did not return HTTP 200")
        text = page.locator("body").inner_text(timeout=10_000)[:MAX_TEXT_CHARS]
        if EXPECTED_MARKER not in text:
            raise RuntimeError("Required target marker was not found")

        print({"exit_ip_present": True, "target_status": 200, "content_valid": True})
    except Exception as error:
        raise SystemExit(f"Browser check failed ({type(error).__name__})") from None
    finally:
        page.close()

Run the saved script with the environment variables set: python camoufox-check.py.

Expected output

The script prints this only after the IP echo returned HTTP 200 with a valid IPv4 or IPv6 address and the target returned HTTP 200 with the required marker. exit_ip_present means the echo value passed IP parsing; the address is not printed. target_status is the target document’s HTTP status, and content_valid means the marker was found in the inspected content. This line matches the successful task-owned local-fixture run; it is an example result, not a claim about a proxy provider or an external target.

{'exit_ip_present': True, 'target_status': 200, 'content_valid': True}

The output reports a successful IP response without printing the address. The marker check scans at most 12,000 characters of extracted body text; it does not cap bytes downloaded by the browser. Navigation has a 20-second timeout, but browser startup, multiple requests, and shutdown need a separate worker deadline if the whole job needs a hard elapsed-time limit.

geoip=True asks Camoufox to look up the proxy IP and set location-related browser values, including the WebRTC IP. Camoufox’s docs recommend enabling GeoIP with a proxy. The run used for this guide emitted LeakWarning: When using a proxy, it is heavily recommended that you pass geoip=True. Omitting it does not prove that a request leaked or that the browser exposed a mismatched address, but it also leaves out the documented GeoIP-based WebRTC adjustment. Choose based on whether your permitted workflow needs that address consistency. GeoIP needs a reachable external IP lookup and adds a network request. It does not prove target acceptance or anonymity. See the Camoufox GeoIP and proxy guide.

Diagnose a failed check

For HTTPS targets, target TLS protects the browser-to-target connection through the proxy. This example does not configure TLS to the proxy endpoint; use only a proxy transport supported by the installed Playwright Firefox backend and protect the client-to-proxy network when it carries credentials. A successful IP echo proves only the address reported for that request. It does not establish identity, location, or acceptance on another request.

Use the proxy error 407 guide for challenge diagnosis and the sticky-session guide when a permitted multi-step flow needs one provider session.

ProxyLaneTraffic never expires

Premium residential proxies
From $2/GB

Scale your workflows with the tools you already use. Rotating or sticky sessions up to 72 hours.

Try 350 MB for $1.95 View plans