Integrations / Automation libraries / Playwright
Playwright with separate browser profiles.
Playwright’s own contexts are fresh and forgetful, and every one looks like the same machine. A Browz profile is a saved browser with its own cookies, fingerprint and proxy. Start one through the local API and attach Playwright to it with connectOverCDP: your script code stays the same.
npm install playwright-core @browz/sdkSetup
Set it up.
Install Browz and open it
Download Browz. Its local API listens on 127.0.0.1:50333 while the app is open.
Install the packages
playwright-coreis enough: Browz provides the browser, so nonpx playwright install.@browz/sdkreads the app’s own token, so there is nothing to paste.Terminalnpm install playwright-core @browz/sdkStart a profile and attach
Use the default context: it is the profile’s own persistent session.
browser.newContext()would open a blank, incognito-like one instead.run.mjsimport { chromium } from 'playwright-core'; import { Browz, localCredentials } from '@browz/sdk'; const browz = new Browz(await localCredentials()); const { id } = await browz.profiles.create({ name: 'checkout-test' }); const session = await browz.browser.start(id); const browser = await chromium.connectOverCDP(session.wsEndpoint ?? session.cdpEndpoint); try { const context = browser.contexts()[0]; // the profile’s cookies and storage const page = context.pages()[0] ?? (await context.newPage()); await page.goto('https://example.com'); console.log(await page.title()); } finally { await browser.close(); // detaches; Browz keeps the browser await browz.browser.stop(id); // Browz saves and closes the profile }Run it
Terminalnode run.mjs
API from Playwright connectOverCDP.
Example
Three users at once, each in its own profile.
withBrowzSession creates a throwaway profile, starts it, runs your function and then stops, deletes and purges the profile, even when the function throws. Run several side by side: they never share a cookie.
import { chromium } from 'playwright-core';
import { withBrowzSession } from '@browz/sdk';
const users = ['buyer-1', 'buyer-2', 'buyer-3'];
await Promise.all(users.map((name) => withBrowzSession(async (session) => {
const browser = await chromium.connectOverCDP(session.cdpEndpoint);
const context = browser.contexts()[0];
const page = context.pages()[0] ?? (await context.newPage());
await page.goto('https://example.com');
console.log(name, await page.title());
await browser.close();
}, { name })));Each line prints Example Domain. Pass { keep: true } to keep a profile for the next run, or { profileId } to use one you already have.
Good to know
Notes and tips.
- Never call
chromium.launch()for a Browz profile: that starts a stock browser with automation flags and none of the profile’s fingerprint, proxy or cookies. Attach to the one Browz started. browser.close()on a CDP-connected browser only disconnects. Stop the profile through Browz so it saves its state cleanly.- Attach to the browser Browz started; never let the library launch its own. A library-launched browser is a stock one with none of the profile’s fingerprint, proxy or cookies.
- A person completes sign-ins, 2FA codes and CAPTCHAs in the profile’s window; your script can wait for the page that follows. Browz never solves or bypasses CAPTCHAs.
- Automate only where each site’s terms allow it. Our acceptable use policy applies to scripts the same as to people.
- The local API, CDP and the SDKs are on every plan, Free included (5 profiles), and are not metered.
FAQ
Playwright and Browz.
Does Playwright Test work too?
Yes. Start the profile in a fixture or globalSetup, connect with chromium.connectOverCDP, and stop the profile in teardown. Use the default context rather than Playwright’s per-test contexts, which would not be the profile.
Can I run headless?
Yes: browz.browser.start(id, { headless: true }). Profiles on the Installed Chrome engine always open a window.
Which Playwright version do I need?
Any recent one with connectOverCDP. Browz’s engine is Chromium, so use chromium, not firefox or webkit.
Get started
Download Browz. Every task, its own browser.
curl -fsSL https://gobrowz.com/agents/install.sh | sh