Chromix is a Chromium-based browser build focused on presenting a coherent,
per-launch browser persona across JavaScript-visible surfaces. It is built on
pinned ungoogled-chromium sources and the matching Windows/Linux/macOS platform
layer, then adds a reviewed Chromium 152 patch series and lightweight Python and
Node SDKs. The unified cross-platform workflow builds Windows x64, Linux
x64/arm64, and macOS x64/arm64; Releases are published only after all five ZIP
bundles pass checksum, extraction, version, and headless smoke checks.
Chromix is intended for browser automation, compatibility testing, privacy research, and controlled fingerprinting experiments. A custom browser does not make automation undetectable; network reputation, behavior, account history, and application-specific signals still matter.
- Coherent browser personas: coordinated user agent, platform, locale, timezone, screen, hardware, media, canvas, WebGL, WebGPU, audio, font, and related observable values.
- Per-launch identity: SDK defaults generate a random 32-bit fingerprint seed, while command-line switches allow reproducible test personas.
- CloakBrowser-compatible SDK surface: existing Playwright-based Python and Node scripts can usually migrate by changing the import.
- Proxy-aware setup: optional GeoIP resolution can align locale, timezone, and the declared WebRTC address with the proxy exit.
- Portable packages: Windows, Linux, and macOS bundles are ZIP archives with runtime files, locales, fonts, and Chromium/Chromix license files. macOS bundles are unsigned and not notarized.
- Reproducible source layers: the Chromium source archive, ungoogled core, and Windows/Linux/macOS platform revisions are pinned in the repository.
- Integrity checks: releases include
SHA256SUMS; the SDK verifies a bundle before extracting it when the manifest is available.
Prebuilt Windows x64, Linux x64/arm64, and macOS x64/arm64 packages are
published on the GitHub Releases page
after the unified build-cross-platform workflow succeeds for all five targets.
Every browser bundle is a ZIP accompanied by SHA256SUMS. macOS bundles remain
unsigned and are not notarized because Apple signing credentials are not part of
this build.
| Browser version | Platform | Release |
|---|---|---|
152.0.7977.75 |
Windows x64 | v152.0.7977.75 |
151.0.7922.173 |
Windows x64 | v151.0.7922.173 |
The source tree is pinned to Chromium 152.0.7977.82; binary releases can lag
behind that pin. Machine-readable source pins are in
build/ungoogled-revisions.psd1; legacy version files remain available for
tooling compatibility. SDK package versions and release channels are unchanged.
Download both chromix-win-x64.zip and SHA256SUMS from the same release, then
verify the archive in PowerShell:
$actual = (Get-FileHash .\chromix-win-x64.zip -Algorithm SHA256).Hash.ToLowerInvariant()
$expected = ((Get-Content .\SHA256SUMS | Where-Object { $_ -match '\s+\*?chromix-win-x64\.zip$' }) -split '\s+')[0].ToLowerInvariant()
if ($actual -ne $expected) { throw "Chromix archive checksum mismatch" }Extract and start the browser:
Expand-Archive .\chromix-win-x64.zip -DestinationPath .\chromix-win-x64
.\chromix-win-x64\chromix\chromix.cmdPass Chromium flags after the launcher when a deterministic test persona is needed:
.\chromix-win-x64\chromix\chromix.cmd `
--fingerprint=123456789 `
--fingerprint-platform=windows `
--fingerprint-timezone=Europe/Berlin `
--fingerprint-locale=de-DEThe Python wrapper returns Playwright Browser and BrowserContext objects and
uses CloakBrowser-compatible function names and keyword arguments.
Install from PyPI:
python -m pip install chromix playwright
python -m playwright install-depsTo install the current checkout instead, replace chromix with ./sdk/python.
Launch Chromix:
from chromix import launch
browser = launch(
proxy="http://user:pass@proxy.example:8080",
geoip=True,
headless=False,
humanize=True,
)
page = browser.new_page()
page.goto("https://example.com")
print(page.title())
browser.close()Async and persistent-context variants are also available:
from chromix import launch_persistent_context
context = launch_persistent_context(
"./profile",
locale="en-US",
timezone="America/New_York",
headless=False,
)
page = context.new_page()
page.goto("https://example.com")
context.close()Binary management commands:
python -m chromix --version
python -m chromix install
python -m chromix info
python -m chromix clear-cache
python -m chromix widevine # Linux x64 Widevine helperSee sdk/python/README.md for the full API and
environment variables.
The Node wrapper uses playwright-core and exposes the matching camelCase API.
Install from npm:
npm install @xiaoxiaofeihh/chromix playwright-coreLaunch Chromix:
import { launch } from "@xiaoxiaofeihh/chromix";
const browser = await launch({
proxy: "http://user:pass@proxy.example:8080",
geoip: true,
headless: false,
humanize: true,
});
const page = await browser.newPage();
await page.goto("https://example.com");
console.log(await page.title());
await browser.close();Binary management commands:
npx chromix --version
npx chromix install
npx chromix info
npx chromix clear-cacheSee sdk/node/README.md for all options and intentional
compatibility differences.
- The Python distribution and import package are both named
chromix. - The Node SDK is
@xiaoxiaofeihh/chromix. The unscoped npm namechromixbelongs to an unrelated project; always install and import the scoped package.
Set CLOAKBROWSER_BINARY_PATH to bypass release download in either SDK. Point
to the actual executable, not a ZIP, directory, Windows .cmd, or macOS .app
directory. Keep the rest of the extracted bundle alongside it.
Windows example:
$env:CLOAKBROWSER_BINARY_PATH = "D:\chromix-build\src\out\Chromix\chrome.exe"For an extracted Linux candidate use /absolute/path/chromix/chrome; on macOS
use /absolute/path/chromix/Chromium.app/Contents/MacOS/Chromium. Export that
path in the shell running the SDK, then call the usual launch(...). Verify the
inner ZIP's checksum and preserve executable bits/framework symlinks when
extracting it; see BUILDING.md.
The current Python chromix.launch/launch_async wrappers resolve the binary
first and pass their own executable_path to Playwright. Supplying
chromix.launch(executable_path=...) is not supported: it does not bypass
download and results in duplicate keyword arguments at launch. Direct Playwright
chromium.launch(executable_path=...) is a different API and does accept that
option. Similarly, Node's top-level executablePath is not a local-binary
selector; launchOptions.executablePath overrides Playwright's option only
after ensureBinary() runs. Use CLOAKBROWSER_BINARY_PATH for download-free
local use in both wrappers.
Other useful environment variables:
| Variable | Purpose |
|---|---|
CLOAKBROWSER_VERSION |
Select a configured browser major/version channel |
CLOAKBROWSER_RELEASE_CHANNEL |
Select stable or latest |
CLOAKBROWSER_GEOIP_TIMEOUT_SECONDS |
Set the GeoIP lookup timeout |
CLOAKBROWSER_WIDEVINE_CDM |
Point to an existing Widevine CDM directory |
CLOAKBROWSER_WIDEVINE=0 |
Disable Widevine discovery |
CHROMIX_CACHE_DIR |
Override the SDK binary cache directory |
CHROMIX_DOWNLOAD_HOST |
Override the release asset host |
Configured native bundle targets are Windows x64, Linux x64/arm64, and macOS x64/arm64. All use ZIP archives. macOS candidates are unsigned for distribution and not notarized.
The SDK accepts familiar high-level options such as proxy, timezone,
locale, geoip, userAgent, viewport, colorScheme, extension paths, and
persistent profile directories. It converts those settings into Playwright
options and the browser's --fingerprint-* command-line aliases.
Useful explicit arguments include:
--fingerprint=<32-bit-seed>
--fingerprint-platform=windows|macos
--fingerprint-timezone=<IANA-timezone>
--fingerprint-locale=<locale>
--fingerprint-webrtc-ip=<address|auto>
Explicit caller settings take priority over GeoIP-derived values. Keep one stable seed and profile directory when a test needs a persistent identity; generate a new seed only when a new persona is intended.
The following ports are compiled in but disabled by default because they can break automation assumptions or weaken browser isolation:
--fingerprint-devtools-runtime-suppressionsuppresses selected V8 Runtime observables and can interfere with console delivery or automation bindings.--fingerprint-canvas-bridge=<host:port|ws://...>plus--fingerprint-canvas-bridge-unsafeforwards canvas/WebGL operations to a configured endpoint and removes the sandbox from participating renderer processes.--fingerprint-webrtc-fake-srflx=<IPv4>fabricates a server-reflexive WebRTC candidate. Non-proxied UDP remains disabled unless--fingerprint-webrtc-fake-srflx-allow-udpis also supplied.
Use these only in controlled environments. More implementation detail is in
patches/README.md.
Chromix packages Windows x64, Linux x64/arm64, and macOS x64/arm64. The pinned layers are:
| Layer | Pin |
|---|---|
| Chromium | 152.0.7977.82 |
| ungoogled-chromium | 152.0.7977.82-1 |
| ungoogled-chromium-windows | 152.0.7977.82-1.1 |
| ungoogled-chromium-portablelinux | 152.0.7977.82-1 |
| ungoogled-chromium-macos | 152.0.7977.82-1.1 |
| Chromix | 110 patches listed in patches/series |
Requirements include Visual Studio 2022 with Desktop development with C++, the
Windows 11 SDK 10.0.26100 Debugging Tools, Python 3, Git, PowerShell 7, 7-Zip,
and roughly 120 GB of free disk space for Windows. Linux additionally needs
Chromium's Debian/Ubuntu build dependencies, Node.js, Go, and Ninja. macOS
needs Xcode, the command-line tools, Node.js, Ninja, and zip for packaging.
macOS artifacts are unsigned and not notarized because Developer ID and Apple
notary credentials are not part of this build.
From a Developer PowerShell:
pwsh build/windows/build.ps1 -WorkDir D:\chromix-build -Jobs 8Resume an interrupted compile with the same source tree:
pwsh build/windows/build.ps1 -WorkDir D:\chromix-build -Resume -Jobs 8The resulting browser is written to:
D:\chromix-build\src\out\Chromix\chrome.exe
Read BUILDING.md for source revisions, GitHub Actions cache
reuse, domain substitution, packaging, and patch-maintenance details.
patches/ Chromium persona and integration patch series
build/windows/ Windows preparation, staged CI, build, and packaging scripts
build/linux/ Linux packaging helper
build/macos/ macOS build and notarization helpers
sdk/python/ Python Playwright wrapper and binary manager
sdk/node/ Node Playwright wrapper and binary manager
tools/ Patch linter, GN helpers, and regression tests
assets/fonts/ Font assets and provenance used by packaging
Run the repository checks before submitting a change:
python3 tools/check_patches.py
python3 -m unittest discover -s tools/tests -v
git diff --checkA full source preparation and compile is performed by the staged Windows GitHub Actions workflow and the parallel Linux/macOS workflow; Chromium builds exceed a single hosted runner's normal time budget.
Chromix's original source code, patch integration, and SDKs are released under
the BSD 3-Clause License. Bundled Chromium and third-party components
retain their own upstream licenses and notices; the BSD license does not replace
those terms. Font assets likewise retain the terms documented by their original
providers—see assets/fonts/SOURCE.md.
Chromix is under active development. Chromium rebases can require individual patch updates, and binaries are published only after the corresponding staged Windows build and package check 5653 s succeed. Use a fixed release tag and verify its checksum for reproducible automation.