@@ -153,14 +153,12 @@ curl -k -H "x-api-key: $KEY" -X POST https://localhost:8765/api/tools/spawn \
   For now: one server = one trust domain. Run separate `umbra-server` processes on different ports if you need real isolation.
 - mTLS option (client-cert auth) instead of bearer keys.
 - per-key rate limiting + quotas.
-- **CloakBrowser integration** — adopt [CloakHQ/CloakBrowser](https://github.com/CloakHQ/CloakBrowser) patched chromium (49–57 C++ source patches: canvas/WebGL/audio/font/GPU/WebRTC/screen/timing) as the default chromium binary. JS-shim stealth (current) loses to native patches because detectors check shim artifacts. Plan:
-  - `umbra setup` CLI → DL cloak binary from `cloakbrowser.dev`, SHA256 verify, cache `~/.umbra/cloak/<version>/`. License is free personal+commercial but **no redistribute** — must DL from upstream, never bundle.
-  - `spawn({ chromium: 'cloak' | 'stock' | <path> })`, default `'cloak'`. First spawn w/ missing binary auto-DLs. Env overrides: `UMBRA_CLOAK_BINARY=<path>`, `UMBRA_NO_CLOAK=1` kill-switch. Unsupported platform → fail-soft to stock + warn (cloak supports linux x64/arm64, mac x64/arm64, win x64).
-  - **humanize layer** port (ref `cloakbrowser/human/`, ~500–800 LOC TS under `src/humanize/`): bezier mouse curves w/ aim points, per-char typing w/ typos+self-correct, scroll accel/decel. Opt-in `humanize: true` on `aria_click`/`aria_type`/`click_at`/`scroll`/`drag`. Presets `default`/`careful` + custom config (`mistype_chance`, `typing_delay`, `idle_between_actions`). Works on stock chromium too.
-  - **geoip-from-proxy** → lookup proxy exit IP, derive timezone+locale, apply via CDP `Emulation.setTimezoneOverride` + `setLocaleOverride`. Opt-in `geoip: true` on spawn. Cache lookups per proxy URL.
-  - **deterministic fingerprint seed** — `spawn({ fingerprintSeed: 'abc' })` → seedable PRNG feeds `rotate_fingerprint`. Reproducible identity for session persistence + detection debugging.
-  - **storage quota normalization** via CDP `Storage.overrideQuotaForOrigin` for fingerprintjs compat.
-  - **WebRTC IP override** via CDP (partial — won't match cloak's native patch but better than current). `webrtcIp: 'auto' | <ip>`, `auto` reuses geoip exit IP.
+- **CloakBrowser integration** ✓ shipped — patched chromium is now the default. See [§ CloakBrowser](#-cloakbrowser-default-chromium). Deferred follow-ons:
+  - **humanize layer** port (bezier mouse curves w/ aim points, per-char typing w/ typos+self-correct, scroll accel/decel). Opt-in on `aria_click`/`aria_type`/`click_at`/`scroll`/`drag`. Works on stock chromium too.
+  - **geoip-from-proxy** → lookup proxy exit IP, derive timezone+locale, apply via CDP `Emulation.setTimezoneOverride` + `setLocaleOverride`. Opt-in `geoip: true` on spawn.
+  - **deterministic fingerprint seed** — `spawn(fingerprint_seed='abc')` → seedable PRNG for `rotate_fingerprint` reproducibility.
+  - **storage quota normalization** via CDP `Storage.overrideQuotaForOrigin`.
+  - **WebRTC IP override** via CDP — covered by cloak's native patch when cloak is active; CDP fallback only useful on stock.
 
 ---
 
@@ -460,6 +458,98 @@ Toggle off via `set_verbosity('full')` when you need raw byte-exact output. Loss
 
 ---
 
+## 🥷 CloakBrowser (default chromium)
+
+`spawn` defaults to `chromium="cloak"` — when the
+[CloakBrowser](https://github.com/CloakHQ/CloakBrowser) patched chromium
+build is installed under `~/.umbra/cloak/<tag>/`, every browser uses it.
+Cloak ships 49-57 C++ source patches against canvas, WebGL, audio, font,
+GPU, WebRTC, screen, and timing fingerprint surfaces. Native patches beat
+JS shims because detectors check the underlying API surface, not just
+property values — so umbra auto-downgrades its own `stealth_mode` to
+`minimal` (automation-tell cleanup only) when cloak is active, to avoid
+double-fingerprinting.
+
+### setup (one-time)
+
+Cloak is **not** bundled (license: free use, no redistribute) and is
+**not** silently auto-downloaded. Install once:
+
+```bash
+python -m umbra --setup           # download + verify + cache
+python -m umbra --setup --force   # re-download
+python -m umbra --setup --tag <t> # pin a specific release
+python -m umbra --status          # show install state (no network)
+python -m umbra --uninstall       # wipe ~/.umbra/cloak/
+```
+
+First `spawn()` with cloak missing **on an interactive TTY** prompts to
+install. Non-TTY (MCP/HTTP server, CI, scripts) silently falls back to
+stock chromium with a one-line warning — spawn never hangs on input.
+A `.declined` marker is written if the user says no, suppressing future
+prompts; delete `~/.umbra/cloak/.declined` to re-enable.
+
+MCP tools: `cloak_status()`, `cloak_install(force=False, tag=None)`.
+
+### opt-out
+
+```bash
+# per-spawn:
+spawn(chromium="stock")          # MCP / python
+# globally:
+export UMBRA_NO_CLOAK=1          # kill-switch — every spawn uses stock
+# or point at your own build:
+export UMBRA_CLOAK_BINARY=/path/to/chrome
+```
+
+### platforms
+
+| platform | cloak build | umbra behavior |
+|---|---|---|
+| linux x64   | ✓ | auto |
+| linux arm64 | ✓ | auto |
+| windows x64 | ✓ | auto |
+| darwin arm64| ✓ (separate tag) | auto |
+| darwin x64  | ✗ | fall back to stock + warn |
+| windows arm64 | ✗ | fall back to stock + warn |
+
+GitHub anon API rate limit is 60/h — set `GITHUB_TOKEN` to lift it.
+Manifest cached 24h.
+
+### measured impact (2026-05, linux-x64, headless)
+
+Public aggregate detectors **do not visibly shift** with cloak — they mostly
+probe the surfaces JS shims already cover (`navigator.webdriver`, basic
+canvas hash, automation flags). The C++ patches harden deeper surfaces those
+aggregates don't score:
+
+| signal | stock + JS shim | + cloak | note |
+|---|---|---|---|
+| creepjs headless % | ≤5 | ≤5 | unchanged — aggregate baseline |
+| creepjs stealth %  | ≤5 | ≤5 | unchanged |
+| sannysoft pass     | 30+/31 | 29/31 | WebGL Vendor/Renderer now report "no webgl context" — cloak strips the uniquely-identifying GPU strings on purpose (intentional surface cut, not a regression) |
+| automation tells   | 0 | 0 | unchanged |
+| UA-CH brands.Chromium version | matches UA | **matches UA** | ✓ fixed — cloak's internal UA-CH stub clobbered our `Network.setUserAgentOverride`, so the minimal payload now re-asserts `navigator.userAgentData` via `defineProperty` from the Python-side detected Chrome version. Only injected under cloak. |
+
+Where cloak actually helps (not aggregate-scored by the public detectors):
+canvas/audio per-pixel noise *patterns*, font enumeration consistency,
+exact GPU info strings, screen geometry edge cases, WebRTC IP leak at the
+C++ level, timing-API quantization. If your adversary fingerprints those
+specifically (FingerprintJS Pro, sift, akamai bot manager), cloak shifts
+the needle in ways `sannysoft`/`creepjs` summaries won't show.
+
+### license note (read this)
+
+CloakBrowser's binary license permits free personal **and** commercial *use*
+but forbids **redistribution**. umbra never bundles the binary — it always
+pulls from upstream releases on your machine. Don't repackage `~/.umbra/cloak`
+into your own product or container image you ship to third parties; the
+auto-download flow exists exactly so each user fetches their own copy. See
+[BINARY-LICENSE.md](https://github.com/CloakHQ/CloakBrowser/blob/main/BINARY-LICENSE.md)
+upstream for the exact terms.
+
+---
+
 ## 🛡️ stealth coverage matrix
 
 | detection vector | obscura | fantoma | sb-mcp | **umbra** |
 
@@ -55,6 +55,7 @@ all = [
 
 [project.scripts]
 umbra-server = "umbra.server:main"
+umbra-cloak-setup = "umbra.cloak.__main__:main"
 
 [project.urls]
 Homepage = "https://github.com/gabriel/umbra"
 
@@ -0,0 +1,59 @@
+"""Top-level umbra CLI.
+
+    python -m umbra --setup [--force] [--tag TAG]
+    python -m umbra --status
+    python -m umbra --uninstall
+    python -m umbra server [server-args ...]
+
+`--setup` is the friendly alias for `umbra-cloak-setup` — fetches the
+CloakBrowser patched chromium build, sha256-verifies it, caches it under
+~/.umbra/cloak/<tag>/, and exits. Spawn auto-installs on first use too,
+so this is for pre-warm or pinning a specific tag.
+"""
+
+from __future__ import annotations
+
+import sys
+
+
+_HELP = """\
+umbra — stealth Chrome automation
+
+  python -m umbra --setup [--force] [--tag TAG]   install CloakBrowser chromium
+  python -m umbra --status                        show cloak install state (no net)
+  python -m umbra --uninstall                     wipe ~/.umbra/cloak/
+  python -m umbra server [args]                   start the MCP / HTTP server
+  python -m umbra --help                          show this help
+
+Equivalent dedicated CLIs (installed by pip):
+  umbra-cloak-setup [...]
+  umbra-server      [...]
+"""
+
+
+def main(argv: list[str] | None = None) -> int:
+    argv = list(sys.argv[1:] if argv is None else argv)
+
+    if not argv or argv[0] in ("-h", "--help", "help"):
+        print(_HELP)
+        return 0
+
+    # Server passthrough.
+    if argv[0] in ("server", "serve"):
+        from umbra.server import main as server_main
+        # umbra.server.main reads sys.argv directly — rewrite it so its
+        # argparse sees only its own args.
+        sys.argv = ["umbra-server", *argv[1:]]
+        server_main()
+        return 0
+
+    # Cloak passthrough — strip a leading "--setup" since the cloak CLI
+    # treats install as the default action.
+    if argv[0] == "--setup":
+        argv = argv[1:]
+    from umbra.cloak.__main__ import main as cloak_main
+    return cloak_main(argv)
+
+
+if __name__ == "__main__":
+    sys.exit(main())
@@ -251,6 +251,19 @@ class StealthOptions:
     extra_args: list[str] = field(default_factory=list)
     window_size: tuple[int, int] = (1920, 1080)
 
+    # Chromium binary selection:
+    #   "cloak"  (default) → CloakBrowser patched build (canvas/audio/webgl/
+    #            font/gpu/webrtc/screen/timing C++ patches). Auto-downloaded
+    #            on first spawn into ~/.umbra/cloak/<tag>/. Beats JS shims.
+    #   "stock" → use the system chromium (chrome_path or auto-detect).
+    #   "<path>" → absolute path to a chromium binary (overrides chrome_path).
+    # Env overrides:
+    #   UMBRA_NO_CLOAK=1   → force stock even if chromium="cloak"
+    #   UMBRA_CLOAK_BINARY=<path> → use this binary as cloak (skip DL)
+    # Unsupported platforms (mac-x64, win-arm64, exotic arches) fall back to
+    # stock with a warning instead of raising.
+    chromium: str = "cloak"
+
     # Performance / footprint
     #   low_memory=True: cut ~80-150MB resident RAM via plausible feature
     #     disables. Stealth-neutral. Use for parallel session farms or
@@ -277,13 +290,127 @@ def __init__(self, options: StealthOptions | None = None):
         self._pool_browser_id: str | None = None
         self._pool_entry: Any = None      # ProxyEntry held for this session
         self._proxy_creds: tuple[str, str] | None = None  # (user, pass) for CDP auth
+        # Set during start() — True when chrome_path was resolved from cloak
+        # cache (or env). Read by _configure_tab → inject.install to skip JS
+        # shims that overlap with cloak's native patches.
+        self._cloak_active: bool = False
 
     @property
     def browser(self) -> uc.Browser:
         if self._browser is None:
             raise RuntimeError("StealthBrowser not started — call await start() first")
         return self._browser
 
+    @staticmethod
+    def _cloak_prompt_install() -> bool:
+        """Ask the user (TTY only) whether to install cloak now.
+
+        Returns True iff the user agreed and the install succeeded. Persists
+        a `.declined` marker in the cache root when the user says no, so we
+        don't prompt again on subsequent spawns. Non-interactive callers
+        (no TTY, MCP/HTTP server, CI) silently return False.
+        """
+        import sys as _sys
+        from umbra.cloak import CloakUnavailable, install_latest
+        from umbra.cloak.loader import cache_root
+
+        root = cache_root()
+        declined = root / ".declined"
+        if declined.exists():
+            return False
+        if not (_sys.stdin.isatty() and _sys.stderr.isatty()):
+            return False
+        try:
+            print(
+                "\nCloakBrowser is not installed. It's a patched chromium build "
+                "that beats JS-shim stealth via native C++ patches.",
+                file=_sys.stderr,
+            )
+            print(
+                "Install now? (~80 MB download, cached to ~/.umbra/cloak/) [Y/n] ",
+                end="", file=_sys.stderr, flush=True,
+            )
+            ans = _sys.stdin.readline().strip().lower()
+        except (EOFError, KeyboardInterrupt):
+            return False
+        if ans not in ("", "y", "yes"):
+            try:
+                root.mkdir(parents=True, exist_ok=True)
+                declined.write_text(
+                    "user declined cloak install — remove this file to re-prompt\n"
+                )
+                print(
+                    "skipping cloak — to install later: `python -m umbra --setup`",
+                    file=_sys.stderr,
+                )
+            except OSError:
+                pass
+            return False
+        print("downloading CloakBrowser ...", file=_sys.stderr, flush=True)
+        try:
+            install_latest()
+        except CloakUnavailable as e:
+            print(f"cloak install failed: {e}", file=_sys.stderr)
+            return False
+        return True
+
+    def _resolve_chromium_binary(self) -> Any:
+        """Pick the chromium binary per `chromium=` option + env overrides.
+
+        Returns a pathlib.Path (or None when caller should leave the existing
+        chrome_path / nodriver auto-detect in place).
+
+        Resolution order, highest priority first:
+          1. env UMBRA_NO_CLOAK=1                  → stock (None)
+          2. opts.chromium = "<absolute path>"     → that path
+          3. opts.chromium = "stock"               → stock (None)
+          4. env UMBRA_CLOAK_BINARY=<path>         → that path (no DL)
+          5. opts.chromium = "cloak" (default)     → resolve+install cloak
+        On any cloak failure (unsupported platform / DL error) we log a
+        warning and return None so the caller falls back to stock.
+        """
+        if os.environ.get("UMBRA_NO_CLOAK"):
+            log.info("UMBRA_NO_CLOAK set — using stock chromium")
+            return None
+
+        choice = (self.options.chromium or "cloak").strip()
+        # Treat an absolute / explicit path as a manual override.
+        if choice not in ("cloak", "stock") and choice:
+            from pathlib import Path as _P
+            p = _P(choice).expanduser()
+            if not p.is_file():
+                log.warning("chromium=%r not found — falling back to stock", choice)
+                return None
+            return p
+
+        if choice == "stock":
+            return None
+
+        # cloak path.
+        try:
+            from umbra.cloak import CloakUnavailable, resolve_cloak_binary
+        except Exception as e:  # noqa: BLE001
+            log.warning("cloak loader import failed (%s) — using stock", e)
+            return None
+        # No silent auto-download. Try the cache first; if empty AND we're on
+        # an interactive TTY, prompt the user once. Non-TTY callers (MCP/HTTP
+        # server, CI) get a warn-and-fall-back so spawn doesn't hang.
+        try:
+            return resolve_cloak_binary(auto_download=False)
+        except CloakUnavailable:
+            pass
+        if self._cloak_prompt_install():
+            try:
+                return resolve_cloak_binary(auto_download=False)
+            except CloakUnavailable as e:
+                log.warning("cloak install reported ok but resolve failed: %s", e)
+                return None
+        log.warning(
+            "CloakBrowser not installed — using stock chromium. "
+            "Run `python -m umbra --setup` to fetch the patched build.",
+        )
+        return None
+
     async def start(self) -> uc.Browser:
         opts = self.options
         flags: list[str] = list(_BASE_FLAGS) + list(opts.extra_args)
@@ -298,6 +425,22 @@ async def start(self) -> uc.Browser:
         if opts.low_memory:
             flags.extend(_LOW_MEMORY_FLAGS)
 
+        # Resolve chromium binary selection. cloak wins by default — its C++
+        # patches against canvas/audio/webgl/font/gpu/webrtc surfaces beat our
+        # JS shims because detectors check the underlying API surface, not
+        # property values. JS shims are layered on top only for tells that
+        # live purely in JS-land (navigator.webdriver etc.); the per-surface
+        # noise is short-circuited when cloak is active so we don't
+        # double-fingerprint the page.
+        cloak_path = self._resolve_chromium_binary()
+        if cloak_path is not None:
+            # Override chrome_path; downstream detect_chrome_version + nodriver
+            # use this path.
+            opts.chrome_path = str(cloak_path)
+            self._cloak_active = True
+        else:
+            self._cloak_active = False
+
         # Detect actual Chrome version → build matching UA + UA-CH metadata.
         # We MUST pin all three (UA string, UA-CH brands, UA-CH fullVersionList)
         # to the same version, or detectors flag the inconsistency.
@@ -428,11 +571,32 @@ async def new_tab(self, url: str = "about:blank") -> Any:
     async def _configure_tab(self, tab: Any) -> None:
         """Install stealth payload + apply CDP overrides on a tab."""
         opts = self.options
+        # If cloak is active, force minimal payload regardless of user setting.
+        # Cloak's C++ patches already noise canvas/audio/webgl/font/etc at the
+        # API surface — layering JS-side noise on top would (a) double-jitter
+        # the fingerprint (cloak applies once, JS applies again), and (b) the
+        # JS hooks themselves are detectable as stealth-lib signatures.
+        # Minimal payload only strips automation tells — orthogonal to cloak.
+        effective_mode = opts.stealth_mode
+        if self._cloak_active and effective_mode != "minimal":
+            log.info(
+                "cloak active — overriding stealth_mode=%r → 'minimal' "
+                "(cloak handles per-surface noise natively)",
+                effective_mode,
+            )
+            effective_mode = "minimal"
         await install_stealth(
             tab,
             timezone=opts.timezone,
             chrome_version=self._chrome_version,
-            mode=opts.stealth_mode,  # type: ignore[arg-type]
+            mode=effective_mode,  # type: ignore[arg-type]
+            # Pass UA-CH only when cloak is active — stock chromium honors
+            # Network.setUserAgentOverride below correctly, so a JS-side
+            # redefinition there would be unnecessary noise (and an extra
+            # detectable hook). With cloak, its internal UA-CH stub clobbers
+            # CDP's override → we re-assert from JS via defineProperty so
+            # navigator.userAgentData matches the UA string we pinned.
+            ua_metadata=self._ua_meta if self._cloak_active else None,
         )
 
         cdp = uc.cdp