Hyperbrowser browsers

Hyperbrowser runs hosted Chromium sessions you drive over the Chrome DevTools Protocol. @mayurajs/browser-hyperbrowser plugs Hyperbrowser into mayura/browser, so agents get Hyperbrowser sessions through the same createBrowsers limits, origins and tools as the Chrome installed on your machine. It creates and stops sessions over Hyperbrowser's sessions API with fetch and drives them over CDP: no Hyperbrowser SDK, no other dependencies, and it runs on every runtime Mayura runs on.

#Install

npm install mayura @mayurajs/browser-hyperbrowser

#Credentials

Create an API key in the Hyperbrowser dashboard under API Keys. The package sends it as the x-api-key header. It reads nothing from the environment: pass the key in yourself, for example from HYPERBROWSER_API_KEY.

#Use it

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

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

const browser = await browsers.open({ lifetimeMs: 10 * 60_000 });
try {
  console.log(browser.liveViewUrl); // view only, with a token in it: treat it as a secret
  await browser.goto('https://example.com/');
  console.log((await browser.snapshot()).text);
} finally {
  await browser.release();
}

// 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 Hyperbrowser is called. See Browsers for per-run browsers, every method and every tool.

#Options

#Sessions

• Each browser is one Hyperbrowser session, created when you open it with your viewport as its screen size.
• Sessions are not kept alive: a session also stops when its connection does.
• The browser's lifetime becomes the session's timeout in whole minutes (1 to 720, rounded up), so Hyperbrowser stops it even if a release never comes.
• release() stops the session. If that is refused, the package asks for the session's status: one that is closed or error counts as released, and one Hyperbrowser no longer knows fails with gone, which createBrowsers treats as released. One Hyperbrowser failed to close (close-error) does not count, as it may still run.
• Off in every session: proxies, stealth, web and video recording, and saved downloads. Captcha solving and ad blocking are off unless you turn them on.
• Hyperbrowser has no labels for sessions, so labels are not sent.

#Live view and CDP

liveViewUrl is Hyperbrowser's live view, a link with a token in it: treat it as a secret. By default it only shows the session (viewOnlyLiveView); liveView: 'interact' lets whoever has the link use the browser too.

The CDP endpoint is Hyperbrowser's WebSocket endpoint, which must be wss:// (plain ws:// only on this machine). Treat it as a secret: Hyperbrowser does not say what it carries, and Mayura never logs it. Each session 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 session 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 Hyperbrowser's HTTP status. Nothing Hyperbrowser wrote reaches the message.

Configuration mistakes, such as a region with spaces or a lifetime under a minute or over 12 hours, fail with INVALID_CONFIG when you call hyperbrowserBrowsers(), before anything is sent.

#How it is tested

• Unit tests run the package against a fake Hyperbrowser sessions API that checks every request: the session body with proxies, stealth, captchas, recording and saved downloads off, timeouts in whole minutes, the live view's mode, the stop, and failures mapped without Hyperbrowser's text.
• The browser conformance suite runs against sessions served by the Chrome or Edge installed on the test machine behind that fake API.
• scripts/live/browser-hyperbrowser.mjs runs the suite's public-page checks on a real Hyperbrowser session (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.
• Kernel browsers: another hosted browser with a view-only live view.
• Live browser viewer: a live view for any browser, local ones included.