skip to content

Automation & Mail Services

Browser Run drives headless Chrome from a Worker, and Email Service routes inbound mail to Workers or addresses and sends mail. Interviewers ask how each is wired and limited.

on this pageshow

explore

questions

10

How does a Cloudflare Worker get a headless browser from Browser Run, and what must its Wrangler file declare?

level: juniorimportance: should knowfreq 30%

answer

  1. a binding, not an API token
  2. browser block plus nodejs_compat
  3. Cloudflare's forks of two libraries
  4. close it in finally

basics

~10 s

The Wrangler file declares a browser binding and the nodejs_compat flag; the Worker passes that binding to launch() from @cloudflare/puppeteer or @cloudflare/playwright, drives the returned browser, and calls browser.close() when it is done.

solid answer

~30 s

The Wrangler file gets a `browser` block such as `"browser": { "binding": "MYBROWSER" }` and `"compatibility_flags": ["nodejs_compat"]`. The binding is an authenticated endpoint to a Chromium instance on Cloudflare's network, so the Worker needs no API token. In code, `puppeteer.launch(env.MYBROWSER)` from `@cloudflare/puppeteer`, or `launch(env.MYBROWSER)` from `@cloudflare/playwright`, returns a browser, and the rest is the library's normal page API. Call `browser.close()` in a `finally` block: a browser that is never closed stays open until 60 seconds pass with no commands, and that time is billed. The `browser` key is not inherited by Wrangler environments, so each environment repeats it.

code

json · 9 lines
json
{
  "name": "preview-worker",
  "main": "src/index.ts",
  "compatibility_date": "2026-10-10",
  "compatibility_flags": ["nodejs_compat"],
  "browser": {
    "binding": "MYBROWSER"
  }
}

go deeper

for a junior

Recall the three pieces: a browser binding in the Wrangler file, the nodejs_compat flag, and launch() from Cloudflare's Puppeteer or Playwright fork with the binding passed in.

for a middle

Explain why no token is needed, why the forks exist, and why browser.close() belongs in a finally block given the 60-second idle timeout.

for a senior

Show you know what a first deployment trips over: the non-inheritable browser key, the Free plan's ten browser minutes a day, and launches that fail with 429.

for a principal

Frame the binding as the boundary: the Worker holds no credential, and the team decides which Workers get a browser binding at all.

## What the browser binding is **Browser Run** (formerly Browser Rendering) runs headless Chromium on Cloudflare's network. A Worker reaches it through a **binding**: a named entry on `env` that the runtime wires to the service for the Worker's own account. The binding is an authenticated endpoint, so the Worker carries no Cloudflare API token. For the scenario of this lesson, a Worker that renders invoices to PDF and screenshots customers' public pages for link previews, the binding is the first thing the project needs. ## Declaring it in the Wrangler file Three settings matter: - a `browser` block with a `binding` name of your choice (`MYBROWSER`, `BROWSER`); - the `nodejs_compat` compatibility flag, because Cloudflare's library forks use Node.js APIs; - a recent `compatibility_date`: the current `@cloudflare/playwright` needs 2025-09-15 or later, and the binding's `quickAction()` method needs 2026-03-24 or later. The `browser` key is **non-inheritable**: a named Wrangler environment such as `staging` does not pick it up from the top level and must declare its own. ## Launching a browser Browser Run ships two forks that accept the binding instead of a local DevTools port: | Library | Install | Launch call | |---|---|---| | Puppeteer | `@cloudflare/puppeteer` | `puppeteer.launch(env.MYBROWSER)` | | Playwright | `@cloudflare/playwright` | `launch(env.MYBROWSER)` | After launch, a page is opened and driven with the library's ordinary API: `browser.newPage()`, `page.goto()`, `page.screenshot()`, `page.pdf()`. The library APIs themselves are covered with Puppeteer and Playwright; what Browser Run adds is the launch, the session methods and the limits. A few fork-specific differences are worth knowing: - the Puppeteer fork does not support XPath selectors in the Workers runtime; use CSS selectors, or run XPath inside `page.evaluate()`; - the Playwright fork does not yet support everything upstream does, for example browsers other than Chromium, video recording, and Playwright Test apart from its assertions; - setting a custom user agent does not hide the browser from bot detection: Browser Run requests are always identified as a bot. ## Closing the browser Every launch starts a **browser session**. It ends in one of these ways: 1. the code calls `browser.close()` (a normal closure); 2. no command arrives for the idle timeout, 60 seconds by default and up to 10 minutes with the `keep_alive` option; 3. Browser Run ends it, for example when a new release rolls out, Chromium crashes or the client's connection drops. Until it ends, the session uses browser time. A Worker that throws before `browser.close()` leaves the browser idling, so the call belongs in a `finally` block. Leaving a browser open on purpose, so a later request can attach to it, is session reuse, which needs its own design. ## What a first Worker runs into | Limit | Workers Free | Workers Paid (defaults as of 2026-10-10) | |---|---|---| | Browser time | 10 minutes per day | 10 hours a month included, then billed per hour | | Concurrent browsers | 3 per account | 200 per account by default | | New browser instances | 1 every 20 seconds | 3 per second | On the Free plan a link-preview Worker can exhaust ten browser minutes quickly, after which launches fail with a `429` until the next UTC day. ## Puppeteer, Playwright or neither Both forks reach the same browser through the same binding, so the choice is mostly about the team's existing scripts and taste. Two version notes matter: sharing one session among several concurrent clients needs `@cloudflare/puppeteer` 1.1.0 or `@cloudflare/playwright` 1.3.0 or later, and the Playwright fork's import is a named `launch` rather than a default export. For a job that one request fully describes, such as "screenshot this URL" or "render this HTML to PDF", a third route skips the library altogether: Browser Run's **Quick Actions**, called over REST or through the same binding's `quickAction()` method, manage the browser for you. ## A checklist before the first deploy 1. The `browser` binding is declared at the top level and in every named environment. 2. `nodejs_compat` is set and the compatibility date is recent enough for the fork in use. 3. Every `launch()` has a matching `browser.close()` in a `finally` block. 4. The page timeouts leave room inside the Worker's own limits, since a Worker that dies mid-session drops its connection to the browser.

  • Why does the Worker not need a Cloudflare API token to use Browser Run?
    The `browser` binding is an authenticated endpoint the runtime wires to the Worker's own account, so the Worker never holds a credential. An API token with the `Browser Run - Edit` permission is only needed when calling Browser Run's REST endpoints from outside a Worker, for example from a CI job or another server.
  • A staging deployment of the Worker fails with env.MYBROWSER undefined although production works; why?
    The `browser` key is non-inheritable in Wrangler: a named environment does not copy it from the top level. The `staging` environment block needs its own `browser` entry with the binding name, just as it repeats KV namespaces and other bindings.

  • Browser Run needs an API token stored as a Worker secret
  • Upstream Puppeteer connects to Browser Run without the Cloudflare fork
  • The browser closes by itself when the fetch handler returns
  • A custom user agent stops Browser Run being seen as a bot
  • A browser block at the top level covers every Wrangler environment

Assumes Browser Run as of 2026-10-10, renamed from Browser Rendering on 2026-04-15; the Workers Paid defaults of 200 concurrent browsers and 3 new browsers per second date from 2026-08-20.

open as a page

In Cloudflare Email Routing, how do routing rules, the catch-all rule and verified destination addresses deliver a domain's support@ and sales@ mail?

level: juniorimportance: should knowfreq 30%

basics

~20 s

Each Email Routing rule maps one address on the domain to an action: send to a verified destination address, send to a Worker, or drop. The catch-all rule takes unmatched addresses, and rules with unverified destinations stay disabled.

open as a page

When should a team use Browser Run Quick Actions such as /screenshot and /pdf instead of driving Puppeteer, and how is a Quick Action called?

level: middleimportance: should knowfreq 25%

basics

~20 s

Use Quick Actions when one request describes the whole job, such as screenshotting a URL or rendering invoice HTML to PDF: POST to the REST endpoint with an API token, or call env.BROWSER.quickAction() from a Worker.

open as a page

In Cloudflare Browser Run, what does keep_alive change, and how does a Worker reuse a session with sessions() and connect() instead of launching per request?

level: middleimportance: should knowfreq 30%

basics

~20 s

A Browser Run browser closes after 60 idle seconds; keep_alive raises that idle timeout to at most 10 minutes. To reuse one, find it with sessions(), attach with connect(), work in a new browser context, then disconnect.

open as a page

How does a Cloudflare Worker send order confirmations through Email Service's send_email binding, and what do its restrictions and plan limits change?

level: middleimportance: should knowfreq 30%

basics

~20 s

Declare a send_email binding and call env.EMAIL.send() with from, to, subject and html or text; it resolves to a messageId. Mailing customers needs an onboarded sending domain and the Workers Paid plan; verified destination addresses are free on every plan.

open as a page

In a Cloudflare Email Worker, what do message.forward(), message.setReject() and message.reply() each do inside the email() handler?

level: middleimportance: should knowfreq 30%

basics

~20 s

An Email Worker's email(message, env, ctx) handler gets the incoming message. message.forward() relays it to a verified destination, message.setReject() sends a permanent SMTP error back to the sending server, and message.reply() sends one threaded reply to the original sender.

open as a page

A Cloudflare Worker rendering thousands of invoice PDFs a day with Browser Run gets 429 errors at peaks and a browser-hours bill far above its render time; why, and what fixes it?

level: seniorimportance: should knowfreq 25%

basics

~20 s

Each invoice launches a new browser, so peaks exceed the new-browser rate, and error paths skip browser.close(), so browsers idle until their timeout and bill it. Close in finally, reuse sessions, honour Retry-After, or use the /pdf Quick Action.

open as a page

A Cloudflare Email Worker for invoices@ allowlists vendors by message.from and calls setReject() for the rest, yet one vendor's invoices bounce; why, and how do you fix it?

level: seniorimportance: should knowfreq 20%

basics

~20 s

message.from is the envelope MAIL FROM, and a vendor's billing platform often sends with its own bounce address, so an exact allowlist on it rejects real invoices. Compare the domain of the From header instead, and log decisions before enforcing setReject().

open as a page

When a Browser Run Worker runs under wrangler dev, what does local mode simulate, and what can it not reproduce?

level: middleimportance: nice to knowfreq 15%

basics

~20 s

Under wrangler dev the browser binding launches a Chrome downloaded to your machine, so Puppeteer and Playwright code runs locally. It reports fixed limits, keeps no session history, rejects requests over 1 MB and does not implement quickAction().

open as a page

How do you test a Cloudflare Email Worker locally with wrangler dev, and which production checks does the local email simulation skip?

level: middleimportance: nice to knowfreq 20%

basics

~20 s

Run wrangler dev and POST a raw RFC 5322 message with a Message-ID header to /cdn-cgi/local/email, passing the envelope from and to as query parameters. The Worker's forward(), setReject() and reply() calls are logged; nothing is verified or delivered.

open as a page