Driving Browser Profiles With Playwright Or Puppeteer
The first script most people write against an antidetect browser looks right and does the wrong thing. It calls the framework’s launch function, a browser window opens, the script visits the site and everything works. Except the window that opened is the framework’s own bundled Chromium, with a fresh temporary directory, the framework’s default viewport, no proxy and a fingerprint that belongs to the machine the script runs on. The profile, with its cookies and its carefully matched settings, is sitting unused in the antidetect app.
Getting the connection right is most of the work. Once a script is really driving the profile, the next job is making sure the framework doesn’t quietly override what the profile is supposed to present. And after that comes the harder question of what the script should be doing at all.
This piece covers the setup side. Our earlier article on what automation leaves behind looks at detection from the platform’s point of view. This one is about the plumbing between your code and your profiles, and the defaults in that plumbing that cause most of the trouble.
Launch versus connect
Playwright and Puppeteer can both work in two modes, and the difference decides everything that follows.
In launch mode, the framework starts a browser itself. It picks the executable, creates a user data directory, passes its own command-line flags and takes control from the first moment. Puppeteer downloads its own Chromium build by default. Playwright ships its own builds of Chromium, Firefox and WebKit. That’s ideal for testing your own website. It’s the wrong tool for driving a profile, because the framework’s choices replace the profile’s.
In connect mode, the browser is already running and the framework attaches to it over the Chrome DevTools Protocol, usually through a WebSocket address. Puppeteer does this with its connect function and a browserWSEndpoint. Playwright does it with connectOverCDP on its Chromium browser type. The browser keeps its own executable, its own profile directory and its own launch settings. The framework just sends it commands.
Antidetect browsers are built around connect mode. The antidetect app starts the profile with its own browser core and its own fingerprint configuration, then hands your script an address to attach to. Your code never launches anything.
If you remember one thing from this piece, make it this: when driving profiles, your script should connect, never launch. A launch call anywhere in your profile automation is almost always a bug.
The local API that starts a profile
Antidetect browsers expose a local API, usually an HTTP server listening on a port on your own machine, and it’s the bridge between your script and the profiles. The exact endpoints differ between vendors, so read your tool’s documentation, but the pattern is close to universal.
Your script sends a request to start a profile by its ID. The antidetect app launches that profile’s browser with its fingerprint, proxy and stored data. The response includes connection details, typically a WebSocket debugger URL or a port number from which the URL can be built. Your script passes that to the framework’s connect function and starts working. When it’s done, it sends a request to stop the profile, and the app closes the browser and saves the profile’s state.
Some tools also expose endpoints to create profiles, update proxy settings, list profiles or check which ones are running. Those are useful for managing a fleet, and they’re also more power than a quick script needs, so treat them with care.
Most tools require the app to be open, and often signed in, for the local API to work. Some have a headless or server mode for running without the desktop interface. Some limit API access to certain paid plans. It’s worth checking all of that before designing a workflow around it.
A small but important detail: the API usually returns before the browser is fully ready. Build in a check that the WebSocket endpoint accepts a connection before your script starts issuing commands, rather than a fixed sleep that works on your fast machine and fails on a loaded one.
Using the profile’s own context
Once connected, there’s a second trap waiting, and it’s subtler than the launch mistake.
A browser can hold several browser contexts. Each context is like a separate session with its own cookies and storage. When the antidetect app starts a profile, the profile’s cookies, local storage and logged-in sessions live in the default context, the one that was there when the browser started.
In Playwright, the natural-looking call after connecting is browser.newContext(). That creates a brand new, empty context, similar to an incognito window. Your script then opens a page in it and finds itself logged out of everything, with none of the profile’s history. Worse, if it then logs in, it creates a session in a throwaway context that disappears when the script ends. What you want instead is the existing context, available from browser.contexts(), usually the first entry.
Puppeteer has the same distinction. Pages opened through the connected browser’s default context share the profile’s storage. Pages opened in a newly created incognito-style context don’t.
There’s a fingerprint angle too. Some antidetect tools apply parts of their fingerprint configuration to the default context or its pages specifically. A fresh context created by the framework may not get the same treatment, so it can present a different set of values than the profile is supposed to. That’s the kind of inconsistency within one session that detection is built to notice.
So the rule is to work inside what the profile gives you. Use its existing context. Reuse an open tab or open new pages from that context, and leave the framework’s context-creation functions alone.
The viewport default nobody notices
This one catches almost everyone who uses Puppeteer with a profile, and it quietly undoes one of the most basic fingerprint values.
Puppeteer’s connect function takes an option called defaultViewport. If you don’t set it, it defaults to 800 by 600 pixels. Every page the script touches gets its viewport forced to that size through a DevTools emulation command. The window on screen may be large, but the page inside it reports an 800 by 600 viewport, which disagrees with the screen size the profile claims and with the window dimensions a real user would have. Set defaultViewport to null when connecting, and Puppeteer leaves the viewport alone.
Playwright’s connectOverCDP generally uses the existing context’s settings, so the viewport problem is less likely there. But if you do create a new context, Playwright applies its own default viewport of 1280 by 720 unless you pass viewport null. That’s another reason to use the existing context.
Beyond defaults, check your code for explicit calls that change page dimensions, such as setViewport in Puppeteer or setViewportSize in Playwright. They’re common in examples copied from testing tutorials, where a fixed viewport makes screenshots consistent. In profile automation, they override what the antidetect tool configured.
The reason this matters is internal consistency. The profile says the screen is one size, the window is a plausible fraction of it, and the page viewport fits inside the window. A forced 800 by 600 viewport inside a window that’s supposedly maximised on a large screen breaks that relationship, and it does so on every page the script touches, which is exactly when the platform is looking.
After connecting, open a fingerprint check page through the script and compare the reported screen, window and viewport numbers with what the profile shows when you open it by hand. They should match.
Emulation calls that fight the profile
Viewport is the most common override, but frameworks come with a whole set of emulation features, and every one of them can contradict the profile.
Playwright contexts accept options for user agent and locale, time zone and geolocation, plus display details like colour scheme, device scale factor and whether touch is supported. Puppeteer offers setUserAgent, emulateTimezone and friends, plus device descriptors that bundle a whole phone’s worth of settings. Under the hood these use DevTools emulation commands that change what the page sees.
In a testing setup these are useful. In a profile, they’re a second source of truth competing with the first. The antidetect tool has configured a user agent, a time zone and a locale that match the proxy and the rest of the fingerprint. If the script sets any of them again, one of two things happens. Either the script’s value wins and the page sees a mismatch between that value and everything else the profile reports, or the two layers conflict and the page sees different values from different APIs, which is worse.
User agent is a good example. Setting it through the framework usually changes the user agent header and the value JavaScript reads, but may not change the structured client hints the browser also sends, or the other signals that describe the browser version. The profile’s own configuration was built to keep those aligned. A script override breaks the alignment.
The rule is simple. The profile defines the fingerprint. The script doesn’t emulate anything. If you find yourself wanting to change a fingerprint value from the script, change it in the profile instead, through the antidetect tool, where it will be applied consistently.
When you copy code from framework documentation or testing guides, search it for emulation calls and delete them.
What the framework itself leaves in the page
Even a clean connection leaves traces, because the framework is talking to the browser through a debugging protocol, and that protocol was never designed to be invisible.
The best-known trace is navigator.webdriver, a property that reports whether the browser is being controlled by automation. It’s typically set when a browser is launched with automation flags. In connect mode, the antidetect app launched the browser, so whether the flag appears depends on how the app started it. Most antidetect tools take care to leave it false, but check it on your own setup rather than assuming.
Other traces come from the protocol itself. When a framework attaches, it enables various DevTools domains to track pages, frames and scripts. Some of those have side effects a page can sometimes observe, and there’s a known family of detection techniques that looks for exactly those side effects. Frameworks and antidetect vendors have made changes in response, and the details keep moving. What’s safe to say is that attaching a debugger is observable in principle, and nobody outside a given platform knows exactly which checks it runs.
Frameworks can also inject helper scripts into pages, for example to support their selector engines or bindings between your code and the page. Some of those leave objects or functions behind that a page could find.
Then there are the timing and input traces that automated interaction produces, which the next section covers.
None of this means automation is always detectable. It means the framework is a visible participant in the session, and the sensible response is to use it less, not to pile on patches.
Input that doesn’t look like hands
The way a framework clicks and types is the part of automation most likely to look wrong, because the defaults are built for speed and reliability, not for resembling a person.
A default click in either framework moves the virtual mouse straight to the centre of the element and presses it instantly. There’s no approach path, no hover, no slight offset, no pause. The events are dispatched through the DevTools input system, so they look like real input events to the page, but their pattern is unlike a hand on a mouse. A page that listens for mouse movement sees the pointer teleport.
Typing is similar. A fill call in Playwright sets the value of a field in one step. A type call sends key events one by one, with no delay unless you set one, which means a full sentence can appear in a few milliseconds. Even with a delay option, the intervals are uniform in a way human typing never is.
Scrolling, if the script does it at all, tends to be one instant jump to an element rather than a series of uneven wheel movements.
It’s tempting to fix this with helper libraries that generate curved mouse paths and randomised typing delays. They help somewhat. But as our automation traces piece argues, adding randomness to machine behaviour tends to produce a different machine pattern, not a human one, and fleet-wide use of the same helper creates a shared signature.
The more useful conclusion is about scope. Input on pages where the platform measures behaviour closely, such as login forms or the screens where you sign up and post, is exactly where scripted input is least convincing. That’s a strong argument for keeping those steps human.
Stealth plugins and double patching
Stealth plugins for Puppeteer and Playwright patch the browser from inside the page to hide automation traces and adjust fingerprint values. They were built for a specific situation: a framework-launched browser with nothing else disguising it. On an antidetect profile, they can do more harm than good.
The problem is double patching. The antidetect browser already modifies the fingerprint at the browser level, often in the browser core itself. A stealth plugin then modifies the same properties again from JavaScript. Now the page may see two layers of changes. The plugin’s JavaScript overrides can themselves be detectable, since patched functions sometimes behave slightly differently from native ones when inspected. And where the plugin and the antidetect core disagree about a value, the page can end up reading contradictory answers from different APIs.
Some stealth patches also set values that fit a generic desktop Chrome, overwriting the profile’s own choices for things like languages, plugins or hardware details.
So on antidetect profiles, I’d leave stealth plugins out entirely. The antidetect tool is the fingerprint layer. If it isn’t doing the job, the fix is a better profile or a better tool, not a second layer on top.
If you’re unsure whether something in your stack is patching values from JavaScript, open a fingerprint test page in the profile both by hand and through your script. Any value that differs between the two is being changed by the automation side, and you should find out why.
Headless and headful
Some antidetect tools include a headless mode for automated runs, so profiles can run on a server without a visible window. It’s convenient, and it deserves caution.
Historically, headless browsers differed from normal ones in many detectable ways: missing plugins, odd screen values, different rendering paths, a telltale string in the user agent. Chrome’s newer headless mode is much closer to the normal browser, and antidetect vendors put effort into making headless profiles present the same values as headful ones. But “much closer” isn’t identical, and the environment around a headless browser often gives it away anyway. A server with no display, no audio device and a software renderer produces signals no real laptop does.
Headful runs on a real desktop, even a virtual one, keep more of the environment normal. Graphics, audio, fonts and screen are all present because a desktop is present.
My practical rule is to use headless for tasks outside the platform’s measured surface. Checking that a profile still loads, collecting your own data from your own accounts, taking a screenshot for records. For anything where the session itself is being judged, keep the profile headful, on a machine with a real display environment.
Whatever you choose, test it the same way. Run the fingerprint check page in the profile headful by hand, then headless through the script, and compare. Any difference is something a platform could also notice.
Shutting down cleanly
Most profile corruption and lost sessions in automated fleets come from scripts that end badly. The script crashes or gets killed, the browser is left running or closed abruptly, and the profile’s state never gets saved properly.
A browser writes cookies and local storage to disk as it goes, but some data is only flushed on a clean close. And the antidetect app often syncs the profile to its cloud storage when the profile stops. If a script disconnects from the browser and exits without asking the app to stop the profile, the browser may keep running, or the app may think it’s still in use. If the script closes the browser directly through the framework, the app may not get the chance to save and sync.
So always stop profiles through the antidetect app’s API, not through the framework’s close function. In code, that means wrapping every session in a try and finally structure, or your language’s equivalent, so the stop request is sent even when something fails in the middle.
Watch out for the difference between disconnect and close in the frameworks. Disconnecting detaches your script and leaves the browser running. Closing tells the browser to quit. When you’re attached to a profile, disconnect first and then ask the app to stop the profile.
Handle the case where the profile is already running, for example because a previous run crashed or someone opened it by hand. Most local APIs will refuse to start a profile that’s already open, or will return the existing connection. Decide deliberately which behaviour you want. Two scripts driving one profile at once is a mess, and a human and a script in the same profile at once is worse.
Concurrency and scheduling across the fleet
Once one profile works, the temptation is to loop over the whole fleet and run them all. That’s where machine resources and fleet-level patterns both start to bite.
Each profile is a full browser. Running twenty at once on one machine can exhaust memory and CPU, and a struggling machine produces slow renders, timeouts and crashes, which in turn produce broken sessions and unsaved profiles. Find out how many profiles your machine can run comfortably with real pages loaded, then stay well under it.
The fleet-level pattern matters more. A script that starts every profile at the same minute, runs the same steps in the same order and stops them all together produces a signature across your accounts that no group of real people shares. Stagger start times. Don’t run every profile every day. Let the order vary.
Keep a run log. For every run, record the profile ID, the start and end time, the script version and the outcome. When something goes wrong across several accounts, that log tells you immediately which runs touched them and what code was running.
Build in failure handling that stops rather than retries aggressively. If a profile fails to load a page three times, the right response is usually to stop that profile and alert a person, not to keep hammering the site. Aggressive retries turn a small problem into a noisy one.
And think about what happens when your machine restarts. If a scheduler relaunches every missed run the moment the machine comes back, you’ve recreated the everyone-at-once pattern by accident.
Version drift between framework and browser
Frameworks and browsers move on separate schedules, and a profile setup that worked last month can break without any change on your side.
Each Puppeteer release is built and tested against a specific Chromium version. Each Playwright release targets specific builds of its browsers. The DevTools Protocol changes between browser versions, mostly by adding things but occasionally by changing or removing them. When your framework expects one protocol version and the antidetect browser core speaks another, most commands keep working, but some fail in odd ways. A navigation that never reports it finished. A screenshot call that throws an error nobody can find in the documentation. An event that stops firing.
Antidetect browsers make this more likely, because their cores often lag behind the latest Chrome, or jump forward several versions in one update when the vendor ships a new engine. So the framework version that matched the old core may not match the new one.
Pin your framework version in your project’s dependency file instead of letting it float to the latest release. When the antidetect vendor announces a core update, test your scripts against one profile on the new core before letting the update reach the rest of the fleet, and update the framework deliberately if you need to. Keep a note of which framework version works with which core version, since you’ll want it the next time something breaks.
It’s also worth knowing that Playwright’s connectOverCDP is documented as lower fidelity than its own protocol connection, and some features behave differently or aren’t available over CDP. That’s an accepted trade-off for driving antidetect profiles, but read the notes before relying on an advanced feature.
Securing the local API
The local API is powerful. Anything that can reach it can start your profiles, read their connection endpoints and, through those, control browsers that are logged into your accounts. It deserves the same care as the accounts themselves.
First, check where it listens. Most tools bind it to localhost, so only software on the same machine can reach it. Some let you change that to accept connections from other machines, which is useful for running scripts on a separate server. If you do that, restrict access with a firewall and put the API behind something that authenticates, like an SSH tunnel or a private network. An antidetect API exposed to the open internet is a remote control for your fleet.
Second, use the API key or token if the tool offers one, and store it the way you store other secrets, not in the script’s source code.
Third, remember that the DevTools endpoint the API hands back is also a control channel. It usually listens on a local port while the profile runs, and anything that reaches it can drive the browser. Keep it local.
Fourth, be careful with third-party code. A package you install to help with automation runs with the same access as your script. That includes access to the local API and to every profile it can start. Prefer well-known packages, pin versions and look at what you’re installing.
Finally, keep scripts that drive account profiles out of public repositories. They often contain profile IDs, API addresses and sometimes proxy details, which together describe your fleet.
Where automation should stop
The technical setup is the easy part. The harder decision is which tasks to hand to a script at all, and the answer depends on the platform’s rules as much as on detection.
Many platforms prohibit automated access to their consumer interfaces in their terms of service. Automating inside a logged-in account can break those terms regardless of whether it’s detected, and it puts the account at risk in a way no fingerprint work can fix. Before automating anything inside an account, check the rules and check for a sanctioned route. Business APIs, official schedulers and built-in tools for managing several accounts exist precisely so people don’t need to script the consumer interface.
Tasks outside the platform’s measured surface are the natural home for automation. Confirming each profile still opens and its proxy still resolves to the right place. Running the fingerprint and leak checks on a schedule. Backing up profiles. Exporting your own data where the platform offers it. Updating your fleet records.
Inside an account, the steps platforms watch hardest are the ones where scripted behaviour stands out most: sign-ups, logins, verification, posting, messaging and anything involving payments. Those are where a human should be at the keyboard. A useful compromise is to let a script do the preparation, opening the right profile, navigating to the right page, loading the content, and leave the final action to a person.
And some things don’t belong in any script. Solving or bypassing verification challenges, creating accounts in bulk, or anything meant to get around a platform’s enforcement is outside what this site covers or supports.
The honest limit
Connecting a framework to a profile correctly removes a set of self-inflicted problems: the wrong browser and the wrong context, forced viewports, emulation overrides and stealth plugins patching on top of the profile. That’s worth doing properly, because those mistakes are common and they’re easy to fix once you know where they are.
It doesn’t make automation invisible. The debugging protocol is observable in principle, scripted input rarely resembles hands, and fleets running the same code share a pattern. How much any platform looks for these things is unknown from the outside and changes over time. Some tolerate a lot. Some tolerate very little.
So treat the setup as hygiene and the scope decision as the real control. Get the connection clean, test it against a fingerprint check page, then automate the work around the accounts far more readily than the work inside them.
I run Singapore mobile proxy and cloud phone farms myself, and the automation we lean on sits mostly around the accounts rather than inside them. For the rest of the stack, from profile setup to scheduling a fleet so it doesn’t look scripted, head to the Multi Account Ops home page.
Get new guides and videos first — join the Telegram channel.