How to Configure the Camofox-Browser Proxy Pool with Multiple Ports for Load Balancing

Camofox-browser distributes browser launches across multiple proxy endpoints using a round-robin pool strategy controlled by environment variables in lib/config.js and managed by createProxyPool() in lib/proxy.js.

The open-source camofox-browser project provides a robust proxy pool abstraction that enables automatic load balancing across multiple HTTP proxy ports. By configuring specific environment variables parsed by the configuration loader, you can distribute browser instances across a range of proxy endpoints without modifying application code.

How the Proxy Pool Works

The proxy pool implementation spans three core files in the jo-inc/camofox-browser repository, working together to parse environment variables, manage port rotation, and inject proxy settings into browser launches.

Configuration Parsing in lib/config.js

The loadConfig() function (lines 60-66) reads process.env and constructs the proxy configuration object. It specifically looks for PROXY_HOST, PROXY_PORT, and the multi-port variable PROXY_PORTS.

The parseProxyPorts() helper function (lines 11-25) converts PROXY_PORTS into an array of integers, supporting both comma-separated lists (10001,10002,10003) and range syntax (10001-10010) which expands to individual port numbers.

Pool Factory in lib/proxy.js

The createProxyPool() function (lines 175-210) in lib/proxy.js instantiates the pool object. When the strategy parameter equals 'round_robin' (the default), the function expects a host string and a non-empty ports array. The pool maintains an internal index that increments on every call to getNext(), using modulo arithmetic (index % ports.length) to cycle through available ports sequentially.

Server Integration in server.js

In server.js (lines 9 and 409), the application initializes the pool at startup using const proxyPool = createProxyPool(CONFIG.proxy), then passes proxy objects to the browser launcher for each new instance.

Configuring Multiple Ports for Load Balancing

To enable multi-port load balancing, define your proxy endpoints using environment variables before starting the camofox-browser server:

1. Set PROXY_HOST to your proxy server hostname or load balancer DNS name
2. Define PROXY_PORTS using comma-separated values or range syntax
3. Optionally set PROXY_STRATEGY=round_robin (this is the default)
4. Provide authentication credentials via PROXY_USERNAME and PROXY_PASSWORD if required

Example Environment Configuration

# Proxy pool with round-robin load balancing across 5 ports

PROXY_STRATEGY=round_robin
PROXY_HOST=proxy.mycompany.net
PROXY_PORTS=10001,10002,10003,10004,10005
PROXY_USERNAME=myuser
PROXY_PASSWORD=mypassword

While PROXY_PORT is still read for backward compatibility, PROXY_PORTS takes precedence when present, enabling the pool to rotate across multiple endpoints.

Understanding Round-Robin Distribution

The default round_robin strategy provides simple yet effective load balancing through two distinct methods defined in the pool interface:

• getLaunchProxy() – Returns the first port in the array (used for the initial browser launch)
• getNext() – Returns subsequent host:port combinations, cycling through the array using modulo indexing to distribute connections evenly

This mechanism ensures that browser instances are distributed sequentially across your proxy infrastructure rather than concentrating load on a single endpoint.

Using the Proxy Pool in Custom Code

You can leverage the same pool logic in external scripts, CLI tools, or test suites by importing the configuration and proxy utilities:

import { loadConfig } from './lib/config.js';
import { createProxyPool, buildProxyUrl } from './lib/proxy.js';

// Load environment-driven configuration
const CONFIG = loadConfig();

// Create the pool (round_robin by default)
const proxyPool = createProxyPool(CONFIG.proxy);

// Obtain proxy for initial browser launch
const launchProxy = proxyPool.getLaunchProxy(); // Returns first port

// Get next proxy for subsequent launches
const nextProxy = proxyPool.getNext(); // Rotates to next port

// Build URL string for external CLI tools like yt-dlp
const proxyUrl = buildProxyUrl(proxyPool, CONFIG.proxy);
// Output: "http://myuser:mypassword@proxy.mycompany.net:10002"

These helpers mirror the internal implementation used by server.js, allowing consistent proxy selection logic across custom integrations.

Summary

• Configure the camofox-browser proxy pool by setting the PROXY_PORTS environment variable in lib/config.js
• Use comma-separated lists (10001,10002) or range syntax (10001-10010) to define multiple proxy ports
• createProxyPool() in lib/proxy.js implements round-robin rotation via the getNext() method
• server.js consumes the pool automatically when launching new browser instances
• Custom scripts can import pool utilities from lib/proxy.js to maintain consistent load-balancing behavior

Frequently Asked Questions

What is the difference between PROXY_PORT and PROXY_PORTS in camofox-browser?

PROXY_PORT accepts a single integer for backward compatibility, while PROXY_PORTS accepts multiple ports via comma-separated values or hyphenated ranges. When PROXY_PORTS is defined, it overrides the single-port configuration and enables the round-robin pool rotation logic in lib/proxy.js.

How does the round-robin strategy distribute connections across proxy ports?

The round_robin strategy maintains an internal counter that increments with each call to getNext(). The implementation calculates the active port using index % ports.length, cycling sequentially through the array parsed from PROXY_PORTS. The initial browser launch uses getLaunchProxy(), which specifically returns the first port in the array.

Can I use range syntax to define 100 proxy ports without listing them individually?

Yes. In lib/config.js, the parseProxyPorts() function (lines 11-25) automatically expands hyphenated ranges such as PROXY_PORTS=10001-10100 into individual port numbers. This allows concise configuration of large proxy pools without manually typing comma-separated values.

Where does camofox-browser initialize the proxy pool during startup?

The pool initialization occurs in server.js at line 9, where the code imports createProxyPool from lib/proxy.js, and again at line 409 where it executes createProxyPool(CONFIG.proxy). The CONFIG object is constructed by loadConfig() in lib/config.js, which parses the environment variables defining your proxy endpoints.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}