How to Leverage Cloudflare Browser Run for Scalable Browser Automation

Overview

Cloudflare Browser Run enables developers to programmatically control and interact with headless browser instances running on Cloudflare's global network. This service is ideal for end-to-end testing, investigating suspicious URLs, rendering PDF documents, capturing screenshots, and extracting content. Recently, it has become a critical enabler for AI agents that need to interact with the web. With the migration to Cloudflare Containers, Browser Run now offers higher usage limits, faster performance, and better reliability. You can spin up 60 browsers per minute via the Workers binding and run up to 120 concurrently—a 4x increase over previous limits. Quick Action response times have dropped more than 50%. This tutorial will guide you through using Browser Run effectively, from setup to advanced scaling strategies.

Prerequisites

Before you start, ensure you have the following:

• A Cloudflare account with Workers enabled.
• Basic knowledge of JavaScript/TypeScript and Cloudflare Workers.
• Node.js installed locally (for testing Workers scripts).
• The wrangler CLI installed globally (npm install -g wrangler).
• Your Cloudflare account must have access to Browser Run (available on all plans, with varying limits).

Step-by-Step Instructions

1. Create a New Worker

Use the Wrangler CLI to initialize a new Workers project:

wrangler init browser-run-demo --yes
cd browser-run-demo

This creates a basic Workers project. Open wrangler.toml and ensure your compatibility_date is recent (e.g., 2025-03-01).

2. Add the Browser Run Binding

In wrangler.toml, add a binding to enable Browser Run:

[[browser]]
binding = "BROWSER"

This makes the BROWSER object available in your Worker runtime.

3. Write a Basic Script to Launch a Browser

Replace the contents of src/index.ts with the following example that opens a headless browser, navigates to a URL, and takes a screenshot:

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    // Launch a new browser instance (40s timeout)
    const browser = await env.BROWSER.launch();
    try {
      const page = await browser.newPage();
      await page.setViewport({ width: 1280, height: 720 });
      await page.goto('https://example.com', { waitUntil: 'networkidle' });
      const screenshot = await page.screenshot({ fullPage: true });
      return new Response(screenshot, {
        headers: { 'Content-Type': 'image/png' },
      });
    } finally {
      await browser.close(); // Always close to release resources
    }
  },
};

interface Env {
  BROWSER: Fetcher;
}

4. Deploy and Test

Deploy your Worker:

wrangler deploy

Visit the URL provided (e.g., https://browser-run-demo.your-subdomain.workers.dev). You should see a PNG screenshot of example.com downloaded. Note: First invocation may be slower due to cold starts; subsequent calls are faster.

5. Use Quick Actions for Common Tasks

For tasks like screenshots or content extraction, you can avoid launching a full browser. Use the quickAction method:

const result = await env.BROWSER.quickAction({ url: 'https://example.com', action: 'screenshot' });
return new Response(result.data, { headers: { 'Content-Type': 'image/png' } });

Available actions: screenshot, pdf, content, links. Quick Actions are faster and more cost-effective—they have a 50% lower response time than full browser launches.

6. Manage Concurrency and Limits

You can now run up to 120 concurrent browsers per account and spin up 60 browsers per minute via the Workers binding. To avoid hitting limits:

• Use browser.close() as soon as you're done.
• Reuse browser contexts when possible (using context.close()).
• Implement a queue or rate limiter if you anticipate high demand.

// Example: Limiting to 50 concurrent browsers
const semaphore = new Semaphore(50);
const browser = await semaphore.acquire(() => env.BROWSER.launch());

7. Advanced: Gradual Migration Pattern

If you're migrating from an older setup, you can use a dual-support pattern similar to Cloudflare's own migration: insert a Worker that sends a percentage of traffic to the new Browser Run endpoints while keeping the old ones for comparison. This allows you to test performance and stability incrementally.

// Example split: 10% to new, 90% to old (pseudo-code)
if (Math.random() < 0.1) {
  // use new BROWSER binding
} else {
  // use legacy code path
}

Common Mistakes

Not Closing Browser Instances

Forgetting to call browser.close() will lead to resource leaks and eventual throttling. Always use try...finally or a disposal pattern.

Ignoring Cold Starts

The first launch may take a few seconds. For latency-sensitive applications, consider warming up instances or using Quick Actions where possible.

Overusing Full Browser Launches

Quick Actions are much faster and consume fewer resources. Only launch a full browser when you need to interact with the page (clicking, typing, etc.).

Exceeding Rate Limits

The 60 browsers per minute and 120 concurrent limit applies per account. Monitor your usage via the Cloudflare dashboard and implement backoff strategies.

Forgetting Binding Configuration

Without the [[browser]] binding in wrangler.toml, the BROWSER environment variable will be undefined at runtime, causing errors.

Summary

Cloudflare Browser Run, powered by Containers, offers a scalable and fast way to automate headless browsers. This tutorial covered setting up a Worker with the Browser Run binding, writing scripts to launch browsers and use Quick Actions, managing concurrency, and avoiding common pitfalls. With limits now 4x higher and response times halved, it's easier than ever to integrate browser automation into your workflows. Remember to close resources, leverage Quick Actions for simple tasks, and monitor your usage to stay within plan limits.