From Bottleneck to Breakthrough: Cloudflare's Step-by-Step Migration of Browser Run to Containers

Introduction

Browser Run, Cloudflare's tool for programmatic headless browser automation, recently underwent a major transformation. By rebuilding on top of Cloudflare's own Containers (powered by Durable Objects), the service now delivers 4x higher concurrency limits, 50% faster Quick Action response times, and improved global reliability—all without requiring any changes from existing users. This guide walks through the exact step-by-step process Cloudflare's team used to migrate from shared infrastructure to a dedicated containerized platform, providing a blueprint for any team looking to modernize a latency-sensitive microservice at scale.

What You Need

• Familiarity with Cloudflare Workers and Durable Objects – understanding of request routing and state management.
• Access to Cloudflare's Container environment (open beta as of 2024) – this is the target platform.
• Existing service metrics – baseline performance data (startup times, concurrency, latency) to compare against.
• Gradual roll-out strategy – ability to route a subset of traffic to the new infrastructure while keeping the old one running.
• Monitoring/alerts – for both old and new systems, to catch regressions.

Step-by-Step Migration Guide

Step 1: Identify Infrastructure Bottlenecks

Before any migration, Cloudflare diagnosed the root issues: Browser Run was sharing infrastructure with Browser Isolation (BISO). While technically similar, BISO's larger container images slowed startup and development. More critically, BISO browsers lacked optimal global distribution, compromising resiliency and latency. And the usage patterns clashed—BISO users had long, steady sessions, while Browser Run experienced short, spiky bursts. This created scaling bottlenecks and availability delays.

Action: Document your own service's usage patterns (peak load, session duration, geographic distribution) and compare them with any co‑located services. This justifies the need for dedicated resources.

Step 2: Design a Dual‑Support Architecture

Cloudflare inserted a Worker in the incoming request path. This Worker acted as a smart router: for a controlled subset of users, it directed requests to new Container‑powered browsers; for everyone else, it continued using the old BISO browsers. This allowed side‑by‑side performance comparison and isolated any implementation bugs without affecting the majority of users.

Action: Implement a routing layer (e.g., a Cloudflare Worker) that can split traffic based on user ID, account plan, or a simple percentage flag. Use feature flags to toggle groups easily.

Step 3: Ramp Up with Quick Actions Endpoints

The migration started with the least critical part of the system: Quick Actions (screenshots, PDF generation, content extraction). These are short‑lived, stateless operations—ideal for validating container startup times and scalability. Cloudflare observed that container browsers for Quick Actions performed significantly faster, with response times dropping more than 50%.

Action: Migrate your simplest, most stateless endpoints first. Measure key performance indicators (latency, error rate, container spin‑up time) and confirm they meet or exceed the old infrastructure.

Step 4: Extend to Workers Binding – Free Accounts

Once Quick Actions were stable, Cloudflare expanded the Container browsers to serve connections made via the Workers browser binding on free accounts. Free accounts typically have lower traffic and fewer SLAs, making them a safe next step to test concurrency limits and mixed workloads.

Action: Enable the new infrastructure for a low‑risk user tier. Monitor for any unexpected interactions between the binding API and the Container environment. Use this phase to validate that the 60 browsers/minute spin‑up and 120 concurrent browser limits work as advertised.

Step 5: Validate with Pay‑As‑You‑Go Accounts

With free accounts stable, Cloudflare promoted the change to pay‑as‑you‑go (PAYG) accounts. PAYG users have higher usage patterns and may expose edge cases around billing, rate limiting, or container reclamation. This step provided confidence before the final push to all contract customers.

Action: Roll out to the next tier of users. Closely watch error logs and customer support tickets. If possible, run A/B comparisons between old and new infrastructure for the same user cohort.

Step 6: Full Migration of Contract Customers

After validating stability and performance across all other tiers, Cloudflare switched all remaining contract customers to the Container‑based browsers. Crucially, this required no action nor redeployment from customers—the existing Workers bindings continued to work seamlessly.

Action: Perform a final, gradual cutover for high‑value customers. Announce the change once it's complete, highlighting the improvements (e.g., “Your Browser Run sessions are now 4x more scalable and 50% faster – no changes needed”).

Step 7: Monitor, Iterate, and Share Learnings

Post‑migration, Cloudflare achieved its goals: higher usage limits (60 browsers/minute via Workers binding, 120 concurrent–up from 30 and 30 respectively), rapid Quick Actions, and faster release cycles for fixes and features. The team continues to build on its own platform (Dogfooding) to catch pain points before external customers do.

Action: Set up dashboards to compare pre‑ and post‑migration metrics. Document the migration process and share it internally (or externally) to assist other teams considering similar moves.

Tips and Lessons Learned

• Dogfood your own platform. By using Cloudflare's own Containers (via Durable Objects), the team could feel and fix any rough edges before releasing the feature to external customers.
• Use gradual rollout with a routing Worker. This allowed side‑by‑side comparisons and caught implementation bugs early without risking the entire user base.
• Start with the simplest endpoints. Quick Actions were the perfect proving ground—they are stateless, short‑lived, and their performance improvements were immediately measurable.
• Communicate clearly with customers. Cloudflare emphasized that no action was required from users, which minimized confusion and support load.
• Measure everything. The 50% drop in Quick Action response times and 4x concurrency increase were backed by data, making the migration's success undeniable.