Multi-Account Browser Automation With WebDriver BiDi, Not Legacy CDP
Here's a failure mode worth knowing before it finds you: a Network.requestWillBeSent handler that's worked fine for years can go quiet after a Chromium bump, and if the catch block swallows the error, the job keeps reporting success while writing nothing.
Not an error — a blank row. The call that fetches response bodies comes back empty, the exit code stays 0, and the pipeline looks healthy right up until someone opens the output CSV and finds it empty.
That's the tax on the Chrome DevTools Protocol. It's a debugger protocol that automation borrowed, it changes when the debugger changes, and nobody owes you a deprecation window. WebDriver BiDi is the W3C's answer to exactly that problem, and if you drive multi-account browser profiles from code, it's worth a weekend of your time.
Not because it makes anything faster. It doesn't. More on that below, because it's the part most BiDi posts gloss over.
What We're Building
By the end of this you'll have a Node script that:
- launches a JustBrowser profile through the REST API and grabs its endpoint
- connects Puppeteer over the BiDi protocol rather than raw CDP
- subscribes to network and console events instead of polling for them
- blocks a third-party host with
network.addIntercept— no Fetch domain, no request-stage bookkeeping - tears the profile down cleanly
Roughly 60 lines. The interesting part isn't the volume of code, it's what stops being your problem afterward.
Prerequisites
- JustBrowser installed and running, REST API answering on
127.0.0.1:36542, and an API token from the app's AI page (team seats have no API access). API access comes with the plan — $9.99/month for unlimited profiles, or $99.99/year — and it works during the 7-day trial too, not only after you convert to paid. - Node 20+ and a recent Puppeteer. BiDi support has been in Puppeteer for a while now, but the mapper it bundles gets meaningfully better with each release — if you're on something from early 2025, upgrade first.
- One profile created, with a proxy attached if the job needs one.
- Enough CDP experience to have been burned by it at least once. Honestly, that's the real prerequisite. If CDP has never broken under you, you won't find the tradeoffs here convincing.
New to driving profiles from code at all? Start with the Playwright and Puppeteer guide — this post assumes you already know what a wsEndpoint is and why you want one.
Step 1: What WebDriver BiDi Is, and What It Isn't
Quick version, because the marketing around this protocol is genuinely confusing.
WebDriver Classic is the old HTTP request-response protocol behind Selenium. You ask a question, you get an answer. That's the whole model. The browser can't volunteer anything it wasn't asked for, so waiting for a network request to finish degrades into a polling loop with a sleep in it, and anyone who has babysat one of those at 3am knows precisely how it ends.
CDP is bidirectional and event-driven and does everything, which is why everyone uses it. It's also Chromium-only, versioned by nobody, and documented as an implementation detail of a debugger.
WebDriver BiDi is the W3C spec that takes the event model from CDP and the standards process from WebDriver Classic. Commands and events over one WebSocket, organised into modules — session, browsingContext, network, script, log, storage, input. Firefox implements it natively. Chromium implements it through a mapper that translates BiDi into CDP underneath.
Read that last sentence again, because it's the thing nobody says out loud: on Chromium in 2026, BiDi still rides CDP. The mapper is a JavaScript layer that Puppeteer bundles and injects for you. You are not escaping CDP. You're putting a specified, versioned interface between your code and it, so the next time a CDP method changes shape, that's the mapper's problem rather than yours.
Which is a smaller promise than "the future of browser automation." It's also the one that matters to a pipeline that can run for days writing blank rows.
Step 2: Launch the Profile, Get the Endpoint
Nothing new here if you've used the REST API before — one POST, one field out of the response.
const API = process.env.JB_API || 'http://127.0.0.1:36542/api/v1';
const AUTH = { Authorization: `Bearer ${process.env.JB_TOKEN}` };
async function launch(profileId) {
const res = await fetch(`${API}/profiles/${profileId}/start`, {
method: 'POST',
headers: { ...AUTH, 'Content-Type': 'application/json' },
body: JSON.stringify({ headless: false }),
});
const body = await res.json();
if (!res.ok) throw new Error(`launch failed: ${body.error?.code}`);
return body.data.cdp_url;
}
async function stop(profileId) {
await fetch(`${API}/profiles/${profileId}/stop`, { method: 'POST', headers: AUTH });
}
headless: false on purpose. The start endpoint launches headless unless you say otherwise, and a headless session has no real window, so its screen and viewport follow headless defaults. If the job needs a visible window with the profile's own screen settings, ask for one. JustBrowser runs on Windows x64 and macOS (Apple Silicon), so this script lives on one of those machines.
The endpoint that comes back is a CDP WebSocket. That's fine. Puppeteer handles the rest.
Step 3: Connect Over BiDi
One property.
import puppeteer from 'puppeteer-core';
const browser = await puppeteer.connect({
browserWSEndpoint: wsEndpoint,
protocol: 'webDriverBiDi',
});
const [page] = await browser.pages();
await page.goto('https://example.com/', {
waitUntil: 'networkidle0',
});
That's it. protocol: 'webDriverBiDi' tells Puppeteer to inject the mapper and speak BiDi from there on. Your page.goto, page.click, page.evaluate calls all still work — they're just compiling down to browsingContext.navigate, input.performActions and script.callFunction now instead of CDP domains.
Flip this flag expecting a wall of breakage and, on a current Puppeteer, you'll probably find very little: request interception and page.pdf() both have BiDi paths now. Older releases had gaps, which is why the prerequisites say upgrade first — anticlimactic, given how much reading the migration seems to demand.
Grab the raw session if you want to see the wire:
const conn = browser.connection; // BiDi connection
const contexts = await conn.send('browsingContext.getTree', {});
console.log(JSON.stringify(contexts, null, 2));
Step 4: Subscribe to Events Instead of Polling
This is the part that pays for the migration.
In BiDi, events are opt-in. You declare what you want, once, and the browser pushes it:
{
"id": 1,
"method": "session.subscribe",
"params": {
"events": ["network.responseCompleted", "log.entryAdded"]
}
}
Through Puppeteer, the same idea with less ceremony:
const seen = new Map();
page.on('response', (res) => {
seen.set(res.url(), res.status());
});
page.on('console', (msg) => {
if (msg.type() === 'error') console.warn('page error:', msg.text());
});
The subscription is scoped to the session, survives navigations, and it's the same event on any browser that implements the spec, Chromium or Firefox. No per-browser branch, which CDP never offered.
One habit worth building early: log network.responseCompleted for every profile run and keep it. When a job misbehaves three weeks later, a record of what it actually loaded is the difference between a diagnosis and a shrug. Pipe it into something queryable — JustAnalytics works for this — rather than a text file nobody opens. Reconstructing a run from memory three weeks later isn't a method. It's a hobby.
Step 5: Intercept Without the Fetch Domain
Blocking a host used to mean enabling the Fetch domain, pausing every request, deciding, and continuing each one — with the fun property that if your handler ever threw, the page hung forever waiting on a request you'd promised to answer.
BiDi splits it into a declarative pattern plus a continue:
{
"method": "network.addIntercept",
"params": {
"phases": ["beforeRequestSent"],
"urlPatterns": [
{ "type": "pattern", "hostname": "cdn.tracker.example" }
]
}
}
Then handle the network.beforeRequestSent event with network.continueRequest or network.failRequest. In Puppeteer terms:
await page.setRequestInterception(true); // BiDi path
page.on('request', (req) => {
if (req.url().includes('cdn.tracker.example')) return req.abort();
return req.continue();
});
With the raw command, only requests that match a pattern you named are paused, so a thrown exception in your handler can only stall those, not every request on the page. Puppeteer's setRequestInterception(true) pauses every request, so if you use it, make sure every path through the handler ends in continue() or abort().
Worth being blunt about this one: blocking third-party scripts is a bandwidth and speed decision. It can also break pages that depend on their own analytics or consent scripts, so block narrowly and test the result.
Step 6: The Selenium Path Is Rougher
Selenium 4 has BiDi APIs — console handlers, network handlers, real event subscriptions, Java and Python and C# bindings. Good APIs. The problem is attachment.
Selenium's BiDi flow wants ChromeDriver to own the browser process, and a JustBrowser profile is launched by JustBrowser, not by ChromeDriver. So you attach the way you always have:
from selenium import webdriver
# debugger_address from GET /profiles/{id}/selenium, e.g. "127.0.0.1:PORT"
options = webdriver.ChromeOptions()
options.debugger_address = debugger_address
driver = webdriver.Chrome(options=options)
Use a ChromeDriver pinned to the engine's current Chromium major (Puppeteer's browser.version() shows it on a running profile). Otherwise Selenium Manager fetches a driver for the machine's own Chrome and the attach fails.
And what you get back is a CDP-flavoured session. The BiDi surface on an attached session has been uneven across point releases — the binding names have moved more than once, and enable_bidi on an already-running browser is not the well-trodden path. Check what your exact version does before you build on it: a working attach script dying on a routine patch bump is a real risk here, more so than with the CDP breakage this whole migration is meant to fix.
Opinion, and not everyone will like it: if you're on Selenium and driving JustBrowser profiles, stay on the existing Selenium attach flow for now and revisit in six months. The BiDi story there is real but it's aimed at people launching their own browsers. Puppeteer and WebdriverIO are further along for the attach-to-a-running-profile case, and WebdriverIO in particular has gone BiDi-first rather than bolting it on.
Common Errors and How to Fix Them
setRequestInterception fails on an older Puppeteer
You're on an older Puppeteer whose mapper doesn't cover the intercept path yet.
Fix: upgrade Puppeteer. If you can't, open a CDP session for that one call — const cdp = await page.createCDPSession() — and leave a comment saying why, because that line is now your upgrade blocker.
Events fire locally and never fire in CI
Almost always a timing problem rather than anything environmental. A listener registered after the navigation starts misses everything that already happened, and a faster or slower CI machine changes which events land before it.
Fix: attach listeners before goto. The whole fix is usually moving a few lines higher in the file — an easy afternoon to lose if you don't know to look for it.
Timezone reads correctly in the page and wrong in Intl
If you've set a timezone override through the automation layer and the profile already sets one at engine level, you now have two sources of truth and they disagree — which is worse than either alone. Your own tests will catch it when Intl.DateTimeFormat().resolvedOptions().timeZone and the reported offset don't match.
Fix: pick one layer. If the profile owns identity — and on a JustBrowser Chrome profile it does, across 40+ parameters in the C++ engine — the automation layer should override nothing.
What BiDi Doesn't Buy You
Here's the contrarian bit, and it's the reason this post exists.
BiDi doesn't change what your profile looks like. The profile's identity (canvas, WebGL, audio, fonts, screen, timezone) comes from the profile. Switching from CDP to BiDi changes the shape of the JSON on a local WebSocket, nothing more. It's a different remote control for the same television.
What it does buy: an interface with a specification and a deprecation process, one event model across Chromium and Firefox, and network interception you can scope to the requests you name. Real wins. Boring wins. Adopt it for those. If you also need to move session state between runs, the cookie export and import walkthrough covers it.
One caveat worth repeating: the mapper is a moving target, and it's reasonable to bet that "unsupported in Puppeteer" today becomes "supported next quarter." Re-test before you write a workaround — a clever one built around a gap that closes next release is wasted effort.
Next Steps
-
Port one job, not all of them. Pick the noisiest CDP consumer you own and flip it. You'll find your gaps in an afternoon instead of theorising about them for a week.
-
Keep the CDP escape hatch documented. Every
createCDPSession()in the codebase should carry a comment with the reason and the Puppeteer version you last checked. Those comments are your migration checklist later. -
Put a concurrency ceiling on it. Every profile is still a full browser process with its own memory. BiDi changes nothing there. Same rate limit and backoff patterns as before.
-
Wire events to something that outlives the run.
log.entryAddedandnetwork.responseCompletedare far more useful as a searchable history than as console output. JustBrowser has no webhooks, so if you also need a profile's state, pollGET /profiles/{id}/status.
The honest summary: the case for this migration is a spec sitting between your code and a debugger protocol that owes you nothing. It doesn't make anything faster, and it doesn't change what your profiles are.
A pipeline that reports success while writing nothing has a way of reordering your priorities.
Frequently Asked Questions
Is WebDriver BiDi actually faster than CDP for multi-account browser automation?
No, and anyone promising that is selling something. On Chromium today, BiDi commands are translated to CDP calls by a mapper layer that Puppeteer ships with, so you're paying a small translation cost on every call — usually invisible next to a page load, but it's a cost not a saving. The reason to move is the event model and the fact that BiDi is a W3C specification with a deprecation process, while CDP is a debugger protocol that changes whenever the debugger changes.
Does JustBrowser expose a native BiDi endpoint, or does Puppeteer map it?
The launch endpoint returns a CDP WebSocket — that's what the REST API gives you and what CDP-based clients connect to directly. When you pass protocol: 'webDriverBiDi' to Puppeteer, Puppeteer injects the chromium-bidi mapper over that same connection and speaks BiDi to your code while speaking CDP to the browser. Your automation code is written against the spec either way, which is the portable part.
Should I use script.addPreloadScript to override profile settings?
Don't. A preload script is JavaScript running in the page, and overriding values like navigator.hardwareConcurrency from there leaves them inconsistent with what the engine reports. On Chrome profiles, JustBrowser sets 40+ identity parameters in the C++ engine, so let the profile own them. Use preload scripts for instrumentation and timing marks.
Can I mix BiDi and CDP in the same session?
Yes, and you'll probably have to. Puppeteer exposes page.createCDPSession() even on a BiDi connection, so the handful of things with no BiDi equivalent — deep tracing, some memory and performance domains, a few Fetch-domain tricks — stay reachable. Treat it as an escape hatch and comment every use, because those are the lines that break on the next Chromium bump.
Try JustBrowser
A multi-account browser for teams — a custom Chromium engine with native C++ integration, not extension-based, patched on every upstream release. Real C++ engine patches at the canvas / WebGL / audio / font / screen layer, with 40+ identity parameters per profile. REST API for Playwright, Puppeteer, Selenium. 7-day free trial, card required — then $9.99/month or $99.99/year, unlimited profiles, free team seats.
Get started → · How it differs from Multilogin / GoLogin / AdsPower
Ready to manage multiple accounts?
Seven days free, then $9.99/month — one plan, everything included.