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

> Discover the CloakBrowser auto-update mechanism for managing Python wrapper and Chromium binary versions. Learn how background threads and caching ensure up-to-date components.

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

---

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

```python
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`](https://github.com/CloakHQ/CloakBrowser/blob/main/cloakbrowser/download.py).

## Practical Implementation Examples

```python

# 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']}")

```

```bash

# Disable auto-updates before running scripts

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

```

```python

# 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.