How to Integrate CloakBrowser with Selenium Using ensure_binary: A Complete Guide

To integrate CloakBrowser with Selenium using ensure_binary, call the helper function from cloakbrowser/download.py to automatically resolve, download, and cache the stealth Chromium binary, then pass its returned path to ChromeOptions.binary_location while applying stealth arguments from get_default_stealth_args().

CloakBrowser is a stealth-hardened Chromium distribution maintained by CloakHQ that patches fingerprinting leaks to evade bot detection. When automating browser sessions with Selenium, the ensure_binary() utility eliminates manual binary management by handling platform detection, cryptographic verification, and local caching automatically.

How ensure_binary() Resolves the Chromium Binary

The ensure_binary() function implemented in cloakbrowser/download.py (lines 73-90) follows a three-tier resolution strategy to guarantee a valid executable is available before your Selenium session starts.

Environment Variable Override

If the environment variable CLOAKBROWSER_BINARY_PATH is set, ensure_binary() returns that path directly without checking the cache or initiating downloads. This allows pinned binaries or custom builds to bypass automatic management entirely.

Cache Directory Lookup

When no override is configured, the function checks the user’s cache directory at ~/.cloakbrowser/ for a previously downloaded binary matching the current platform architecture and version. Supported platforms include Linux x86_64, Linux arm64, macOS x86_64, macOS arm64, and Windows x64.

Automatic Download and Verification

If the binary is absent from cache, CloakBrowser contacts official download servers to fetch the appropriate Chromium 145 archive, verifies the SHA-256 checksum, extracts the executable, and stores it in the cache directory for subsequent runs.

Configuring Stealth Arguments with get_default_stealth_args()

After securing the binary path, you must supply CloakBrowser’s stealth patches to prevent detection. The get_default_stealth_args() function in cloakbrowser/config.py (lines 40-62) returns a list of command-line flags that activate fingerprint spoofing:

• --no-sandbox
• --fingerprint=<random-seed>
• --fingerprint-platform=windows|macos

These arguments randomize browser fingerprints and platform signals that websites use to identify automation.

Complete Selenium Integration Example

The following script, adapted from examples/integrations/selenium_example.py, demonstrates the full integration pattern. It uses chromedriver-autoinstaller (referenced in lines 6-9 of the example file) to automatically match the ChromeDriver version to the downloaded Chromium 145 binary.

# Selenium + CloakBrowser integration: stealth Chromium with WebDriver

# Requires: pip install selenium cloakbrowser

# Optional: pip install chromedriver-autoinstaller

from selenium import webdriver
from selenium.webdriver.chrome.options import Options

# Cloak Browser helpers

from cloakbrowser.config import get_default_stealth_args
from cloakbrowser.download import ensure_binary

# 1. Ensure the stealth binary is available (downloads on first run)

binary_path = ensure_binary()

# 2. Retrieve the default stealth arguments

stealth_args = get_default_stealth_args()

# 3. Configure Selenium ChromeOptions

options = Options()
options.binary_location = binary_path          # Point to Cloak's binary

options.add_argument("--headless")             # Optional: run headless

for arg in stealth_args:                       # Apply all stealth flags

    options.add_argument(arg)

# 4. Launch ChromeDriver (chromedriver-autoinstaller matches the binary version)

driver = webdriver.Chrome(options=options)

# 5. Use the driver as usual

driver.get("https://example.com")
print(f"Title: {driver.title}")

# Verify stealth patches are active

result = driver.execute_script("""
    return {
        webdriver: navigator.webdriver,
        plugins: navigator.plugins.length,
        platform: navigator.platform,
    }
""")
print("Stealth checks:", result)

driver.quit()

Platform Support and ChromeDriver Requirements

CloakBrowser’s Selenium integration supports Linux x86_64, Linux arm64, macOS x86_64, macOS arm64, and Windows x64. The only external requirement is a ChromeDriver binary compatible with Chromium 145. The recommended approach is installing chromedriver-autoinstaller, which automatically downloads the correct driver version when the session initializes.

Summary

• ensure_binary() in cloakbrowser/download.py handles binary resolution via environment variable, cache lookup, or automated download with SHA-256 verification.
• get_default_stealth_args() in cloakbrowser/config.py supplies the necessary flags to activate fingerprint spoofing and platform mimicking.
• Pass the binary path to ChromeOptions.binary_location and iterate stealth arguments through add_argument() to configure the Selenium driver.
• The integration supports all major desktop platforms and requires only a matching ChromeDriver version, best managed via chromedriver-autoinstaller.

Frequently Asked Questions

Where does CloakBrowser store the downloaded Chromium binary?

CloakBrowser stores binaries in the user’s cache directory at ~/.cloakbrowser/ after downloading and verifying them from official servers. This location is checked on subsequent runs before any new download is initiated.

Can I use a custom Chromium binary instead of the auto-downloaded one?

Yes. Set the CLOAKBROWSER_BINARY_PATH environment variable to the absolute path of your custom binary. When this variable is present, ensure_binary() returns that path directly, skipping cache checks and automatic downloads entirely.

What ChromeDriver version do I need for CloakBrowser?

You need a ChromeDriver version matching Chromium 145, which is the version currently distributed by CloakBrowser. The easiest solution is installing chromedriver-autoinstaller, which automatically detects the browser version and downloads the compatible driver at runtime.

Are the stealth arguments compatible with headless mode?

Yes. You can append --headless to the ChromeOptions alongside the stealth arguments returned by get_default_stealth_args(). The fingerprint spoofing patches remain active in headless mode, ensuring consistent anti-detection protection whether running headed or headless.

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