Quick Start & Basic Usage

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• CLAUDE.md
• proxybroker/init.py
• tests/test_api.py
• tests/test_integration.py
• tests/test_server.py

ProxyBroker2 finds public proxies from multiple sources, validates them against judge servers, and operates as a rotating proxy server. It supports HTTP(S) and SOCKS4/5 protocols while providing first-class IPv6 support and asynchronous performance.

You use ProxyBroker2 through three primary interfaces: the Command Line Interface (CLI), a Python API for programmatic integration, or a Docker container for production environments.

Sources: README.md:1-20, CLAUDE.md:8-12

Installation

You must use Python 3.10 to 3.14 to run ProxyBroker2. Install the package directly from the GitHub repository to avoid unauthorized versions on PyPI.

Standard Installation

# Install latest version via pip
pip install -U git+https://github.com/bluet/proxybroker2.git

Sources: README.md:120-130, CLAUDE.md:20-25

Docker

# Pull the official image
docker pull bluet/proxybroker2

Sources: README.md:105-110

Command Line Interface (CLI)

The CLI provides three main commands: find, grab, and serve. You execute these by running the module with python -m proxybroker.

CLI Command Summary

Command	Action	Description
find	Scans + Validates	Discovers proxies and checks them against judge servers for anonymity and speed.
grab	Scans Only	Retrieves proxy addresses from sources without performing any validation checks.
serve	Rotates	Starts a local proxy server that distributes requests to a pool of validated proxies.

Sources: README.md:175-215, CLAUDE.md:46-56

Common CLI Examples

# Find 5 working HTTP proxies
python -m proxybroker find --types HTTP --limit 5

# Find 10 US HTTP proxies with High anonymity
python -m proxybroker find --types HTTP --countries US --lvl High --limit 10

# Grab 10 US proxies without checking them
python -m proxybroker grab --countries US --limit 10 --outfile ./proxies.txt

# Run a local proxy server on port 8888
python -m proxybroker serve --host 127.0.0.1 --port 8888 --types HTTP HTTPS

Sources: README.md:180-210, CLAUDE.md:46-56

Python API Usage

The Broker class manages the pipeline of finding and validating proxies. Most asynchronous operations require an asyncio.Queue to store results.

Basic Implementation Flow

The following diagram illustrates how the Broker interacts with providers and the user application.

This diagram shows the data flow from proxy discovery to the user's application consumption.
Sources: README.md:220-240, CLAUDE.md:61-70, tests/test_api.py:50-80

Basic Code Example

import asyncio
from proxybroker import Broker

async def show(proxies):
    while True:
        proxy = await proxies.get()
        if proxy is None: break
        print("Found proxy: %s" % proxy)

async def main():
    proxies = asyncio.Queue()
    broker = Broker(proxies)
    # Search for 10 HTTP/HTTPS proxies
    await asyncio.gather(
        broker.find(types=["HTTP", "HTTPS"], limit=10),
        show(proxies)
    )

if __name__ == "__main__":
    asyncio.run(main())

Sources: README.md:220-245, tests/test_api.py:73-86

Proxy Server Mode

The serve command or broker.serve() method runs a local server. This server acts as a middleman, rotating through external proxies for every request.

Server Request Flow

The sequence diagram details how the local server handles incoming client requests by selecting a proxy from the pool.
Sources: README.md:210-215, CLAUDE.md:85-90, tests/test_server.py:15-50

Proxy Information

When using the proxy server, you can identify which external proxy handled your request by checking the X-Proxy-Info header in the response.

# Example using curl with the local proxy server
curl -v -x http://127.0.0.1:8888 http://httpbin.org/get

Sources: README.md:280-300

Configuration Options

The Broker and Server classes accept several parameters to tune performance and validation behavior.

Parameter	Type	Default	Description
timeout	int	8	Connection and response timeout in seconds.
max_conn	int	200	Maximum number of concurrent connections.
max_tries	int	3	Number of attempts to check a proxy.
judges	list	None	URLs of judge servers to use for validation.
verify_ssl	bool	False	Whether to verify SSL certificates of proxies.

Sources: tests/test_api.py:30-45, tests/test_integration.py:145-160, proxybroker/proxy.py:90-105

Conclusion

ProxyBroker2 simplifies complex proxy management into high-level commands. You can quickly deploy it via CLI for simple tasks or integrate the Broker class into asynchronous Python applications for advanced rotation and validation workflows.