CloakBrowser

Practical CloakBrowser code examples for routing browser traffic through Residential Proxies, separated into JavaScript (Node.js) and Python sections.

CloakBrowser is an open source Chromium-based browser developed by CloakHQ, with Playwright-like APIs for browser automation.

CloakBrowser code examples divided by programming language (JavaScript and Python) for browser automation with Residential Proxy.

JavaScript (Node.js)

Prerequisites

npm install cloakbrowser proxy-chain
npx cloakbrowser install

cloakbrowser: Node.js browser automation library built on Chromium with Playwright-like APIs.

Proxy Format

In JavaScript, CloakBrowser accepts a proxy object during launch():

const proxy = {
  server: 'http://proxy.mrscraper.com:10000',
  username: 'user-country-us-sessid-session1',
  password: 'pass123',
}

SOCKS5 Proxy Setup

For SOCKS5 proxies, use proxy-chain to anonymize the authenticated SOCKS5 connection before passing the local proxy server to CloakBrowser:

import { launch } from 'cloakbrowser'
import { anonymizeProxy, closeAnonymizedProxy } from 'proxy-chain'

const username = 'user-country-us'
const password = 'pass123'

const socks5Proxy =
  `socks5://${encodeURIComponent(username)}:${encodeURIComponent(password)}` +
  `@proxy.mrscraper.com:10001`

const localProxy = await anonymizeProxy(socks5Proxy)

const browser = await launch({
  proxy: {
    server: localProxy,
  },
})

try {
  const page = await browser.newPage()

  await page.goto('https://ipinfo.io/json')

  console.log(await page.textContent('body'))
} finally {
  await browser.close()
  await closeAnonymizedProxy(localProxy, true)
}

Use port 10001 for SOCKS5. Always close the browser before calling closeAnonymizedProxy().

1. Basic Request

Demonstrates launching CloakBrowser with an authenticated residential proxy in JavaScript. It navigates to an IP lookup endpoint and prints the verified proxy IP.

import { launch } from 'cloakbrowser'

async function testProxy() {
  // Launch the browser with proxy options
  const browser = await launch({
    headless: true,
    proxy: {
      server: 'http://proxy.mrscraper.com:10000',
      username: 'user-country-us',
      password: 'pass123',
    },
  })

  const page = await browser.newPage()
  await page.goto('https://api.ipify.org?format=json')

  const content = await page.textContent('body')
  console.log('Your Proxy IP:', content)

  await browser.close()
}

testProxy().catch(console.error)

Use Case: Baseline proxy connectivity check and browser launch in Node.js.

Maintains a static IP address across sequential page navigations by reusing a session ID (sessid) and extending session time (sesstime-30).

import { launch } from 'cloakbrowser'

async function runStickySession() {
  const browser = await launch({
    headless: true,
    proxy: {
      server: 'http://proxy.mrscraper.com:10000',
      // 30-minute Canadian static session
      username: 'user-country-ca-sessid-session1-sesstime-30',
      password: 'pass123',
    },
  })

  const page = await browser.newPage()

  const targetUrls = [
    'https://example.com/step1',
    'https://example.com/step2',
    'https://example.com/step3',
  ]

  for (const url of targetUrls) {
    await page.goto(url)
    console.log(`Visited ${url} -> Title:`, await page.title())
  }

  await browser.close()
}

runStickySession().catch(console.error)

Use Case: Executing multi-page JavaScript workflows that need a consistent IP across navigations.

3. Parallel Workers

Demonstrates spawning multiple concurrent JavaScript CloakBrowser instances, each configured with a unique sticky session ID for isolated parallel operations.

import { launch } from 'cloakbrowser'

async function runParallelWorkers() {
  const workerIds = ['worker_1', 'worker_2', 'worker_3']

  const workerPromises = workerIds.map(async (workerId) => {
    const browser = await launch({
      headless: true,
      proxy: {
        server: 'http://proxy.mrscraper.com:10000',
        username: `user-country-us-sessid-${workerId}`,
        password: 'pass123',
      },
    })

    const page = await browser.newPage()
    await page.goto('https://api.ipify.org?format=json')
    const ipData = await page.textContent('body')

    console.log(`Worker [${workerId}] IP:`, ipData)
    await browser.close()
  })

  await Promise.all(workerPromises)
}

runParallelWorkers().catch(console.error)

Use Case: High-concurrency Node.js web scraping where each worker thread requires its own browser instance and IP isolation.

4. Production Error Handling

Production-ready error handling pattern for JavaScript CloakBrowser, providing navigation timeout configurations, response status validation, and safe browser closing routines.

import { launch } from 'cloakbrowser'

async function safeScrape(targetUrl) {
  let browser = null
  try {
    browser = await launch({
      headless: true,
      proxy: {
        server: 'http://proxy.mrscraper.com:10000',
        username: 'user-country-us-sessid-prod1',
        password: 'pass123',
      },
    })

    const page = await browser.newPage()

    // Set 30s timeout
    const response = await page.goto(targetUrl, { timeout: 30000 })

    if (!response || !response.ok()) {
      throw new Error(`HTTP Error ${response?.status()}`)
    }

    console.log('Successfully loaded page title:', await page.title())
  } catch (error) {
    console.error(`CloakBrowser execution failed:`, error.message)
  } finally {
    if (browser) {
      await browser.close()
    }
  }
}

safeScrape('https://example.com')

Use Case: Deploying Node.js scrapers that handle timeouts and site exceptions safely.

Python

Prerequisites

pip install cloakbrowser
python -m cloakbrowser install

cloakbrowser: Python package for Chromium browser automation.
Install sing-box separately and make sure the sing-box command is available on your PATH for SOCKS5 proxy bridging.

Proxy Format

In Python, CloakBrowser receives a dictionary with proxy parameters:

proxy = {
    "server": "http://proxy.mrscraper.com:10000",
    "username": "user-country-us-sessid-session1",
    "password": "pass123"
}

SOCKS5 Proxy Setup

CloakBrowser's Python integration uses sing-box to expose the authenticated SOCKS5 proxy as a local HTTP proxy:

import json
import os
import subprocess
import tempfile
import time

from cloakbrowser import launch

username = "user-country-us"
password = "pass123"

local_proxy = "http://127.0.0.1:8080"

singbox_config = {
    "inbounds": [
        {
            "type": "http",
            "tag": "http-in",
            "listen": "127.0.0.1",
            "listen_port": 8080,
        }
    ],
    "outbounds": [
        {
            "type": "socks",
            "tag": "mrscraper",
            "server": "proxy.mrscraper.com",
            "server_port": 10001,
            "username": username,
            "password": password,
            "version": "5",
        }
    ],
    "route": {
        "final": "mrscraper"
    },
}

with tempfile.NamedTemporaryFile(
    mode="w",
    suffix=".json",
    delete=False,
) as config_file:
    json.dump(singbox_config, config_file)
    config_path = config_file.name

singbox_process = subprocess.Popen([
    "sing-box",
    "run",
    "-c",
    config_path,
])

try:
    time.sleep(1)

    browser = launch(
        headless=True,
        proxy={
            "server": local_proxy,
        },
    )

    try:
        page = browser.new_page()
        page.goto("https://ipinfo.io/json")
        print(page.text_content("body"))
    finally:
        browser.close()
finally:
    singbox_process.terminate()
    singbox_process.wait()
    os.remove(config_path)

Use port 10001 for SOCKS5 and always terminate sing-box after closing the browser.

1. Basic Request

Demonstrates launching CloakBrowser using its Python API to route automated browser requests through a residential proxy.

from cloakbrowser import launch

def test_proxy():
    # Launch browser with proxy server and credentials
    browser = launch(
        headless=True,
        proxy={
            "server": "http://proxy.mrscraper.com:10000",
            "username": "user-country-us",
            "password": "pass123"
        }
    )

    page = browser.new_page()
    page.goto("https://api.ipify.org?format=json")

    print("Your Proxy IP:", page.text_content("body"))
    browser.close()

if __name__ == "__main__":
    test_proxy()

Use Case: Quick proxy verification script in Python.

Maintains a static Python browser session across multiple page navigations using a session ID (sessid).

from cloakbrowser import launch

def run_sticky_session():
    browser = launch(
        headless=True,
        proxy={
            "server": "http://proxy.mrscraper.com:10000",
            "username": "user-country-us-sessid-python1-sesstime-20",
            "password": "pass123"
        }
    )

    page = browser.new_page()

    urls = [
        "https://example.com/step1",
        "https://example.com/step2",
        "https://example.com/step3"
    ]

    for url in urls:
        page.goto(url)
        print(f"Scraped {url} -> Title: {page.title()}")

    browser.close()

if __name__ == "__main__":
    run_sticky_session()

Use Case: Python multi-step workflows that require session IP continuity.

3. Geotargeting

Demonstrates routing Python CloakBrowser traffic through a German residential proxy.

from cloakbrowser import launch

def geotargeted_session():
    browser = launch(
        headless=True,
        proxy={
            "server": "http://proxy.mrscraper.com:10000",
            "username": "user-country-de-sessid-shop1",
            "password": "pass123"
        }
    )

    page = browser.new_page()
    page.goto("https://httpbin.org/headers")

    print("Browser Headers:\n", page.text_content("body"))
    browser.close()

if __name__ == "__main__":
    geotargeted_session()

Use Case: Retrieving the version of an international website served to a specific country.

4. Production Error Handling & Lifecycle Management

Provides robust Python error handling, custom navigation timeout configuration, response validation, and guaranteed teardown.

from cloakbrowser import launch

def safe_scrape(target_url):
    browser = None
    try:
        browser = launch(
            headless=True,
            proxy={
                "server": "http://proxy.mrscraper.com:10000",
                "username": "user-country-us-sessid-prod1",
                "password": "pass123"
            }
        )

        page = browser.new_page()
        page.set_default_timeout(30000)

        page.goto(target_url)
        print("Successfully loaded page title:", page.title())
    except Exception as error:
        print(f"CloakBrowser Python execution failed: {error}")
    finally:
        if browser:
            browser.close()

if __name__ == "__main__":
    safe_scrape("https://example.com")

Use Case: Production Python automation scripts requiring clean error logging and reliable browser process cleanup.

Note

CloakBrowser follows standard Playwright page and navigation APIs in both JavaScript and Python.
Run npx cloakbrowser install or python -m cloakbrowser install prior to execution to download the browser binaries.
Keep sensitive proxy credentials in environment variables (process.env.PROXY_PASSWORD or os.environ.get("PROXY_PASSWORD")).

CloakBrowser

JavaScript (Node.js)

Prerequisites

Proxy Format

SOCKS5 Proxy Setup

1. Basic Request

2. Sticky Session Navigation

3. Parallel Workers

4. Production Error Handling

Python

Prerequisites

Proxy Format

SOCKS5 Proxy Setup

1. Basic Request

2. Sticky Session Navigation

3. Geotargeting

4. Production Error Handling & Lifecycle Management

On this page