Integration guide · public reference

GodBrowser — Integration Guide

GodBrowser is a patched-Chromium 151 anti-fingerprint browser that generates billions of coherent, real-device fingerprints across 5 operating systems (Windows / macOS / Linux / iOS / Android) and 5 browser engines (Chrome / Safari / Firefox / Samsung Internet / Edge), with deterministic per-seed personas and session persistence. You drive it like Chrome — launch it with --bot-* flags, or automate over the Chrome DevTools Protocol (CDP / Puppeteer / Playwright) — for privacy-preserving browsing, testing, and web automation.

AI / agent integrating programmatically? Fetch the machine-readable version: https://godbrowser.io/llms.txt (concise) · https://godbrowser.io/llms-full.txt (full param dump).

Chromium 1515 OS × 5 browsers 169/191 params verified 13/16 captcha widget types proven on real sites.

Quick start

Get the build (access-controlled)

# GodBrowser binaries are access-gated; request access for the install one-liner + signed builds.

The integration info on this page is public; the binaries are not publicly distributed. Once you have the build, the usage below applies as-is.

Run a persona at a URL (wrapper)

./tools/run_godbrowser.sh --bot-os=macos --bot-browser=chrome https://example.com

The wrapper sets sane defaults (mock-keychain, captcha-on-if-key-present, etc.) and forwards any --bot-* flag.

Run the raw binary directly

/Applications/GodBrowser.app/Contents/MacOS/GodBrowser --bot-os=windows --bot-browser=firefox https://example.com

Every --bot-* flag works on the raw binary too; the wrapper is optional convenience.

Deterministic persona (reproducible fingerprint)

GodBrowser --bot-profile=<seed-string> https://example.com

A given seed always yields the identical coherent persona (UA, fonts, canvas, audio, WebGL, locale, timezone…).

Automate over CDP (the integration path)

GodBrowser --remote-debugging-port=9222 --remote-allow-origins=* --bot-profile=s7 https://example.com

Connect Puppeteer/Playwright/any CDP client to ws://127.0.0.1:9222 (the --remote-allow-origins=* is required for programmatic DevTools-WS clients). isTrusted input + the FP spoofing are native (not CDP-injected), so they survive automation.

Personas (fingerprint selection)

--bot-os= windows | macos | linux | ios | android
--bot-browser= chrome | safari | firefox | samsung | edge (valid OS×browser subset only; e.g. Safari=Apple, Samsung=Android)
--bot-profile=<seed> — a deterministic seed; the same seed always yields the same coherent device. Omit --bot-os/--bot-browser to let the seed pick a coherent persona.
--bot-config-locale=, --bot-egress-countries= — locale / egress provisioning.

Captcha handling

Optional captcha handling: provide a solving-service key via an env var (or --bot-captcha-key-file=<path>) and GodBrowser can complete supported challenge widgets in-browser via that service, no host sidecar. The wrapper enables it when a key is present (read from .env); opt out with GB_CAPTCHA_OFF=1 or --bot-captcha-auto=off. The key is read browser-process-only and never reaches the renderer, page, command line, or logs.

Proxy & geo-coherent egress

For geo-coherent egress, set GODBROWSER_PROXY_SEED=<proxy-template-url> in the environment and pick a country with --bot-proxy-seed-country=<ISO2> (the wrapper alias is --proxy-country=XX). The persona locale + timezone + Accept-Language are made coherent with the chosen exit country automatically. A static upstream proxy is --bot-proxy=<url> (no seed→locale resolution).

Automation & integration

CDP / Puppeteer / Playwright: launch with --remote-debugging-port=<port> and attach normally. The anti-fingerprint layer and trusted input are in the C++/V8 core, so they are present under automation (no JS injection a detector could catch).
Headless: supported via --headless=new (use --enable-automation for headless dump/eval flows).
Per-request isolation: one --bot-profile (or --user-data-dir) per identity; each profile is a stable, distinct, coherent device.
Server-side coherence: JA4/TLS, HTTP/2, and peetprint are aligned byte-for-byte with the real target browser — your proxy/egress just needs to be geo-coherent.
Verifying a persona: open the browser at creepjs / fp-scanner / the target site; GodBrowser is designed to read as a real device (CreepJS headless_rating 0, 0 lies on Chrome personas).

Optimize an automation (record → analyze → requests-only)

When a browser-driven automation is slow or brittle, reduce it to a direct requests-only path:

Run a session with a BusyMate capture device (--bm-device-name=<label> + --bm-auth-file=<account busymate_auth>).
Perform the action — navigate / filter / submit.
If the busymate-net MCP is connected, summarize_device_traffic(<device>) then inspect_requests(host, path_contains, method=POST) the captured traffic.
Identify the data endpoint — the XHR / GraphQL / REST op returning the records.
Reconstruct a direct requests-only call -> instant data.

Worked example: investigating 999.md this way surfaced POST /graphql (op SearchAds); replaying it directly returned the full ~88,793-car dataset. The native capture_network verb (roadmap) will make this in-browser.

Full parameter reference (183 switches)

Every --bot-* / --bm-* switch and the key environment variables. Grouped by family.

environment variables

--bot-captcha-key-file	Solving-service key for in-browser captcha handling (browser-process-only; or supply via .env).
GB_CAPTCHA_OFF=1	Disable captcha handling.
GODBROWSER_PROXY_SEED	Proxy-pool / template URL that drives seed→locale→egress resolution.
GB_BIN	(wrapper) path to a specific GodBrowser binary.

Each switch below carries a status from our live switch-coverage harness (run against this exact build): verified = tested working standalone; needs dep = works once you supply the noted external dependency (e.g. a captcha-solver key or proxy); flags that are declared-but-not-wired are listed separately at the bottom so you don’t rely on them.

Verified — tested working (0)

Getting the build

This page (the integration info + params) is public. The GodBrowser binaries are access-controlled and not publicly distributed — request access to receive the install one-liner and the signed macOS / Linux / Windows builds. Everything above works once you have the build.