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

> Integrate CloakBrowser with Selenium using ensure_binary. Download and cache the stealth Chromium binary automatically. Pass its path to ChromeOptions for seamless automation. Read the complete guide today.

- Repository: [CloakHQ/CloakBrowser](https://github.com/CloakHQ/CloakBrowser)
- Tags: how-to-guide
- Published: 2026-05-09

---

**To integrate CloakBrowser with Selenium using `ensure_binary`, call the helper function from [`cloakbrowser/download.py`](https://github.com/CloakHQ/CloakBrowser/blob/main/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`](https://github.com/CloakHQ/CloakBrowser/blob/main/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`](https://github.com/CloakHQ/CloakBrowser/blob/main/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`](https://github.com/CloakHQ/CloakBrowser/blob/main/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.

```python

# 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`](https://github.com/CloakHQ/CloakBrowser/blob/main/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`](https://github.com/CloakHQ/CloakBrowser/blob/main/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.