Browser Use Cloud browsers

Browser Use Cloud hosts Chromium browsers you drive over the Chrome DevTools Protocol. @mayurajs/browser-browser-use plugs those browsers into mayura/browser, so agents get them through the same createBrowsers limits, origins and tools as the Chrome installed on your machine. This is Browser Use's browser infrastructure, not its agent: your Mayura agent drives the browser. The package creates and stops browsers over Browser Use's browsers API (v2) with fetch and drives them over CDP: no Browser Use SDK, no other dependencies, and it runs on every runtime Mayura runs on.

#Install

npm install mayura @mayurajs/browser-browser-use

#Credentials

Create an API key in Browser Use Cloud under API Keys. The package sends it as the x-browser-use-api-key header. It reads nothing from the environment: pass the key in yourself, for example from BROWSER_USE_API_KEY.

#Use it

import { browserPerRun, browserTools, createBrowsers } from 'mayura/browser';
import { browserUseBrowsers } from '@mayurajs/browser-browser-use';

const browsers = createBrowsers(browserUseBrowsers({ apiKey: process.env.BROWSER_USE_API_KEY ?? '' }), {
  maxBrowsers: 2,
  maxLifetimeMs: 30 * 60_000,
  origins: ['https://example.com', 'https://*.example.com'],
});

const browser = await browsers.open({ lifetimeMs: 10 * 60_000, labels: { team: 'research' } });
try {
  await browser.goto('https://example.com/');
  console.log((await browser.snapshot()).text);
} finally {
  await browser.release(); // a Browser Use browser outlives its connection: always release it
}

// Or give each run a browser as tools. A run grants tool:web.<tool> for each tool it calls, effect:read and
// browser:web:read; actions such as web.click also need effect:write and browser:web:act.
const perRun = browserPerRun(browsers);
const tools = browserTools(perRun.source, { name: 'web', act: true });

createBrowsers enforces your limits (how many browsers, how long each lives, which origins pages may load from) before Browser Use is called. See Browsers for per-run browsers, every method and every tool.

#Options

#Browsers

• Each browser is created when you open it and stopped when you release it. Its screen is your viewport, at least 320 × 320.
• A Browser Use browser outlives its connection: only stopping ends it. The browser's lifetime becomes its timeout in whole minutes (rounded up, at most 240), so Browser Use stops one you did not release then.
• Browser Use charges for that timeout up front and refunds what a stop leaves unused.
• release() stops the browser. If that is refused, the package asks for its status: one that is gone or stopped counts as released.
• No proxy and no captcha solving, though Browser Use's own defaults are a US proxy and captcha solving on. Recording is off.
• labels become the browser's metadata, at most 10; more fail the open with INVALID_INPUT.

#Live view and CDP

There is no live view unless you pass liveView: true, because whoever has Browser Use's live link may be able to use the browser, not only watch it. Treat the link as a secret.

The CDP endpoint is Browser Use's CDP URL: a wss:// WebSocket, or an https:// address the package asks for its WebSocket URL (plain ws:// and http:// only on this machine). If that lookup fails, the browser is stopped and the open fails. Treat the URL as a secret: Browser Use does not say what it carries, and Mayura never logs it. Each browser is yours alone, so browser.cdp is there for another client, such as Stagehand, to drive it alongside.

#Origins

Origins are enforced inside the browser: Mayura intercepts every request the browser makes over CDP and blocks those to origins you did not allow, as the guide describes. Should a connection not allow that interception, opening the browser fails rather than running unchecked.

#Errors

Failures reach you as a BrowserError with a reason, mapped from Browser Use's HTTP status. Nothing Browser Use wrote reaches the message.

Configuration mistakes, such as a three-letter country code or a lifetime over 4 hours, fail with INVALID_CONFIG when you call browserUseBrowsers(), before anything is sent.

#How it is tested

• Unit tests run the package against a fake Browser Use browsers API that checks every request: the body with no proxy, captchas and recording off, timeouts in whole minutes, the minimum screen, labels as metadata, the stop, the live view only when asked, and failures mapped without Browser Use's text.
• The browser conformance suite runs against browsers served by the Chrome or Edge installed on the test machine behind that fake API.
• scripts/live/browser-browser-use.mjs runs the suite's public-page checks on a real Browser Use browser (live view, opening and snapshotting a page, origins enforced, following a link and a screenshot): all passed on October 6, 2026.

#Related

• Browsers: limits, origins, per-run browsers and tools.
• Steel browsers: another hosted browser that outlives its connection.
• Live browser viewer: a view-only live view for any browser.