Scaling Browser Run with Cloudflare Containers: A Complete Migration Guide

Overview

Browser Run is a powerful platform that lets developers programmatically control headless browser instances on Cloudflare’s global network. Use cases include end-to-end testing, URL security investigations, PDF rendering, screenshot capture, content extraction, and increasingly, enabling AI agents to interact with the web.

Scaling Browser Run with Cloudflare Containers: A Complete Migration Guide — Source: blog.cloudflare.com

Recently, the team rebuilt Browser Run on top of Cloudflare Containers, resulting in dramatic improvements: you can now spin up 60 browsers per minute via the Workers binding and run up to 120 concurrently — a 4x increase over the previous limit. Additionally, Quick Action response times dropped by more than 50%. These enhancements are live today with zero changes required on your part.

This guide walks you through the migration process from a shared infrastructure (Browser Isolation, BISO) to Container‑powered browsers. You’ll learn the step‑by‑step approach used, common pitfalls to avoid, and how to achieve similar scalability for your own projects.

Prerequisites

Before diving into the migration, ensure you have the following:

A Cloudflare account with access to Cloudflare Workers and Durable Objects (DO).
Familiarity with headless browser automation (e.g., Puppeteer, Playwright).
Basic understanding of Worker bindings and container orchestration concepts.
Access to both Browser Run and any legacy BISO infrastructure for testing.

No manual reconfiguration is needed for existing Browser Run users — the migration is transparent. However, if you’re building a similar solution, you’ll need to prepare your environment for dual support as described below.

Step‑by‑Step Migration Guide

1. Assess Current Infrastructure

Browser Run originally shared resources with Browser Isolation (BISO). While both use similar browser technology, BISO’s container images are much larger, leading to slower startup times and slower feature delivery. More critically, BISO browsers lacked optimal global distribution, hurting latency and resilience. Browser Run’s usage pattern — short, spiky sessions — conflicted with BISO’s long, steady sessions, causing scaling bottlenecks and availability delays.

Begin by documenting your current performance metrics: browser spin‑up rates, concurrency limits, average response times, and global availability. These baselines will help you measure improvement after migration.

2. Insert a Worker for Dual Support

The team started by inserting a Worker in front of incoming request paths. This Worker acted as a traffic router, directing a subset of users to Container‑powered browsers while the rest continued using BISO browsers. This dual‑support phase was critical for comparing performance and isolating bugs without risking full downtime.

Example Worker pseudocode:

// Route a percentage of requests to Container browsers
const useContainer = Math.random() < 0.1; // start with 10%
const target = useContainer ? containerEndpoint : bisoEndpoint;
return await fetch(target, request);

Gradually increase the percentage as you gain confidence. Monitor error rates and latency closely.

3. Performance Comparison

With dual support active, you can directly compare the two approaches. Key metrics to track:

Startup time: How quickly does each approach spin up a new browser instance?
Concurrency scaling: What is the maximum number of simultaneous browsers supported without degradation?
Response latency: For Quick Actions (e.g., screenshot, PDF), measure end‑to‑end response times.
Global distribution: Check the geographic spread of endpoints and how close they are to users.

In the Browser Run migration, these comparisons revealed that Container browsers were already delivering sub‑50% lower latency and could handle 4x more concurrent sessions. Such data builds the case for full adoption.

4. Gradual Rollout

Once confidence is high, plan a phased rollout:

Quick Actions first: Switch all Quick Actions endpoints (screenshot, PDF, content extraction) to Containers.
Workers binding – free accounts: Move free‑tier users to Container browsers.
Workers binding – pay‑as‑you‑go accounts: Roll out to PAYG users after validating stability.
Contract customers: Finally, migrate remaining contract customers. No worker redeployments or user changes are required.

Throughout each phase, monitor error budgets, latency SLOs, and customer feedback. The Browser Run team took exactly this approach, ensuring a seamless transition for all users.

Common Mistakes to Avoid

Not using dual support: Migrating all at once can cause widespread failures if containers behave unexpectedly. Always run both systems in parallel for a while.
Ignoring startup time differences: Browsers on Containers start faster, but your code must handle timeouts appropriately. Don’t assume old timeout values work.
Overlooking global distribution: Simply moving to containers doesn’t guarantee optimal placement. Use Cloudflare’s global network features to ensure low‑latency edge access.
Forgetting concurrency limits: The new limit of 120 concurrent browsers (up from 30) might tempt you to launch many instances simultaneously. Plan your code to respect rate limits (60 per minute via binding) and avoid overwhelming your application.
Skipping performance baselines: Without pre‑migration metrics, you can’t prove improvement. Measure everything before and after.

Summary

Migrating Browser Run to Cloudflare Containers unlocked 4x higher concurrency (120 browsers), 50% faster Quick Action responses, and faster feature delivery. The key to success was a gradual, dual‑support rollout: first with a routing Worker, then phased adoption across endpoints and user tiers. By following the same methodology, you can scale your own browser automation workloads on Cloudflare’s platform without disrupting users.

For existing Browser Run users, these improvements are already live — simply continue using the Workers binding as before. For those building similar solutions, use this guide as a blueprint for your migration journey.

Tags: