Kernel browsers

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

#Install

npm install mayura @mayurajs/browser-kernel

#Credentials

Create an API key in the Kernel dashboard under API Keys. The package sends it as a bearer token. It reads nothing from the environment: pass the key in yourself, for example from KERNEL_API_KEY.

#Use it

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

const browsers = createBrowsers(kernelBrowsers({ apiKey: process.env.KERNEL_API_KEY ?? '', region: 'eu-west' }), {
  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 {
  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 Kernel is called. See Browsers for per-run browsers, every method and every tool.

#Options

#Browsers

• Each browser is created when you open it, with your viewport, and deleted when you release it.
• Kernel keeps a browser running for as long as something is connected, so it has no timeout of its own to give: createBrowsers keeps the lifetime and releases the browser when it ends.
• Once nothing is connected (your process stopped, say), Kernel deletes the browser after standbyTimeoutSeconds, 60 by default. That ends a browser whose release never came.
• release() deletes the browser. One Kernel deleted already answers 404, which createBrowsers counts as released.
• Stealth is off, since in Kernel it also turns on a captcha solver. No proxy is used.
• labels become the browser's tags.

#Live view and CDP

liveViewUrl is Kernel's live view, a link with a token in it: treat it as a secret. By default the package adds readOnly=true, so it only shows the browser; liveView: 'interact' lets whoever has the link use it too. Kernel's live view needs a browser with a screen, so with liveView: false the browser runs headless and has none.

The CDP endpoint is Kernel's CDP WebSocket URL, which must be wss:// (plain ws:// only on this machine). Treat it as a secret: Kernel 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 Kernel's HTTP status. Nothing Kernel wrote reaches the message.

Configuration mistakes, such as an unknown region or a standby timeout under 10 seconds, fail with INVALID_CONFIG when you call kernelBrowsers(), before anything is sent.

#How it is tested

• Unit tests run the package against a fake Kernel browsers API that checks every request: the body with stealth off, the standby timeout, headless without a live view, labels as tags, the read-only live view, the delete, and failures mapped without Kernel'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-kernel.mjs runs the suite's public-page checks on a real Kernel 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.
• Hyperbrowser browsers: sessions with stealth and recording off.
• Stagehand tools: natural-language tools on a Kernel browser.