How to Migrate Browser Run to Cloudflare Containers for Faster, More Scalable Performance

Introduction

Browser Run, a powerful tool for controlling headless browsers on Cloudflare's global network, recently underwent a major infrastructure upgrade. By moving from shared infrastructure with Browser Isolation (BISO) to Cloudflare's Durable Object (DO)-enabled Containers (now in open beta), it achieved 4x higher concurrency limits (up to 120 simultaneous browsers), 50% faster Quick Action response times, and the ability to spin up 60 browsers per minute via the Workers binding. This how-to guide walks through the step-by-step migration process Cloudflare used, so you can replicate a similar upgrade for your own services or simply understand the approach. Whether you're a developer looking to optimize a headless browser solution or a platform engineer exploring containerization at scale, these steps offer a proven path to better performance and reliability.

What You Need

• A Cloudflare account with access to Workers and Containers (Durable Object-enabled)
• An existing Browser Run service or a similar headless browser setup that uses shared infrastructure
• Familiarity with JavaScript/TypeScript for Workers and basic container lifecycle management
• Monitoring tools to compare performance metrics (e.g., startup time, latency, concurrency)
• A staging environment for gradual rollout (optional but recommended)

Step-by-Step Migration Guide

Step 1: Identify Bottlenecks in Your Current Infrastructure

Before migrating, analyze your existing setup. In the original Browser Run architecture, shared resources with Browser Isolation (BISO) caused three key issues:

• Slow startup due to larger container images designed for long-running sessions.
• Suboptimal global distribution that increased latency and reduced resiliency.
• Scaling bottlenecks from a mismatch between BISO's steady, lengthy sessions and Browser Run's short, spiky usage patterns.

Document your current performance baselines—concurrent browser limits, request rates, response times, and any availability delays. This data will help you measure improvement after migration.

Step 2: Prepare Your Target Platform – Cloudflare Durable Object-Enabled Containers

Cloudflare’s Durable Object-enabled Containers (DO Containers) offer a more flexible and scalable foundation. They provide:

• Faster container startup times suitable for short-lived browser sessions.
• Better global distribution across Cloudflare’s network.
• Independent scaling per workload, avoiding conflicts with other services like BISO.

To prepare, ensure you have access to the open beta. Create a base container image optimized for headless browser operations—smaller footprint, pre-installed browser dependencies (e.g., Chromium, Puppeteer). Test it locally with wrangler or the Cloudflare dashboard.

Step 3: Insert a Worker as a Dual-Support Layer

Cloudflare's migration used a Worker in front of incoming requests to route traffic both to legacy BISO-based browsers and to new Container-based browsers. This dual-support architecture is crucial for a gradual rollout because it:

• Lets you compare performance side by side.
• Isolates implementation bugs before full cutover.
• Gives you confidence through real-world testing with a subset of users.

Write a simple routing Worker (e.g., using fetch handlers) that sends a small percentage of traffic to the new containers. Example logic:

async function handleRequest(request) {
  const useContainer = Math.random() < 0.1; // 10% of traffic
  if (useContainer) {
    return fetch(request, { backend: 'container-backend' });
  }
  return fetch(request, { backend: 'biso-backend' });
}

Deploy the Worker and monitor for errors or latency spikes.

Step 4: Migrate Quick Actions Endpoints First

Once the dual-support layer is stable, start moving specific endpoints. Quick Actions (e.g., screenshots, PDF rendering, content extraction) are ideal first candidates because they:

• Are stateless and short-lived.
• Have high volume and benefit most from lower latency.
• Provide immediate performance wins to validate the approach.

Configure your routing Worker to direct 100% of Quick Actions traffic to Container-based browsers. Measure response times—Cloudflare reported a >50% drop after this step.

Step 5: Expand to Free and Pay-as-You-Go Tiers

With Quick Actions stable, extend the migration to cover Workers browser binding connections, starting with free accounts, then pay-as-you-go. This phased approach spreads risk:

• Free accounts typically have lower usage and can tolerate minor issues.
• Pay-as-you-go adds more traffic but with billing limits to contain impact.
• Each phase validates stability under increasing load.

Update your Worker to route eligible accounts (based on plan type) to the new containers. Continue monitoring for errors and performance.

Step 6: Complete Cutover to All Contract Customers with Zero User Action

After validation across all tiers, roll out to contract (enterprise) customers. The key goal is zero required action from users—existing Worker code and bindings continue to work without redeployment. Achieve this by:

• Ensuring the routing Worker handles all traffic transparently.
• Updating backend references from BISO to Containers in the Worker's logic.
• Gradually increasing the percentage of Container traffic over a few days while monitoring support tickets.

Once 100% traffic is on Containers, decommission the legacy BISO infrastructure if no longer needed. Document the new limits (60 browsers/min per binding, 120 concurrent) for your users.

Tips for a Successful Migration

1. Embrace gradual rollout. The dual-support Worker approach allows safe comparison and bug isolation—don't skip it.
2. Monitor both systems simultaneously. Collect metrics on startup time, request latency, error rates, and concurrency usage from both legacy and new systems.
3. Optimize container images early. Smaller images reduce cold start times and improve global distribution speed.
4. Communicate improvements externally. Share the new limits and speed gains with your user base (as Cloudflare did) to build trust and encourage adoption.
5. Plan for future features. With faster shipping cycles on Containers, prioritize fixes and new capabilities (e.g., AI agent integration) that leverage the improved infrastructure.

By following these steps, you can replicate Browser Run's successful migration to Cloudflare Containers, unlocking better performance, higher scalability, and faster iteration. The result: a more reliable headless browser service that meets the demands of modern web testing, security analysis, and AI interactions.