feat: connect to remote browser services

packages/browser-crawler/src/internals/browser-crawler.ts

@@ -393,6 +393,12 @@ export abstract class BrowserCrawler<
         this.browserPool = new BrowserPool<InternalBrowserPoolOptions>({
             ...(browserPoolOptions as any),
         });
+
+        // Read maxOpenBrowsers from the remote browser config and apply it to the pool.
+        const remoteMaxBrowsers = this.browserPool.browserPlugins[0]?.remoteBrowser?.maxOpenBrowsers;
+        if (remoteMaxBrowsers) {
+            this.browserPool.maxOpenBrowsers = remoteMaxBrowsers;
+        }
     }
 
     protected override buildContextPipeline(): ContextPipeline<
@@ -673,6 +679,13 @@ export abstract class BrowserCrawler<
             return;
         }
 
+        // Remote browsers are expensive — don't retire them when a session retires.
+        // Let retireBrowserAfterPageCount control the browser lifecycle instead.
+        // See also: PR #3605 which fixes the root cause (maxUsageCount: 1 in BasicCrawler).
+        if (browserController.launchContext.isRemote) {
+            return;
+        }
+
         let sessionIds = this.browserSessionIds.get(browserController);
 
         if (sessionIds) {
@@ -703,6 +716,16 @@ export abstract class BrowserCrawler<
      * Function for cleaning up after all requests are processed.
      * @ignore
      */
+    protected override async _isTaskReadyFunction(): Promise<boolean> {
+        // Don't start new tasks if browser pool is at its limit and no active browser has capacity.
+        // AutoscaledPool will retry automatically when a browser closes and frees a slot.
+        if (!this.browserPool.hasFreeBrowserSlot() && !this.browserPool.hasActiveBrowserWithFreeCapacity()) {
+            return false;
+        }
+
+        return super._isTaskReadyFunction();
+    }
+
     override async teardown(): Promise<void> {
         await this.browserPool.destroy();
         await super.teardown();

packages/browser-crawler/src/internals/browser-launcher.ts

@@ -113,6 +113,7 @@ export abstract class BrowserLauncher<
         userDataDir: ow.optional.string,
         launchOptions: ow.optional.object,
         userAgent: ow.optional.string,
+        remoteBrowser: ow.optional.object,
     };
 
     static requireLauncherOrThrow<T>(launcher: string, apifyImageName: string): T {

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

@@ -141,6 +141,7 @@ export abstract class BrowserController<
             this.log.debug(`Could not close browser.\nCause: ${(error as Error).message}`, { id: this.id });
         }
 
+        await this._releaseRemoteBrowser();
         this.emit(BROWSER_CONTROLLER_EVENTS.BROWSER_CLOSED, this);
 
         setTimeout(() => {
@@ -158,9 +159,26 @@ export abstract class BrowserController<
     async kill(): Promise<void> {
         await this.hasBrowserPromise;
         await this._kill();
+        await this._releaseRemoteBrowser();
         this.emit(BROWSER_CONTROLLER_EVENTS.BROWSER_CLOSED, this);
     }
 
+    /**
+     * Calls `remoteBrowser.release()` if configured. Safe to call multiple times —
+     * clears the endpoint after the first call so release only fires once.
+     */
+    private async _releaseRemoteBrowser(): Promise<void> {
+        const endpoint = this.launchContext?._resolvedRemoteEndpoint as string | undefined;
+        if (!endpoint) return;
+
+        const context = this.launchContext._remoteContext as Record<string, unknown> | undefined;
+
+        // Clear so release only fires once (close() schedules kill() after timeout)
+        this.launchContext.extend({ _resolvedRemoteEndpoint: undefined, _remoteContext: undefined });
+
+        await this.browserPlugin._callRelease(endpoint, context);
+    }
+
     /**
      * Opens new browser page.
      * @ignore

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

@@ -4,6 +4,7 @@ import merge from 'lodash.merge';
 
 import type { LaunchContextOptions } from '../launch-context.js';
 import { LaunchContext } from '../launch-context.js';
+import { RemoteBrowserProvider } from '../remote-browser-provider.js';
 import type { UnwrapPromise } from '../utils.js';
 import type { BrowserController } from './browser-controller.js';
 
@@ -44,6 +45,67 @@ export interface CommonPage {
     url(): string | Promise<string>;
 }
 
+/**
+ * Return type for dynamic endpoint functions that need to pass session
+ * metadata to the `release()` callback.
+ */
+export interface RemoteBrowserEndpointResult {
+    /** The browser endpoint URL to connect to. */
+    url: string;
+    /** Opaque metadata passed back to `release()` — e.g. session IDs, API tokens. */
+    context?: Record<string, unknown>;
+}
+
+/**
+ * Configuration for connecting to a remote browser service.
+ *
+ * **Static endpoint (e.g. Browserless):**
+ * ```typescript
+ * { endpoint: 'wss://browserless.io?token=xxx' }
+ * ```
+ *
+ * **Dynamic endpoint with lifecycle (e.g. Browserbase):**
+ * ```typescript
+ * {
+ *     endpoint: async () => {
+ *         const session = await createSession();
+ *         return { url: session.connectUrl, context: { id: session.id } };
+ *     },
+ *     release: async ({ context }) => {
+ *         await releaseSession(context.id);
+ *     },
+ * }
+ * ```
+ */
+export interface RemoteBrowserConfig {
+    /**
+     * The browser endpoint URL, or an async function that returns one.
+     * When a function is provided, it is called once per browser launch (not per page).
+     *
+     * Can return a plain string or an object with `url` and optional `context`
+     * that will be forwarded to `release()`.
+     */
+    endpoint: string | (() => string | RemoteBrowserEndpointResult | Promise<string | RemoteBrowserEndpointResult>);
+    /**
+     * Optional cleanup function called when the browser closes, crashes, or the pool is destroyed.
+     * Receives the resolved endpoint URL and the `context` object returned by `endpoint()`.
+     * Errors are caught and logged as warnings — they never crash the crawler.
+     */
+    release?: (info: { endpoint: string; context?: Record<string, unknown> }) => void | Promise<void>;
+    /**
+     * Connection type. Subclass interfaces narrow this further
+     * (e.g. Puppeteer only allows `'cdp'`).
+     * @default 'cdp'
+     */
+    type?: 'cdp' | 'websocket';
+    /**
+     * Maximum number of browsers that can be open at the same time.
+     * When the limit is reached, the crawler waits for a browser to close before launching a new one.
+     * Set this to your remote service's concurrent session limit to avoid 429 errors.
+     */
+    maxOpenBrowsers?: number;
+}
+
 export interface BrowserPluginOptions<LibraryOptions> {
     /**
      * Options that will be passed down to the automation library. E.g.
@@ -81,6 +143,15 @@ export interface BrowserPluginOptions<LibraryOptions> {
      * This is useful when using HTTPS proxies with self-signed certificates.
      */
     ignoreProxyCertificate?: boolean;
+    /**
+     * Configuration for connecting to a remote browser service.
+     * When set, the plugin connects to a remote browser instead of launching a local one.
+     *
+     * Accepts either a {@link RemoteBrowserConfig} object or a {@link RemoteBrowserProvider} instance.
+     *
+     * Takes precedence over `connectOverCDPOptions` / `connectOptions` if both are set.
+     */
+    remoteBrowser?: RemoteBrowserConfig | RemoteBrowserProvider<any>;
 }
 
 export interface CreateLaunchContextOptions<
@@ -116,6 +187,7 @@ export abstract class BrowserPlugin<
     browserPerProxy?: boolean;
 
     ignoreProxyCertificate?: boolean;
+    remoteBrowser?: RemoteBrowserConfig;
 
     constructor(library: Library, options: BrowserPluginOptions<LibraryOptions> = {}) {
         const {
@@ -125,6 +197,7 @@ export abstract class BrowserPlugin<
             useIncognitoPages = false,
             browserPerProxy = false,
             ignoreProxyCertificate = false,
+            remoteBrowser,
         } = options;
 
         this.log = serviceLocator.getLogger().child({ prefix: 'BrowserPool' });
@@ -135,6 +208,53 @@ export abstract class BrowserPlugin<
         this.useIncognitoPages = useIncognitoPages;
         this.browserPerProxy = browserPerProxy;
         this.ignoreProxyCertificate = ignoreProxyCertificate;
+
+        // Normalize RemoteBrowserProvider instances into a plain RemoteBrowserConfig
+        // so all downstream code only deals with the config shape.
+        if (remoteBrowser instanceof RemoteBrowserProvider) {
+            const provider = remoteBrowser;
+            this.remoteBrowser = {
+                endpoint: () => provider.connect(),
+                release: ({ context }) => provider.release(context as any),
+                type: provider.type,
+                maxOpenBrowsers: provider.maxOpenBrowsers,
+            };
+        } else {
+            this.remoteBrowser = remoteBrowser;
+        }
+    }
+
+    /** Resolves the remote browser endpoint from a string or function. Returns { url, context }. */
+    protected async _resolveRemoteEndpoint(): Promise<RemoteBrowserEndpointResult> {
+        const { endpoint } = this.remoteBrowser!;
+        const result = typeof endpoint === 'function' ? await endpoint() : endpoint;
+        if (typeof result === 'string') {
+            return { url: result };
+        }
+        return result;
+    }
+
+    /** @internal Called by BrowserController on browser close/kill. */
+    async _callRelease(endpoint: string, context?: Record<string, unknown>): Promise<void> {
+        try {
+            await this.remoteBrowser?.release?.({ endpoint, context });
+        } catch (err) {
+            this.log.warning('remoteBrowser.release() failed.', { error: (err as Error)?.message });
+        }
+    }
+
+    /** Strips credentials from a URL for safe logging. */
+    protected _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>';
+        }
     }
 
     /**
@@ -155,6 +275,7 @@ export abstract class BrowserPlugin<
             browserPerProxy = this.browserPerProxy,
             ignoreProxyCertificate = this.ignoreProxyCertificate,
             proxyTier,
+            isRemote,
         } = options;
 
         return new LaunchContext({
@@ -167,6 +288,7 @@ export abstract class BrowserPlugin<
             browserPerProxy,
             ignoreProxyCertificate,
             proxyTier,
+            isRemote,
         });
     }
 
@@ -190,15 +312,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 +340,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/browser-pool.ts

@@ -303,6 +303,7 @@ export class BrowserPool<
 > extends TypedEmitter<BrowserPoolEvents<BrowserControllerReturn, PageReturn>> {
     browserPlugins: BrowserPlugins;
     maxOpenPagesPerBrowser: number;
+    maxOpenBrowsers: number;
     retireBrowserAfterPageCount: number;
     operationTimeoutMillis: number;
     closeInactiveBrowserAfterMillis: number;
@@ -395,6 +396,7 @@ export class BrowserPool<
 
         this.browserPlugins = browserPlugins as unknown as BrowserPlugins;
         this.maxOpenPagesPerBrowser = maxOpenPagesPerBrowser;
+        this.maxOpenBrowsers = Infinity;
         this.retireBrowserAfterPageCount = retireBrowserAfterPageCount;
         this.operationTimeoutMillis = operationTimeoutSecs * 1000;
         this.closeInactiveBrowserAfterMillis = closeInactiveBrowserAfterSecs * 1000;
@@ -860,6 +862,28 @@ export class BrowserPool<
         }
     }
 
+    /**
+     * Returns `true` if the pool can accept a new browser launch without exceeding
+     * {@link BrowserPoolOptions.maxOpenBrowsers}. Counts starting, active, and retired browsers.
+     */
+    hasFreeBrowserSlot(): boolean {
+        const total =
+            this.startingBrowserControllers.size +
+            this.activeBrowserControllers.size +
+            this.retiredBrowserControllers.size;
+        return total < this.maxOpenBrowsers;
+    }
+
+    /**
+     * Returns `true` if any active browser has room for another page.
+     */
+    hasActiveBrowserWithFreeCapacity(): boolean {
+        for (const controller of this.activeBrowserControllers) {
+            if (controller.activePages < this.maxOpenPagesPerBrowser) return true;
+        }
+        return false;
+    }
+
     private _initializeFingerprinting(): void {
         const { useFingerprintCache = true, fingerprintCacheSize = 10_000 } = this.fingerprintOptions;
         this.fingerprintGenerator = new FingerprintGenerator(this.fingerprintOptions.fingerprintGeneratorOptions);

packages/browser-pool/src/fingerprinting/hooks.ts

@@ -19,6 +19,9 @@ export function createFingerprintPreLaunchHook(browserPool: BrowserPool<any, any
     } = browserPool;
 
     return (_pageId: string, launchContext: LaunchContext) => {
+        // Remote browsers may have their own fingerprinting — skip local fingerprint injection
+        if (launchContext.isRemote) return;
+
         const { useIncognitoPages } = launchContext;
         const cacheKey = (launchContext.session as { id: string } | undefined)?.id ?? launchContext.proxyUrl;
         const { launchOptions }: { launchOptions: any } = launchContext;
@@ -62,6 +65,7 @@ export function createFingerprintPreLaunchHook(browserPool: BrowserPool<any, any
 export function createPrePageCreateHook() {
     return (_pageId: string, browserController: BrowserController, pageOptions: any): void => {
         const { launchContext, browserPlugin } = browserController;
+        if (launchContext.isRemote) return;
         const { fingerprint } = launchContext.fingerprint!;
 
         if (launchContext.useIncognitoPages && browserPlugin instanceof PlaywrightPlugin && pageOptions) {
@@ -80,6 +84,7 @@ export function createPrePageCreateHook() {
 export function createPostPageCreateHook(fingerprintInjector: FingerprintInjector) {
     return async (page: any, browserController: BrowserController): Promise<void> => {
         const { browserPlugin, launchContext } = browserController;
+        if (launchContext.isRemote) return;
         const fingerprint = launchContext.fingerprint!;
 
         // TODO this will require refactoring, we should use common API instead of branching based on plugin type,

packages/browser-pool/src/index.ts

@@ -43,9 +43,12 @@ export type {
     CommonLibrary,
     BrowserPluginOptions,
     CreateLaunchContextOptions,
+    RemoteBrowserConfig,
+    RemoteBrowserEndpointResult,
 } from './abstract-classes/browser-plugin.js';
 export { BrowserPlugin, BrowserLaunchError, DEFAULT_USER_AGENT } from './abstract-classes/browser-plugin.js';
 export type { LaunchContextOptions } from './launch-context.js';
 export { LaunchContext } from './launch-context.js';
+export { RemoteBrowserProvider } from './remote-browser-provider.js';
 export type { InferBrowserPluginArray, UnwrapPromise } from './utils.js';
 export { anonymizeProxySugar, type AnonymizeProxySugarOptions } from './anonymize-proxy.js';