Introduction
Browser Run allows developers to programmatically control headless browsers on Cloudflare’s global network for tasks like end-to-end testing, URL investigation, PDF rendering, screenshot capture, and AI agent interactions. Recently, Browser Run was rebuilt on Cloudflare’s Containers, resulting in a 4x increase in concurrent browser limits (up to 120), 60 browsers per minute via Workers binding, and over 50% reduction in Quick Action response times. This guide walks you through the exact migration process that made these improvements possible, helping you replicate the performance gains with your own Browser Run deployment.
What You Need
- A Cloudflare account with access to Durable Object (DO)-enabled Containers (available in open beta).
- An existing Browser Run setup (or equivalent headless browser automation) running on shared infrastructure (e.g., alongside Browser Isolation).
- Familiarity with Cloudflare Workers and basic configuration.
- Optional: Test accounts (free, pay-as-you-go, contract) for gradual rollouts.
Step-by-Step Migration Guide
Step 1: Evaluate Current Infrastructure Bottlenecks
Begin by analyzing your existing setup. Browser Run previously shared resources with Browser Isolation (BISO), which caused slower startup times, uneven global distribution, and scaling conflicts due to differing usage patterns (long steady sessions vs. short spiky loads). Identify similar bottlenecks in your environment—such as container image size, latency, or availability delays—to justify migration.
Step 2: Deploy Durable Object–Enabled Containers
Cloudflare’s DO-enabled Containers provide isolated, scalable runtimes. Follow the open beta documentation to provision containers optimized for headless browser instances. Ensure your container images are lean—unlike BISO’s larger images—to speed up cold starts and simplify updates.
Step 3: Insert a Worker for Gradual Traffic Routing
Place a Cloudflare Worker in the incoming request path. This Worker will act as a traffic splitter, sending a subset of users to the new Container-powered browsers while keeping the rest on the old BISO infrastructure. This dual-support phase allows side-by-side performance comparison and bug isolation without disrupting existing users.
Step 4: Enable Dual Support and Compare Metrics
Activate both systems concurrently. Use the Worker to route small test groups—starting with internal or low-risk traffic—to Containers. Monitor key metrics: startup time, response latency, concurrency limits, and error rates. Gather data to validate that Containers deliver the promised improvements (e.g., 50% faster Quick Action responses).
Step 5: Migrate Quick Actions Endpoints First
Once confident, switch all Quick Actions (screenshots, PDF generation, content extraction) to Containers. These short-lived, high-frequency operations benefit most from Containers’ rapid scaling and reduced latency. Verify that no regressions occur before expanding.
Step 6: Roll Out to Workers Binding Users—Free Then Paid
Next, enable Container browsers for users connecting via the Workers binding. Start with free accounts (lower stakes), then progress to pay-as-you-go accounts. Monitor stability and fine-tune container resource allocations as needed. This incremental approach ensures any issues are caught early without affecting paying customers.
Step 7: Complete Migration for Contract Customers
After validating with free and pay-as-you-go tiers, switch all remaining contract customers to Containers. Because the Worker-based routing is transparent, no customer action or re-deployment of existing Workers is required—the change happens seamlessly server-side.
Step 8: Measure and Optimize Post-Migration
After full migration, reassess performance. You should see higher concurrent browser limits (up to 120), faster spin-up rates (60 browsers per minute), and improved global latency. Use Cloudflare’s analytics to continuously monitor and adjust container settings for peak efficiency.
Tips for Success
- Start small: Use a Worker to test with a handful of users first. This minimizes risk and provides real-world performance data.
- Compare before and after: Keep BISO operational during dual support to directly measure improvements.
- Optimize container images: Smaller images lead to faster cold starts and simpler updates.
- Leverage dogfooding: Use your own platform (e.g., Cloudflare on Cloudflare) to catch and fix issues before customers encounter them.
- Plan for spiky usage: Containers handle short, bursty workloads better than shared infrastructure designed for steady sessions.
- Monitor and iterate: Continue tracking performance after migration; further tuning—like adjusting concurrent limits—can yield additional gains.