Firecrawl browsers and web tools

Firecrawl turns web pages into data for models, and hosts browsers you can drive. @mayurajs/browser-firecrawl brings both to Mayura:

• firecrawlBrowsers: browsers for mayura/browser, as Firecrawl Interact sessions driven over CDP, with the same createBrowsers limits, origins and tools as the Chrome installed on your machine.
• firecrawlTools: Firecrawl's web data as permission-gated tools, kept to the origins you allow: scrape a page, map a site and, when enabled, search the web, crawl a site or extract structured data. See Web data without a browser.

Both talk to Firecrawl's v2 API with fetch: no Firecrawl SDK, no other dependencies, and they run on every runtime Mayura runs on.

#Install

npm install mayura @mayurajs/browser-firecrawl

#Credentials

Create an API key (it starts with fc-) in the Firecrawl 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 FIRECRAWL_API_KEY.

#Use the tools

import { createRuntime, defineAgent, z } from 'mayura';
import { firecrawlTools } from '@mayurajs/browser-firecrawl';

const web = firecrawlTools({
  apiKey: process.env.FIRECRAWL_API_KEY ?? '',
  origins: ['https://docs.example.com'],
  crawl: true,
  maxCrawlPages: 20,
  costMicros: { scrape: 1_000, map: 1_000, crawl: 20_000 },
});

const researcher = defineAgent({
  id: 'docs.researcher',
  version: '1',
  instructions: 'Answer from the documentation at https://docs.example.com. Use web.map to find pages and web.scrape to read them.',
  input: z.object({ question: z.string() }),
  output: z.object({ answer: z.string() }),
  tools: web,
  model,
});

const runtime = createRuntime({
  profile: 'ephemeral',
  permissions: {
    allow: ['model:openai.responses', 'tool:web.scrape', 'tool:web.map', 'tool:web.crawl', 'effect:read', 'web:web:read', 'web:web:crawl'],
  },
  limits: { maxCostMicros: 200_000 },
});
const outcome = await runtime.submit(researcher, { input: { question: 'How do I rotate keys?' } }).result();

Every tool reads (effects: 'read'), so a call needs tool:<name>.<tool>, effect:read and the tool's permission:

#Tool options

#What the tools do

• Origins. Every URL a tool reads must be within origins; one outside them comes back as the tool's result, { error: 'PERMISSION_DENIED', message }, so the model can choose another. Search results are not bound by origins, but reading them is. A crawl stays on its site (no external links, no subdomains), and pages a redirect took elsewhere are left out.
• Off-machine. Firecrawl fetches the pages from its own servers, with TLS checked (Firecrawl's own default skips it), main content only. Page content is the tools' result for the model to read: treat it as untrusted text.
• Limits. Content is cut at maxPageBytes and marked truncated: true. Extracted data larger than that comes back as a LIMIT_EXCEEDED result.
• Crawls. A crawl polls Firecrawl every 2 seconds until it completes. One cancelled with the run, or running past crawlTimeoutMs, is cancelled at Firecrawl too, so it stops spending.
• Extraction uses Firecrawl's JSON format on one page, with Firecrawl's model.
• Costs. costMicros charges each call to the run's budget; Firecrawl bills credits on its side.

#Use the browsers

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

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

const browser = await browsers.open({ lifetimeMs: 5 * 60_000 });
try {
  console.log(browser.liveViewUrl); // view only: 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; see the browser guide for the grants they need.
const perRun = browserPerRun(browsers);
const tools = browserTools(perRun.source, { name: 'site', act: true });

#Browser options

#Sessions

• Each browser is one Interact session, created when you open it and deleted when you release it. Firecrawl ends it at its lifetime (given as its ttl in seconds, at least 30) or after activityTimeoutSeconds without activity.
• release() deletes the session. One deleted already answers 404 (gone), which createBrowsers counts as released.
• The session is not given your viewport or labels; createBrowsers sets the viewport over CDP.
• The CDP endpoint must be wss:// (plain ws:// only on this machine). Treat it as a secret, as Firecrawl's docs differ on what it carries: 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 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

Browsers fail with a BrowserError whose reason is mapped from Firecrawl's HTTP status, without anything Firecrawl wrote: authentication (401, 403), quota (402), rate_limited (429), gone (404, 410), timeout (408, 504), unavailable (5xx), rejected (other refusals), and invalid_response when a reply lacks a session id or a secure CDP URL.

Tool calls fail the call, again without Firecrawl's text, except for mistakes the model can put right:

Configuration mistakes, such as missing origins, a tool name with spaces or maxCrawlPages over 100, fail with INVALID_CONFIG when you call firecrawlTools() or firecrawlBrowsers(), before anything is sent.

#How it is tested

• Unit tests run both against a fake Firecrawl API that checks every request: the tools' permissions and costs, TLS checked, truncation, origins refused as results, map and search bodies, crawls polled, kept to their site and cancelled when cancelled, timed out or failed, extraction bounded, a call blocked without its permission, and the Interact session's ttl, live views and delete.
• 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-firecrawl.mjs runs the suite's public-page checks on a real Interact session (live view, opening and snapshotting a page, origins enforced, following a link and a screenshot): all passed on October 6, 2026. The same script also calls scrape, map and extract against Firecrawl.

#Related

• Browsers: limits, origins, per-run browsers and tools.
• Cloudflare quick actions: Browser Run's markdown, links, scrape, screenshot, JSON and crawl as tools.
• Permissions: how tool:, effect: and capability grants combine.