feat(docker): opt-in GPU acceleration via CLOAKBROWSER_GPU_ACCEL (#189)

Author: mvanhorn

README.md

@@ -571,6 +571,7 @@ Access the original un-patched Playwright page at `page._original` if you need r
 | `CLOAKBROWSER_AUTO_UPDATE` | `true` | Set to `false` to disable background update checks |
 | `CLOAKBROWSER_SKIP_CHECKSUM` | `false` | Set to `true` to skip SHA-256 verification after download |
 | `CLOAKBROWSER_GEOIP_TIMEOUT_SECONDS` | `5` | Max seconds for GeoIP resolution before continuing without it |
+| `CLOAKBROWSER_GPU_ACCEL` | — | Set to `1` to opt in to Docker GPU acceleration flags |
 
 ## Fingerprint Management
 
@@ -848,6 +849,12 @@ services:
       start_period: 10s
 ```
 
+### GPU acceleration in Docker
+
+GPU acceleration is opt-in. Set `CLOAKBROWSER_GPU_ACCEL=1` to add Chromium's EGL, GPU rasterization, GPU blocklist bypass, and Linux Vaapi video decode flags. If you use NVIDIA GPUs, install the NVIDIA Container Toolkit on the Docker host and add a GPU device reservation to your Compose service.
+
+See [`examples/docker-compose.gpu.yml`](examples/docker-compose.gpu.yml) for a complete Compose example. If you run CloakBrowser inside your own multi-container stack, mirror the environment variable and GPU reservation in that service.
+
 **Per-connection fingerprint seeds** — run multiple browser identities from a single container. Each unique seed spawns a separate Chrome process with its own fingerprint:
 
 ```python

cloakbrowser/browser.py

@@ -16,6 +16,7 @@
 
 import logging
 import os
+import sys
 from typing import Any, Literal, TypedDict
 from urllib.parse import quote, unquote, urlparse, urlunparse
 
@@ -64,6 +65,7 @@ def launch(
     humanize: bool = False,
     human_preset: HumanPreset = "default",
     human_config: HumanConfigOverrides | None = None,
+    gpu_accel: bool = False,
     **kwargs: Any,
 ) -> Any:
     """Launch stealth Chromium browser. Returns a Playwright Browser object.
@@ -90,6 +92,8 @@ def launch(
         humanize: Enable human-like mouse, keyboard, scroll behavior (default False).
         human_preset: Humanize preset — 'default' or 'careful' (default 'default').
         human_config: Custom humanize config mapping to override preset values.
+        gpu_accel: Enable Docker GPU acceleration flags (default False).
+            Can also be enabled with CLOAKBROWSER_GPU_ACCEL=1.
         **kwargs: Passed directly to playwright.chromium.launch().
 
     Returns:
@@ -112,7 +116,14 @@ def launch(
     if exit_ip and not (args and any(a.startswith("--fingerprint-webrtc-ip") for a in args)):
         args = list(args or [])
         args.append(f"--fingerprint-webrtc-ip={exit_ip}")
-    chrome_args = build_args(stealth_args, (args or []) + proxy_extra_args, timezone=timezone, locale=locale, headless=headless)
+    chrome_args = build_args(
+        stealth_args,
+        (args or []) + proxy_extra_args,
+        timezone=timezone,
+        locale=locale,
+        headless=headless,
+        gpu_accel=gpu_accel,
+    )
 
     logger.debug("Launching stealth Chromium (headless=%s, args=%d)", headless, len(chrome_args))
 
@@ -159,6 +170,7 @@ async def launch_async(  # noqa: C901
     humanize: bool = False,
     human_preset: HumanPreset = "default",
     human_config: HumanConfigOverrides | None = None,
+    gpu_accel: bool = False,
     **kwargs: Any,
 ) -> Any:
     """Async version of launch(). Returns a Playwright Browser object.
@@ -175,6 +187,8 @@ async def launch_async(  # noqa: C901
         humanize: Enable human-like mouse, keyboard, scroll behavior (default False).
         human_preset: Humanize preset — 'default' or 'careful' (default 'default').
         human_config: Custom humanize config mapping to override preset values.
+        gpu_accel: Enable Docker GPU acceleration flags (default False).
+            Can also be enabled with CLOAKBROWSER_GPU_ACCEL=1.
         **kwargs: Passed directly to playwright.chromium.launch().
 
     Returns:
@@ -202,7 +216,14 @@ async def launch_async(  # noqa: C901
     if exit_ip and not (args and any(a.startswith("--fingerprint-webrtc-ip") for a in args)):
         args = list(args or [])
         args.append(f"--fingerprint-webrtc-ip={exit_ip}")
-    chrome_args = build_args(stealth_args, (args or []) + proxy_extra_args, timezone=timezone, locale=locale, headless=headless)
+    chrome_args = build_args(
+        stealth_args,
+        (args or []) + proxy_extra_args,
+        timezone=timezone,
+        locale=locale,
+        headless=headless,
+        gpu_accel=gpu_accel,
+    )
 
     logger.debug("Launching stealth Chromium async (headless=%s, args=%d)", headless, len(chrome_args))
 
@@ -253,6 +274,7 @@ def launch_persistent_context(
     humanize: bool = False,
     human_preset: HumanPreset = "default",
     human_config: HumanConfigOverrides | None = None,
+    gpu_accel: bool = False,
     **kwargs: Any,
 ) -> Any:
     """Launch stealth browser with a persistent profile and return a BrowserContext.
@@ -282,6 +304,8 @@ def launch_persistent_context(
         humanize: Enable human-like mouse, keyboard, scroll behavior (default False).
         human_preset: Humanize preset — 'default' or 'careful' (default 'default').
         human_config: Custom humanize config mapping to override preset values.
+        gpu_accel: Enable Docker GPU acceleration flags (default False).
+            Can also be enabled with CLOAKBROWSER_GPU_ACCEL=1.
         **kwargs: Passed directly to playwright.chromium.launch_persistent_context().
 
     Returns:
@@ -306,7 +330,14 @@ def launch_persistent_context(
     if exit_ip and not (args and any(a.startswith("--fingerprint-webrtc-ip") for a in args)):
         args = list(args or [])
         args.append(f"--fingerprint-webrtc-ip={exit_ip}")
-    chrome_args = build_args(stealth_args, (args or []) + proxy_extra_args, timezone=timezone, locale=locale, headless=headless)
+    chrome_args = build_args(
+        stealth_args,
+        (args or []) + proxy_extra_args,
+        timezone=timezone,
+        locale=locale,
+        headless=headless,
+        gpu_accel=gpu_accel,
+    )
 
     logger.debug(
         "Launching persistent stealth Chromium (headless=%s, user_data_dir=%s)",
@@ -377,6 +408,7 @@ async def launch_persistent_context_async(
     humanize: bool = False,
     human_preset: HumanPreset = "default",
     human_config: HumanConfigOverrides | None = None,
+    gpu_accel: bool = False,
     **kwargs: Any,
 ) -> Any:
     """Async version of launch_persistent_context().
@@ -403,6 +435,8 @@ async def launch_persistent_context_async(
         humanize: Enable human-like mouse, keyboard, scroll behavior (default False).
         human_preset: Humanize preset — 'default' or 'careful' (default 'default').
         human_config: Custom humanize config mapping to override preset values.
+        gpu_accel: Enable Docker GPU acceleration flags (default False).
+            Can also be enabled with CLOAKBROWSER_GPU_ACCEL=1.
         **kwargs: Passed directly to playwright.chromium.launch_persistent_context().
 
     Returns:
@@ -432,7 +466,14 @@ async def launch_persistent_context_async(
     if exit_ip and not (args and any(a.startswith("--fingerprint-webrtc-ip") for a in args)):
         args = list(args or [])
         args.append(f"--fingerprint-webrtc-ip={exit_ip}")
-    chrome_args = build_args(stealth_args, (args or []) + proxy_extra_args, timezone=timezone, locale=locale, headless=headless)
+    chrome_args = build_args(
+        stealth_args,
+        (args or []) + proxy_extra_args,
+        timezone=timezone,
+        locale=locale,
+        headless=headless,
+        gpu_accel=gpu_accel,
+    )
 
     logger.debug(
         "Launching persistent stealth Chromium async (headless=%s, user_data_dir=%s)",
@@ -957,6 +998,7 @@ def build_args(
     timezone: str | None = None,
     locale: str | None = None,
     headless: bool = True,
+    gpu_accel: bool = False,
 ) -> list[str]:
     """Combine stealth args with user-provided args and locale flags.
 
@@ -979,6 +1021,13 @@ def build_args(
     if not headless or _platform.system() == "Windows":
         seen["--ignore-gpu-blocklist"] = "--ignore-gpu-blocklist"
 
+    if gpu_accel or os.environ.get("CLOAKBROWSER_GPU_ACCEL"):
+        seen["--use-gl"] = "--use-gl=egl"
+        seen["--enable-gpu-rasterization"] = "--enable-gpu-rasterization"
+        seen["--ignore-gpu-blocklist"] = "--ignore-gpu-blocklist"
+        if sys.platform.startswith("linux"):
+            seen["--enable-features"] = "--enable-features=VaapiVideoDecoder"
+
     if extra_args:
         for arg in extra_args:
             key = arg.split("=", 1)[0]

examples/docker-compose.gpu.yml

@@ -0,0 +1,22 @@
+services:
+  cloakbrowser:
+    image: cloakhq/cloakbrowser
+    command: cloakserve
+    restart: unless-stopped
+    environment:
+      CLOAKBROWSER_GPU_ACCEL: "1"
+    ports:
+      - "127.0.0.1:9222:9222"
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:9222/json/version"]
+      interval: 30s
+      timeout: 5s
+      retries: 3
+      start_period: 10s
+    deploy:
+      resources:
+        reservations:
+          devices:
+            - driver: nvidia
+              count: all
+              capabilities: [gpu]

js/src/args.ts

@@ -29,6 +29,14 @@ export function buildArgs(options: LaunchOptions): string[] {
   if (options.headless === false || process.platform === "win32") {
     seen.set("--ignore-gpu-blocklist", "--ignore-gpu-blocklist");
   }
+  if (options.gpuAccel || process.env.CLOAKBROWSER_GPU_ACCEL) {
+    seen.set("--use-gl", "--use-gl=egl");
+    seen.set("--enable-gpu-rasterization", "--enable-gpu-rasterization");
+    seen.set("--ignore-gpu-blocklist", "--ignore-gpu-blocklist");
+    if (process.platform === "linux") {
+      seen.set("--enable-features", "--enable-features=VaapiVideoDecoder");
+    }
+  }
   if (options.args) {
     for (const arg of options.args) {
       const key = arg.split("=")[0];

js/src/types.ts

@@ -25,6 +25,8 @@ export interface LaunchOptions {
   locale?: string;
   /** Auto-detect timezone/locale from proxy IP (requires: npm install mmdb-lib). */
   geoip?: boolean;
+  /** Enable Docker GPU acceleration flags. Can also be enabled with CLOAKBROWSER_GPU_ACCEL=1. */
+  gpuAccel?: boolean;
   /** Raw options passed directly to playwright/puppeteer launch(). */
   launchOptions?: Record<string, unknown>;
   /** Enable human-like mouse, keyboard, and scroll behavior. */

js/tests/config.test.ts

@@ -1,4 +1,4 @@
-import { describe, it, expect } from "vitest";
+import { afterEach, describe, it, expect } from "vitest";
 import {
   CHROMIUM_VERSION,
   getArchiveExt,
@@ -11,6 +11,22 @@ import {
 } from "../src/config.js";
 import { _buildArgsForTest, resolveTimezone } from "../src/playwright.js";
 
+const originalPlatform = Object.getOwnPropertyDescriptor(process, "platform")!;
+const originalGpuAccel = process.env.CLOAKBROWSER_GPU_ACCEL;
+
+afterEach(() => {
+  Object.defineProperty(process, "platform", originalPlatform);
+  if (originalGpuAccel === undefined) {
+    delete process.env.CLOAKBROWSER_GPU_ACCEL;
+  } else {
+    process.env.CLOAKBROWSER_GPU_ACCEL = originalGpuAccel;
+  }
+});
+
+function setPlatform(platform: NodeJS.Platform): void {
+  Object.defineProperty(process, "platform", { ...originalPlatform, value: platform });
+}
+
 describe("config", () => {
   it("CHROMIUM_VERSION matches expected format", () => {
     expect(CHROMIUM_VERSION).toMatch(/^\d+\.\d+\.\d+\.\d+(\.\d+)?$/);
@@ -183,6 +199,45 @@ describe("buildArgs deduplication", () => {
   });
 });
 
+describe("buildArgs GPU acceleration", () => {
+  it("leaves GPU acceleration flags off by default", () => {
+    delete process.env.CLOAKBROWSER_GPU_ACCEL;
+    const args = _buildArgsForTest({});
+    expect(args).not.toContain("--use-gl=egl");
+    expect(args).not.toContain("--enable-gpu-rasterization");
+    expect(args).not.toContain("--enable-features=VaapiVideoDecoder");
+  });
+
+  it("CLOAKBROWSER_GPU_ACCEL adds Linux GPU flags", () => {
+    process.env.CLOAKBROWSER_GPU_ACCEL = "1";
+    setPlatform("linux");
+    const args = _buildArgsForTest({});
+    expect(args).toContain("--use-gl=egl");
+    expect(args).toContain("--enable-gpu-rasterization");
+    expect(args).toContain("--ignore-gpu-blocklist");
+    expect(args).toContain("--enable-features=VaapiVideoDecoder");
+  });
+
+  it("skips VaapiVideoDecoder off Linux", () => {
+    process.env.CLOAKBROWSER_GPU_ACCEL = "1";
+    setPlatform("darwin");
+    const args = _buildArgsForTest({});
+    expect(args).toContain("--use-gl=egl");
+    expect(args).toContain("--enable-gpu-rasterization");
+    expect(args).not.toContain("--enable-features=VaapiVideoDecoder");
+  });
+
+  it("gpuAccel option adds GPU flags without the environment variable", () => {
+    delete process.env.CLOAKBROWSER_GPU_ACCEL;
+    setPlatform("linux");
+    const args = _buildArgsForTest({ gpuAccel: true });
+    expect(args).toContain("--use-gl=egl");
+    expect(args).toContain("--enable-gpu-rasterization");
+    expect(args).toContain("--ignore-gpu-blocklist");
+    expect(args).toContain("--enable-features=VaapiVideoDecoder");
+  });
+});
+
 describe("buildArgs webrtc IP", () => {
   it("passes --fingerprint-webrtc-ip from args", () => {
     const args = _buildArgsForTest({ args: ["--fingerprint-webrtc-ip=1.2.3.4"] });

tests/conftest.py

@@ -1,11 +1,10 @@
 """Shared test fixtures."""
 
-import os
-
 import pytest
 
 
 @pytest.fixture(autouse=True)
-def _clean_backend_env(monkeypatch):
-    """Ensure CLOAKBROWSER_BACKEND doesn't leak into tests from the host environment."""
+def _clean_env(monkeypatch):
+    """Ensure host-level wrapper env vars don't leak into tests."""
     monkeypatch.delenv("CLOAKBROWSER_BACKEND", raising=False)
+    monkeypatch.delenv("CLOAKBROWSER_GPU_ACCEL", raising=False)

tests/test_build_args.py

@@ -1,5 +1,7 @@
 """Unit tests for build_args timezone/locale injection and timezone alias."""
 
+import sys
+
 from cloakbrowser.browser import build_args, _resolve_timezone
 
 
@@ -151,6 +153,50 @@ def test_non_value_flags_preserved():
     assert "--no-sandbox" in args
 
 
+# --- GPU acceleration ---
+
+
+def test_gpu_accel_default_off(monkeypatch):
+    """GPU acceleration flags should stay off unless explicitly enabled."""
+    monkeypatch.delenv("CLOAKBROWSER_GPU_ACCEL", raising=False)
+    args = build_args(stealth_args=True, extra_args=None)
+    assert "--use-gl=egl" not in args
+    assert "--enable-gpu-rasterization" not in args
+    assert "--enable-features=VaapiVideoDecoder" not in args
+
+
+def test_gpu_accel_env_adds_linux_flags(monkeypatch):
+    """CLOAKBROWSER_GPU_ACCEL enables GPU flags, including Vaapi on Linux."""
+    monkeypatch.setenv("CLOAKBROWSER_GPU_ACCEL", "1")
+    monkeypatch.setattr(sys, "platform", "linux")
+    args = build_args(stealth_args=True, extra_args=None)
+    assert "--use-gl=egl" in args
+    assert "--enable-gpu-rasterization" in args
+    assert "--ignore-gpu-blocklist" in args
+    assert "--enable-features=VaapiVideoDecoder" in args
+
+
+def test_gpu_accel_skips_vaapi_off_linux(monkeypatch):
+    """VaapiVideoDecoder is Linux-only."""
+    monkeypatch.setenv("CLOAKBROWSER_GPU_ACCEL", "1")
+    monkeypatch.setattr(sys, "platform", "darwin")
+    args = build_args(stealth_args=True, extra_args=None)
+    assert "--use-gl=egl" in args
+    assert "--enable-gpu-rasterization" in args
+    assert "--enable-features=VaapiVideoDecoder" not in args
+
+
+def test_gpu_accel_kwarg_adds_flags(monkeypatch):
+    """gpu_accel=True enables GPU flags without the environment variable."""
+    monkeypatch.delenv("CLOAKBROWSER_GPU_ACCEL", raising=False)
+    monkeypatch.setattr(sys, "platform", "linux")
+    args = build_args(stealth_args=True, extra_args=None, gpu_accel=True)
+    assert "--use-gl=egl" in args
+    assert "--enable-gpu-rasterization" in args
+    assert "--ignore-gpu-blocklist" in args
+    assert "--enable-features=VaapiVideoDecoder" in args
+
+
 def test_override_logs_debug(caplog):
     """Should log debug message when an override happens."""
     import logging