feat: connect to remote browser services

packages/browser-pool/src/abstract-classes/browser-plugin.ts

@@ -155,6 +155,7 @@ export abstract class BrowserPlugin<
             browserPerProxy = this.browserPerProxy,
             ignoreProxyCertificate = this.ignoreProxyCertificate,
             proxyTier,
+            isRemote,
         } = options;
 
         return new LaunchContext({
@@ -167,6 +168,7 @@ export abstract class BrowserPlugin<
             browserPerProxy,
             ignoreProxyCertificate,
             proxyTier,
+            isRemote,
         });
     }
 
@@ -190,15 +192,23 @@ export abstract class BrowserPlugin<
             NewPageResult
         > = this.createLaunchContext(),
     ): Promise<LaunchResult> {
+        // launchOptions is only used by the local launch path below — remote connections ignore it.
         launchContext.launchOptions ??= {} as LibraryOptions;
 
         const { proxyUrl, launchOptions } = launchContext;
 
-        if (proxyUrl) {
+        if (proxyUrl && launchContext.isRemote) {
+            this.log.warning(
+                'proxyUrl is set but will be ignored for remote browser connections. ' +
+                    'Configure proxy settings on the remote browser service instead.',
+            );
+        }
+
+        if (proxyUrl && !launchContext.isRemote) {
             await this._addProxyToLaunchOptions(launchContext);
         }
 
-        if (this._isChromiumBasedBrowser(launchContext)) {
+        if (!launchContext.isRemote && this._isChromiumBasedBrowser(launchContext)) {
             // This will set the args for chromium based browsers to hide the webdriver.
             (launchOptions as Dictionary).args = this._mergeArgsToHideWebdriver(launchOptions!.args);
             // When User-Agent is not set, and we're using Chromium in headless mode,
@@ -210,6 +220,10 @@ export abstract class BrowserPlugin<
             }
         }
 
+        if (launchContext.isRemote) {
+            this.log.info('Connecting to remote browser (skipping local proxy and webdriver stealth configuration).');
+        }
+
         return this._launch(launchContext);
     }
 

packages/browser-pool/src/launch-context.ts

@@ -57,6 +57,12 @@ export interface LaunchContextOptions<
      * This is useful when using HTTPS proxies with self-signed certificates.
      */
     ignoreProxyCertificate?: boolean;
+    /**
+     * Whether this launch context represents a connection to a remote browser
+     * rather than a locally launched one.
+     * @default false
+     */
+    isRemote?: boolean;
 }
 
 export class LaunchContext<
@@ -73,6 +79,7 @@ export class LaunchContext<
     browserPerProxy?: boolean;
     userDataDir: string;
     proxyTier?: number;
+    readonly isRemote: boolean;
     ignoreProxyCertificate?: boolean;
 
     private _proxyUrl?: string;
@@ -92,6 +99,7 @@ export class LaunchContext<
             userDataDir = '',
             proxyTier,
             ignoreProxyCertificate,
+            isRemote,
         } = options;
 
         this.id = id;
@@ -102,6 +110,7 @@ export class LaunchContext<
         this.userDataDir = userDataDir;
         this.proxyTier = proxyTier;
         this.ignoreProxyCertificate = ignoreProxyCertificate ?? false;
+        this.isRemote = isRemote ?? false;
 
         this._proxyUrl = proxyUrl;
     }

packages/browser-pool/src/playwright/playwright-plugin.ts

@@ -1,8 +1,13 @@
 import fs from 'node:fs';
 
-import type { Browser as PlaywrightBrowser, BrowserType } from 'playwright';
-
-import { BrowserPlugin } from '../abstract-classes/browser-plugin.js';
+import type { Browser as PlaywrightBrowser, BrowserType, ConnectOverCDPOptions, ConnectOptions } from 'playwright';
+
+import {
+    BrowserLaunchError,
+    BrowserPlugin,
+    type BrowserPluginOptions,
+    type CreateLaunchContextOptions,
+} from '../abstract-classes/browser-plugin.js';
 import { anonymizeProxySugar } from '../anonymize-proxy.js';
 import type { createProxyServerForContainers } from '../container-proxy-server.js';
 import type { LaunchContext } from '../launch-context.js';
@@ -11,6 +16,29 @@
 import { PlaywrightBrowser as PlaywrightBrowserWithPersistentContext } from './playwright-browser.js';
 import { PlaywrightController } from './playwright-controller.js';
 
+/**
+ * Options for connecting to a remote browser via CDP.
+ * Mirrors `browserType.connectOverCDP(endpointURL, options?)`.
+ */
+export interface PlaywrightConnectOverCDPOptions extends ConnectOverCDPOptions {
+    /** The CDP endpoint URL to connect to (required). Overrides the deprecated optional `endpointURL` from Playwright. */
+    endpointURL: string;
+}
+
+/**
+ * Options for connecting to a remote browser via WebSocket.
+ * Mirrors `browserType.connect(wsEndpoint, options?)`.
+ */
+export interface PlaywrightConnectOptions extends ConnectOptions {
+    /** The WebSocket endpoint URL to connect to (required). */
+    wsEndpoint: string;
+}
+
+export interface PlaywrightPluginOptions extends BrowserPluginOptions<SafeParameters<BrowserType['launch']>[0]> {
+    connectOptions?: PlaywrightConnectOptions;
+    connectOverCDPOptions?: PlaywrightConnectOverCDPOptions;
+}
+
 export class PlaywrightPlugin extends BrowserPlugin<
     BrowserType,
     SafeParameters<BrowserType['launch']>[0],
@@ -19,7 +47,96 @@
     private _browserVersion?: string;
     _containerProxyServer?: Awaited<ReturnType<typeof createProxyServerForContainers>>;
 
+    connectOptions?: PlaywrightConnectOptions;
+    connectOverCDPOptions?: PlaywrightConnectOverCDPOptions;
+
+    constructor(library: BrowserType, options: PlaywrightPluginOptions = {}) {
+        const { connectOptions, connectOverCDPOptions, ...baseOptions } = options;
+
+        if (connectOptions && connectOverCDPOptions) {
+            throw new Error("Cannot set both 'connectOptions' and 'connectOverCDPOptions' — pick one protocol.");
+        }
+
+        if (connectOverCDPOptions && !connectOverCDPOptions.endpointURL) {
+            throw new Error("'connectOverCDPOptions.endpointURL' must be a non-empty string.");
+        }
+
+        if (connectOptions && !connectOptions.wsEndpoint) {
+            throw new Error("'connectOptions.wsEndpoint' must be a non-empty string.");
+        }
+
+        super(library, baseOptions);
+        this.connectOptions = connectOptions;
+        this.connectOverCDPOptions = connectOverCDPOptions;
+
+        // We check options.useIncognitoPages (not this.useIncognitoPages) because super() collapses undefined to false.
+        // This preserves the distinction between "not set" (undefined → default to true) and "explicitly false".
+        if (this.connectOptions || this.connectOverCDPOptions) {
+            if (options.useIncognitoPages === undefined) {
+                this.useIncognitoPages = true;
+                this.log.info('Remote browser detected — defaulting useIncognitoPages to true for session isolation.');
+            } else if (options.useIncognitoPages === false) {
+                const message = this.connectOptions
+                    ? 'useIncognitoPages is set to false with a remote WebSocket connection. ' +
+                      'This may cause errors because browserType.connect() returns a browser with no default context.'
+                    : 'useIncognitoPages is set to false with a remote browser connection. ' +
+                      'Pages will share cookies and storage on the remote browser instance.';
+                this.log.warning(message);
+            }
+        }
+    }
+
+    override createLaunchContext(options: CreateLaunchContextOptions<BrowserType> = {}): LaunchContext<BrowserType> {
+        return super.createLaunchContext({
+            ...options,
+            isRemote: options.isRemote ?? !!(this.connectOptions || this.connectOverCDPOptions),
+        });
+    }
+
+    private _sanitizeEndpointForLog(endpoint: string): string {
+        try {
+            const url = new URL(endpoint);
+            if (url.username || url.password) {
+                url.username = '***';
+                url.password = '***';
+            }
+            return url.toString();
+        } catch {
+            return '<invalid URL>';
+        }
+    }
+
     protected async _launch(launchContext: LaunchContext<BrowserType>): Promise<PlaywrightBrowser> {
+        // Remote CDP connection — skip all local launch/proxy logic
+        if (this.connectOverCDPOptions) {
+            const { endpointURL, ...options } = this.connectOverCDPOptions;
+            this.log.info('Connecting to remote browser via connectOverCDP.');
+            try {
+                return await this.library.connectOverCDP(endpointURL, options);
+            } catch (cause) {
+                throw new BrowserLaunchError(
+                    `Failed to connect to remote browser via CDP at "${this._sanitizeEndpointForLog(endpointURL)}". ` +
+                        'Check that the endpoint is reachable and the browser is accepting CDP connections.\n\u200b',
+                    { cause },
+                );
+            }
+        }
+
+        // Remote Playwright WebSocket connection — skip all local launch/proxy logic
+        if (this.connectOptions) {
+            const { wsEndpoint, ...options } = this.connectOptions;
+            this.log.info('Connecting to remote browser via connect (Playwright WebSocket).');
+            try {
+                return await this.library.connect(wsEndpoint, options);
+            } catch (cause) {
+                throw new BrowserLaunchError(
+                    `Failed to connect to remote browser via WebSocket at "${this._sanitizeEndpointForLog(wsEndpoint)}". ` +
+                        'Check that the endpoint is reachable and the Playwright server is running.\n\u200b',
+                    { cause },
+                );
+            }
+        }
+
         const { launchOptions, useIncognitoPages, userDataDir, proxyUrl } = launchContext;
         let browser: PlaywrightBrowser;