CloakBrowser Auto-Update Mechanism: Managing Python Wrapper and Chromium Binary Versions

CloakBrowser automatically maintains both its Python wrapper and stealth-modified Chromium binary through separate background update threads that check PyPI and GitHub Releases respectively, respecting a one-hour rate limit and caching binaries for subsequent launches.

The CloakHQ/CloakBrowser repository distributes a Python orchestration layer alongside a modified Chromium executable, with each component following independent update paths. Understanding the CloakBrowser auto-update mechanism is essential for maintaining current stealth patches and security fixes without manual intervention. The system delegates update checks to daemon threads that minimize performance impact while ensuring version consistency through intelligent caching and resolution strategies.

Dual-Path Update Architecture

CloakBrowser maintains two distinct software artifacts that update separately: the Python wrapper (distributed via PyPI) and the Chromium binary (distributed via GitHub Releases). When the library initializes, cloakbrowser.download.ensure_binary() triggers _maybe_trigger_update_check(), which spawns background threads for each update stream if enabled.

Python Wrapper Updates (PyPI)

The wrapper update mechanism compares the locally installed version against the latest PyPI release. The system imports _wrapper_version from cloakbrowser/_version.py and queries https://pypi.org/pypi/cloakbrowser/json to detect newer releases. If a mismatch exists, the daemon thread logs a warning recommending pip install --upgrade cloakbrowser. This check runs once per process and is not rate-limited, executing immediately upon initialization unless disabled.

Chromium Binary Updates (GitHub)

The browser binary follows a different lifecycle managed through the GitHub Releases API. The system maintains a cache directory (typically ~/.cloakbrowser/<platform>/) where downloaded versions are stored as chromium-v<version>/. The effective binary version is determined by get_effective_version(), which returns the newest cached version or falls back to the CHROMIUM_VERSION constant defined in cloakbrowser/config.py.

Background Update Flow and Rate Limiting

Binary updates proceed through a carefully rate-limited pipeline to prevent API abuse and excessive network traffic.

Rate Limit Enforcement

Before initiating any network request, _should_check_for_update() validates several conditions:

• Environment override: Returns False immediately if CLOAKBROWSER_AUTO_UPDATE=false is set or if CLOAKBROWSER_DOWNLOAD_URL or CLOAKBROWSER_BINARY_PATH are customized.
• Timestamp validation: Inspects .last_update_check in the cache directory. If the elapsed time since the last check is less than UPDATE_CHECK_INTERVAL (1 hour), the check is skipped.

Download and Extraction Process

When allowed, a daemon thread executes _check_and_download_update():

1. Records the current timestamp to .last_update_check.
2. Calls _get_latest_chromium_version() to query the GitHub Releases API for the newest platform-specific tag.
3. Compares the remote version against CHROMIUM_VERSION from config.py.
4. If newer and not cached, invokes _download_and_extract(version=latest) to fetch the archive.
5. Verifies the SHA-256 checksum (unless CLOAKBROWSER_SKIP_CHECKSUM=true).
6. Extracts the binary and creates a version marker via _write_version_marker.

The updated binary remains cached and will be used on the next launch of CloakBrowser, not the current session.

Version Resolution Strategy

CloakBrowser implements a hierarchical version selection algorithm:

• Bundled version: Defined by CHROMIUM_VERSION in cloakbrowser/config.py, representing the version shipped with the current wrapper release.
• Cached versions: Previously downloaded binaries stored in ~/.cloakbrowser/<platform>/chromium-v<version>/chrome.
• Effective version: get_effective_version() returns the newest cached version if available, otherwise the bundled version.

The binary_info() function exposes the current state, returning a dictionary containing the effective version, bundled version, platform tag, and resolved binary path.

Manual Update Control

Users can bypass the automatic background checks and trigger immediate verification:

from cloakbrowser.download import check_for_update

new_version = check_for_update()
if new_version:
    print(f"Chromium {new_version} cached for next launch")
else:
    print("No updates available")

This function blocks until the GitHub API responds, returning the new version string or None. The CLI exposes this as npx cloakbrowser update.

Configuration Environment Variables

The update behavior is controlled through several environment variables:

• CLOAKBROWSER_AUTO_UPDATE=false: Disables all background update checks for both wrapper and binary.
• CLOAKBROWSER_DOWNLOAD_URL=<url>: Forces a custom binary download endpoint; disables auto-update and rate limiting.
• CLOAKBROWSER_BINARY_PATH=<path>: Bypasses download logic entirely, using the specified binary directly.
• CLOAKBROWSER_SKIP_CHECKSUM=true: Disables SHA-256 verification during binary extraction.

These variables are evaluated in _should_check_for_update() and ensure_binary() within cloakbrowser/download.py.

Practical Implementation Examples

# Retrieve current binary metadata

from cloakbrowser.download import binary_info

info = binary_info()
print(f"Effective: {info['version']}, Bundled: {info['bundled_version']}")
print(f"Location: {info['binary_path']}")

# Disable auto-updates before running scripts

export CLOAKBROWSER_AUTO_UPDATE=false
export CLOAKBROWSER_BINARY_PATH=/opt/stealth/chrome
python my_automation_script.py

# Force custom binary without environment variables

import os
os.environ['CLOAKBROWSER_BINARY_PATH'] = '/path/to/custom/chrome'

from cloakbrowser import launch
browser = launch()

Summary

• CloakBrowser employs dual update paths: PyPI for the Python wrapper and GitHub Releases for the Chromium binary.
• Rate limiting prevents excessive API calls through a one-hour interval enforced via the .last_update_check timestamp file.
• Version resolution prefers cached binaries over bundled versions, with get_effective_version() determining the active executable.
• Daemon threads handle network requests asynchronously to avoid blocking browser automation workflows.
• Environment variables provide granular control to disable updates, skip checksums, or specify custom binary sources.

Frequently Asked Questions

How often does CloakBrowser check for updates?

The Python wrapper checks PyPI once per process initialization with no rate limiting, while the Chromium binary checks GitHub Releases no more frequently than once per hour. The binary update interval is controlled by UPDATE_CHECK_INTERVAL (1 hour) and tracked via the .last_update_check file in the cache directory.

Can I disable automatic updates entirely?

Yes. Set the environment variable CLOAKBROWSER_AUTO_UPDATE=false to prevent both wrapper and binary background checks. Alternatively, specify CLOAKBROWSER_BINARY_PATH to use a manually managed binary, which implicitly disables the download and update mechanisms.

Where are downloaded Chromium binaries stored?

Downloaded binaries are cached in ~/.cloakbrowser/<platform>/chromium-v<version>/ (platform varies by operating system). The get_effective_version() function selects the newest cached version, and binary_info() returns the exact resolved path and version metadata.

Why doesn't the updated binary take effect immediately?

The auto-update mechanism downloads and caches new binaries in the background, but the effective version is determined at launch time. Subsequent launches will use the newly cached version, while the currently running process continues using the binary that was effective at its start time.

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