### Environment Configuration: Full Example Source: https://context7.com/dgtlmoon/sockpuppetbrowser/llms.txt A comprehensive example of running Sock Puppet Browser in Docker with various environment variables configured. This allows fine-tuning of concurrency, memory limits, logging, screen resolution, and more. ```bash # Full environment configuration example docker run --rm \ -e MAX_CONCURRENT_CHROME_PROCESSES=100 \ -e HARD_MEMORY_USAGE_LIMIT_PERCENT=85 \ -e DROP_EXCESS_CONNECTIONS=true \ -e STATS_REFRESH_SECONDS=5 \ -e STARTUP_DELAY=0 \ -e LOG_LEVEL=INFO \ -e SCREEN_WIDTH=1920 \ -e SCREEN_HEIGHT=1080 \ -e CHROME_HEADLESS=false \ -e ALLOW_CDP_LOG=false \ --security-opt seccomp=$(pwd)/chrome.json \ -p 127.0.0.1:3000:3000 \ -p 127.0.0.1:8080:8080 \ dgtlmoon/sockpuppetbrowser # Environment variables reference: # MAX_CONCURRENT_CHROME_PROCESSES - Max simultaneous browsers (default: 10) # HARD_MEMORY_USAGE_LIMIT_PERCENT - Memory threshold to reject connections (default: 90) # DROP_EXCESS_CONNECTIONS - Drop vs queue excess connections (default: false) # STATS_REFRESH_SECONDS - Stats logging interval (default: 3) # STARTUP_DELAY - Delay before starting (default: 0) # LOG_LEVEL - Logging verbosity (default: INFO) # SCREEN_WIDTH - Viewport width (default: 1024) # SCREEN_HEIGHT - Viewport height (default: 768) # CHROME_HEADLESS - Run Chrome headfully (default: true) # ALLOW_CDP_LOG - Enable CDP logging (default: false) ``` -------------------------------- ### Run Sock Puppet Browser with Docker Source: https://github.com/dgtlmoon/sockpuppetbrowser/blob/master/README.md Download the required seccomp profile and start the container with the recommended security settings. ```bash wget https://raw.githubusercontent.com/dgtlmoon/sockpuppetbrowser/refs/heads/master/chrome.json docker run --rm --security-opt seccomp=$(pwd)/chrome.json -p 127.0.0.1:3000:3000 dgtlmoon/sockpuppetbrowser ``` -------------------------------- ### Run Headful Mode with Docker Source: https://github.com/dgtlmoon/sockpuppetbrowser/blob/master/README.md Start the container with the CHROME_HEADFUL environment variable to enable virtual display support. ```bash docker run --rm -e CHROME_HEADFUL=true --security-opt seccomp=$(pwd)/chrome.json -p 127.0.0.1:3000:3000 dgtlmoon/sockpuppetbrowser ``` -------------------------------- ### View CDP session logs Source: https://github.com/dgtlmoon/sockpuppetbrowser/blob/master/README.md Example output of a CDP session log when enabled via environment variable and connection URL. ```text 1712224824.5491815 - Attempting connection to ws://localhost:56745/devtools/browser/899f78ce-e7c8-4ad1-b8c9-a7aa449a93ef 1712224824.5528538 - Connected to ws://localhost:56745/devtools/browser/899f78ce-e7c8-4ad1-b8c9-a7aa449a93ef 1712224824.5529754 - Puppeteer -> Chrome: {"method": "Target.getBrowserContexts", "params": {}, "id": 1} 1712224824.553542 - Chrome -> Puppeteer: {"id":1,"result":{"browserContextIds":[]}} ... ``` -------------------------------- ### Python: Connect with Custom Chrome Arguments Source: https://context7.com/dgtlmoon/sockpuppetbrowser/llms.txt Connect to Sock Puppet Browser using pyppeteer with custom Chrome arguments specified in the browserWSEndpoint URL. This example sets a proxy server and window size. ```python import pyppeteer import asyncio async def main(): browser = await pyppeteer.launcher.connect( browserWSEndpoint='ws://localhost:3000/?--proxy-server=http://proxy:8080&--window-size=1280,720' ) page = await browser.newPage() await page.goto("https://httpbin.org/ip") print(await page.content()) await browser.close() asyncio.get_event_loop().run_until_complete(main()) ``` -------------------------------- ### Proxy Authentication with Pyppeteer Source: https://context7.com/dgtlmoon/sockpuppetbrowser/llms.txt Configure HTTP proxy authentication for browser connections using Pyppeteer. Ensure Pyppeteer is installed and the WebSocket endpoint is accessible. ```python import pyppeteer import asyncio async def main(): browser = await pyppeteer.launcher.connect( browserWSEndpoint='ws://localhost:3000/?--proxy-server=http://proxy.example.com:8080' ) page = await browser.newPage() # Authenticate with proxy server await page.authenticate({ 'username': 'proxy_user', 'password': 'proxy_password' }) # Set custom headers if needed await page.setExtraHTTPHeaders({ 'Accept-Language': 'en-US,en;q=0.9' }) # Set custom user agent await page.setUserAgent('Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36') # Navigate through proxy response = await page.goto("https://httpbin.org/ip") print(await page.content()) await browser.close() asyncio.get_event_loop().run_until_complete(main()) ``` -------------------------------- ### Example Statistics Output Source: https://github.com/dgtlmoon/sockpuppetbrowser/blob/master/README.md The JSON response format returned by the /stats endpoint. ```json { "active_connections": 158, "connection_count_total": 8383, "mem_use_percent": 46.9, "special_counter_len": 0 } ``` -------------------------------- ### Connect to Sock Puppet Browser with Pyppeteer Source: https://context7.com/dgtlmoon/sockpuppetbrowser/llms.txt Use this Python snippet with pyppeteer to connect to the Sock Puppet Browser proxy and automate browser tasks. Ensure pyppeteer is installed and the proxy is running. ```python import pyppeteer import asyncio async def main(): # Connect to Sock Puppet Browser proxy browser = await pyppeteer.launcher.connect( browserWSEndpoint='ws://localhost:3000' ) page = await browser.newPage() await page.setBypassCSP(True) # Navigate to a page response = await page.goto("https://example.com", {"waitUntil": "load"}) # Get page content and screenshot html = await page.content() screenshot = await page.screenshot({ "encoding": "binary", "fullPage": True, "quality": 60, "type": "jpeg" }) print(f"Status: {response.status}") print(f"Content length: {len(html)} bytes") await page.close() await browser.close() asyncio.get_event_loop().run_until_complete(main()) ``` -------------------------------- ### Custom Chrome Arguments via WebSocket URL Source: https://context7.com/dgtlmoon/sockpuppetbrowser/llms.txt Pass custom Chrome command-line flags directly to Chrome by appending them as query parameters to the WebSocket connection URL. Flags starting with `--` are recognized. ```bash # Single custom flag ws://127.0.0.1:3000/?--disable-web-security=true # Multiple custom flags ws://127.0.0.1:3000/?--window-size=1920,1080&--proxy-server=http://myproxy:8080&--user-data-dir=/custom/profile # Common useful flags: # --proxy-server= # Use HTTP proxy # --user-data-dir= # Custom profile directory # --disable-web-security=true # Disable CORS # --window-size=, # Set viewport size # --user-agent= # Custom user agent (URL encoded) ``` -------------------------------- ### Access Statistics via HTTP API Source: https://context7.com/dgtlmoon/sockpuppetbrowser/llms.txt Monitor the proxy's operational metrics, such as active connections and memory usage, by sending a GET request to the `/stats` endpoint. The default port is 8080, but can be customized. ```bash # Get current statistics (default port 8080) curl http://127.0.0.1:8080/stats ``` ```json # Response example: { "active_connections": 158, "child_count": 160, "connection_count_total": 8383, "dropped_threshold_reached": 0, "dropped_waited_too_long": 0, "mem_use_percent": 46.9, "special_counter_len": 0, "chrome_start_failures": 0 } ``` ```bash # Use custom stats port with --sport flag docker run --rm --security-opt seccomp=$(pwd)/chrome.json \ -p 127.0.0.1:3000:3000 \ -p 127.0.0.1:9090:9090 \ dgtlmoon/sockpuppetbrowser --sport 9090 ``` -------------------------------- ### Configure viewport size via environment variables Source: https://github.com/dgtlmoon/sockpuppetbrowser/blob/master/README.md Set default viewport dimensions using SCREEN_WIDTH and SCREEN_HEIGHT environment variables during container startup. ```bash docker run -e SCREEN_WIDTH=1920 -e SCREEN_HEIGHT=1080 --security-opt seccomp=$(pwd)/chrome.json -p 127.0.0.1:3000:3000 dgtlmoon/sockpuppetbrowser ``` -------------------------------- ### Configure viewport size via connection URL Source: https://github.com/dgtlmoon/sockpuppetbrowser/blob/master/README.md Set window dimensions by appending the --window-size flag to the connection URL in docker-compose.yml. ```yaml - PLAYWRIGHT_DRIVER_URL=ws://browser-sockpuppet-chrome:3000/?--window-size=1920,1080 ``` -------------------------------- ### Configure Window Size for Browser Instances Source: https://context7.com/dgtlmoon/sockpuppetbrowser/llms.txt Control the viewport dimensions of Chrome instances by appending the `--window-size` parameter to the WebSocket URL. This affects rendering and screenshots. Alternatively, configure via environment variables in Docker. ```bash # Via connection URL query parameter (recommended) # Connect with custom viewport size ws://127.0.0.1:3000/?--window-size=1920,1080 ``` ```yaml # Via docker-compose environment for changedetection.io services: browser: image: dgtlmoon/sockpuppetbrowser environment: - PLAYWRIGHT_DRIVER_URL=ws://browser-sockpuppet-chrome:3000/?--window-size=1920,1080 ``` ```bash # Via environment variables when running container docker run -e SCREEN_WIDTH=1920 -e SCREEN_HEIGHT=1080 \ --security-opt seccomp=$(pwd)/chrome.json \ -p 127.0.0.1:3000:3000 dgtlmoon/sockpuppetbrowser ``` -------------------------------- ### Window Size Configuration Source: https://context7.com/dgtlmoon/sockpuppetbrowser/llms.txt Configure the browser viewport dimensions using connection URL query parameters or environment variables. This impacts rendering and screenshots. ```APIDOC ## Window Size Configuration ### Description Control browser viewport dimensions through connection URL parameters or environment variables. This affects screenshots and page rendering behavior. ### Method GET (via WebSocket connection URL) ### Endpoint `ws://127.0.0.1:3000/?--window-size=,` ### Parameters #### Query Parameters - **--window-size** (string) - Required - Specifies the viewport dimensions in the format `width,height` (e.g., `1920,1080`). ### Environment Variables - **SCREEN_WIDTH** (integer) - Optional - Sets the screen width. - **SCREEN_HEIGHT** (integer) - Optional - Sets the screen height. ### Request Example (Docker Compose) ```yaml services: browser: image: dgtlmoon/sockpuppetbrowser environment: - PLAYWRIGHT_DRIVER_URL=ws://browser-sockpuppet-chrome:3000/?--window-size=1920,1080 ``` ### Request Example (Docker Run) ```bash docker run -e SCREEN_WIDTH=1920 -e SCREEN_HEIGHT=1080 \ --security-opt seccomp=$(pwd)/chrome.json \ -p 127.0.0.1:3000:3000 dgtlmoon/sockpuppetbrowser ``` ``` -------------------------------- ### Enable Headful Mode via WebSocket URL Source: https://github.com/dgtlmoon/sockpuppetbrowser/blob/master/README.md Connect to the browser service with the headful parameter enabled to run Chrome with a virtual display. ```text ws://127.0.0.1:3000/?headful=true ``` -------------------------------- ### Docker Deployment: Basic Run Source: https://context7.com/dgtlmoon/sockpuppetbrowser/llms.txt Run Sock Puppet Browser in a Docker container with recommended security settings. This command mounts the chrome.json security profile and exposes the necessary ports. ```bash # Basic run with security profile (recommended) wget https://raw.githubusercontent.com/dgtlmoon/sockpuppetbrowser/refs/heads/master/chrome.json docker run --rm \ --security-opt seccomp=$(pwd)/chrome.json \ -p 127.0.0.1:3000:3000 \ -p 127.0.0.1:8080:8080 \ dgtlmoon/sockpuppetbrowser ``` -------------------------------- ### Python: Signal Script Completion Source: https://context7.com/dgtlmoon/sockpuppetbrowser/llms.txt Use this Python script with pyppeteer to signal script completion to Sock Puppet Browser. Ensure the browser is connected via the specified WebSocket endpoint. ```python import pyppeteer import asyncio async def run_with_completion_tracking(): browser = await pyppeteer.launcher.connect( browserWSEndpoint='ws://localhost:3000' ) page = await browser.newPage() await page.goto("https://example.com") # Perform your automation tasks... content = await page.content() # Signal script completion to Sock Puppet Browser try: await page._client.send("SOCKPUPPET.specialcounter") except: pass # Command may fail silently, that's OK await page.close() await browser.close() asyncio.get_event_loop().run_until_complete(run_with_completion_tracking()) ``` -------------------------------- ### Enable Headful Mode for Visual Rendering Source: https://context7.com/dgtlmoon/sockpuppetbrowser/llms.txt Run Chrome instances with a visible display using Xvfb for websites that detect headless browsers or when visual rendering is required. This can be enabled via the connection URL or environment variables. ```bash # Enable headful mode via connection URL ws://127.0.0.1:3000/?headful=true ``` ```bash # Enable headful mode via environment variable docker run --rm -e CHROME_HEADFUL=true \ --security-opt seccomp=$(pwd)/chrome.json \ -p 127.0.0.1:3000:3000 dgtlmoon/sockpuppetbrowser ``` ```markdown # Headful mode features: # - Automatic display allocation with xvfb-run -a # - Hundreds of concurrent headful browsers supported # - Better compatibility with automation-detecting websites # - Supports visual rendering, screenshots, DOM operations requiring display ``` -------------------------------- ### Docker Deployment: Production docker-compose.yml Source: https://context7.com/dgtlmoon/sockpuppetbrowser/llms.txt A production-ready docker-compose.yml configuration for Sock Puppet Browser. It includes settings for concurrency, memory limits, ports, security, environment variables, and health checks. ```yaml version: "3" services: browser: image: dgtlmoon/sockpuppetbrowser cap_add: - SYS_ADMIN ports: - "127.0.0.1:3000:3000" # WebSocket endpoint - "127.0.0.1:8080:8080" # Stats endpoint security_opt: - seccomp:./chrome.json environment: - MAX_CONCURRENT_CHROME_PROCESSES=50 - HARD_MEMORY_USAGE_LIMIT_PERCENT=85 - LOG_LEVEL=INFO healthcheck: test: "python3 /usr/src/app/docker-health-check.py --host http://localhost" interval: 30s timeout: 5s retries: 3 start_period: 10s ``` -------------------------------- ### WebSocket Connection Endpoint Source: https://context7.com/dgtlmoon/sockpuppetbrowser/llms.txt Connect to this endpoint to launch a new, isolated Chrome browser instance. The instance persists until the connection is closed. Custom Chrome settings can be passed as query parameters. ```APIDOC ## WebSocket Connection Endpoint ### Description The primary interface for creating new Chrome browser instances. Each WebSocket connection to this endpoint launches an isolated Chrome process that persists until the connection is closed. ### Method GET ### Endpoint `ws://:` ### Parameters #### Query Parameters - **--window-size** (string) - Optional - Specifies the viewport dimensions in the format `width,height` (e.g., `1920,1080`). - **headful** (boolean) - Optional - Set to `true` to enable headful mode, displaying the browser window. ### Request Example (Python using pyppeteer) ```python import pyppeteer import asyncio async def main(): browser = await pyppeteer.launcher.connect( browserWSEndpoint='ws://localhost:3000' ) page = await browser.newPage() await page.goto("https://example.com") # ... further actions await browser.close() asyncio.get_event_loop().run_until_complete(main()) ``` ### Response This endpoint establishes a WebSocket connection. No explicit HTTP response is returned upon successful connection; instead, a WebSocket connection is maintained. ``` -------------------------------- ### Manual Health Check Commands Source: https://context7.com/dgtlmoon/sockpuppetbrowser/llms.txt Verify the proxy server is operational by checking the WebSocket port and stats HTTP endpoint using netcat and curl. ```bash # Check WebSocket port is listening nc -z localhost 3000 && echo "WebSocket OK" || echo "WebSocket FAIL" ``` ```bash # Check stats endpoint curl -sf http://localhost:8080/stats > /dev/null && echo "Stats OK" || echo "Stats FAIL" ``` -------------------------------- ### Enable CDP Debug Logging Source: https://context7.com/dgtlmoon/sockpuppetbrowser/llms.txt Enable low-level Chrome DevTools Protocol logging for debugging. Requires the ALLOW_CDP_LOG=yes environment variable. The log file path is specified in the WebSocket URL query. ```bash # Enable CDP logging in container docker run --rm -e ALLOW_CDP_LOG=yes \ --security-opt seccomp=$(pwd)/chrome.json \ -p 127.0.0.1:3000:3000 \ -v /tmp/logs:/tmp/logs \ dgtlmoon/sockpuppetbrowser # Connect with log file path in query ws://127.0.0.1:3000/?log-cdp=/tmp/logs/session.txt # Log file output example: # 1712224824.5491815 - Attempting connection to ws://localhost:56745/devtools/browser/899f78ce-... # 1712224824.5528538 - Connected to ws://localhost:56745/devtools/browser/899f78ce-... # 1712224824.5529754 - Puppeteer -> Chrome: {"method": "Target.getBrowserContexts", "params": {}, "id": 1} # 1712224824.553542 - Chrome -> Puppeteer: {"id":1,"result":{"browserContextIds":[]}} ``` -------------------------------- ### Implement Docker healthcheck Source: https://github.com/dgtlmoon/sockpuppetbrowser/blob/master/README.md Add a healthcheck to docker-compose.yml to monitor the browser service availability. ```yaml healthcheck: test: "python3 /usr/src/app/docker-health-check.py --host http://localhost" interval: 30s timeout: 5s retries: 3 start_period: 10s ``` -------------------------------- ### Headful Mode with Virtual Display Source: https://context7.com/dgtlmoon/sockpuppetbrowser/llms.txt Enable headful mode to run Chrome with a visible display using Xvfb. This is useful for websites that detect headless browsers or when visual rendering is required. ```APIDOC ## Headful Mode with Virtual Display ### Description Run Chrome with a visible display using Xvfb for scenarios requiring visual rendering or when websites detect headless browsers. Each Chrome instance gets its own isolated virtual display. ### Method GET (via WebSocket connection URL) or Environment Variable ### Endpoint `ws://127.0.0.1:3000/?headful=true` ### Parameters #### Query Parameters - **headful** (boolean) - Optional - Set to `true` to enable headful mode. ### Environment Variables - **CHROME_HEADFUL** (boolean) - Optional - Set to `true` to enable headful mode. ### Request Example (Docker Run) ```bash docker run --rm -e CHROME_HEADFUL=true \ --security-opt seccomp=$(pwd)/chrome.json \ -p 127.0.0.1:3000:3000 dgtlmoon/sockpuppetbrowser ``` ### Features - Automatic display allocation with xvfb-run -a - Supports hundreds of concurrent headful browsers. - Better compatibility with automation-detecting websites. - Supports visual rendering, screenshots, and DOM operations requiring a display. ``` -------------------------------- ### Track Script Completion with Special Counter Source: https://context7.com/dgtlmoon/sockpuppetbrowser/llms.txt Implement script completion tracking by sending a custom CDP command. The special counter, accessible via the stats endpoint, increments upon script completion signals. ```python ``` -------------------------------- ### Docker Container Health Status Source: https://context7.com/dgtlmoon/sockpuppetbrowser/llms.txt Inspect the health status of a Docker container. ```bash # Check container health status docker inspect --format='{{json .State.Health}}' ``` -------------------------------- ### Docker Health Check Command Source: https://context7.com/dgtlmoon/sockpuppetbrowser/llms.txt Perform a health check on a running Docker container using a Python script. ```bash # Docker health check (built into container) docker exec python3 /usr/src/app/docker-health-check.py --host http://localhost ``` -------------------------------- ### Special Counter for Script Completion Tracking Source: https://context7.com/dgtlmoon/sockpuppetbrowser/llms.txt Track successful script completion by sending a custom CDP command. The counter increments when scripts signal completion and is accessible via the stats endpoint. ```APIDOC ## Special Counter for Script Completion Tracking ### Description Track successful script completion by sending a custom CDP command. The counter increments when scripts signal completion, accessible via the stats endpoint. ### Method CDP Command (via WebSocket connection) ### Endpoint WebSocket connection to `ws://:` ### Parameters #### CDP Command - **method**: `Browser.setPermission` (example, actual command may vary) - **params**: Custom parameters to signal script completion. ### Request Example (Conceptual Python) ```python # This is a conceptual example. The exact CDP command and parameters # for signaling script completion would depend on the specific implementation. async def signal_completion(page): # Example: Sending a custom message or event via CDP await page.evaluate('''() => { // Replace with actual CDP command or message window.sendToProxy('script_completed'); }''') # In your pyppeteer script: # await signal_completion(page) ``` ### Response This action does not return a direct response but increments a counter tracked by the Statistics HTTP API. ``` -------------------------------- ### Statistics HTTP API Source: https://context7.com/dgtlmoon/sockpuppetbrowser/llms.txt Access operational metrics and statistics about the proxy server, including active connections and memory usage, via a dedicated HTTP endpoint. ```APIDOC ## Statistics HTTP API ### Description Monitor active connections, memory usage, and operational metrics via the HTTP stats endpoint. Returns JSON data about the proxy server state. ### Method GET ### Endpoint `http://:/stats` ### Parameters #### Query Parameters None #### Environment Variables - **STATS_PORT** (integer) - Optional - Specifies the port for the statistics endpoint. Defaults to 8080. ### Request Example ```bash # Get current statistics (default port 8080) curl http://127.0.0.1:8080/stats ``` ### Response #### Success Response (200) - **active_connections** (integer) - Number of currently active WebSocket connections. - **child_count** (integer) - Number of running Chrome child processes. - **connection_count_total** (integer) - Total number of connections established since startup. - **dropped_threshold_reached** (integer) - Count of connections dropped due to reaching a threshold. - **dropped_waited_too_long** (integer) - Count of connections dropped because they waited too long. - **mem_use_percent** (number) - Current memory usage percentage of the proxy process. - **special_counter_len** (integer) - Length of the special counter. - **chrome_start_failures** (integer) - Number of failures encountered when starting Chrome instances. #### Response Example ```json { "active_connections": 158, "child_count": 160, "connection_count_total": 8383, "dropped_threshold_reached": 0, "dropped_waited_too_long": 0, "mem_use_percent": 46.9, "special_counter_len": 0, "chrome_start_failures": 0 } ``` ### Request Example (Custom Stats Port) ```bash # Use custom stats port with --sport flag docker run --rm --security-opt seccomp=$(pwd)/chrome.json \ -p 127.0.0.1:3000:3000 \ -p 127.0.0.1:9090:9090 \ dgtlmoon/sockpuppetbrowser --sport 9090 ``` ``` -------------------------------- ### Increment Special Counter Source: https://github.com/dgtlmoon/sockpuppetbrowser/blob/master/README.md Use the CDP client to send a custom command to increment the special counter tracked by the statistics endpoint. ```python try: await self.page._client.send("SOCKPUPPET.specialcounter") except: pass ``` -------------------------------- ### Inspect container health status Source: https://github.com/dgtlmoon/sockpuppetbrowser/blob/master/README.md Retrieve detailed health information for a specific container using the docker inspect command. ```bash docker inspect --format='{{json .State.Health}}' browser-sockpuppetbrowser-1 ``` === COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.