OS emulation
Browserless sessions run on Linux, so they expose a Linux fingerprint by default. Bot detection systems cross-check signals like the User-Agent, navigator.platform, UA Client Hints, GPU renderer, and media devices, and flag sessions where these don't line up. The emulationOs query parameter switches the session to a coherent operating system identity — set it to windows or macos to move off the default Linux fingerprint, or to android or ios to present a phone or tablet.
- A Browserless API token from your account dashboard
Visual learner? Check out this video Is Your Web Scraper Getting Blocked? Try This OS Emulation for a step-by-step tutorial.
emulationOs is a URL query parameter you add to the endpoint. It works on stealth routes (/stealth, /chromium/stealth, /chrome/stealth), on the unblock and scrape REST APIs (/unblock, /chromium/unblock, /chrome/unblock, /smart-scrape), on BQL routes, and on the Agent route (/chromium/agent), on any regional endpoint. It is not a header, a launch option, or a mutation. Anywhere else, including plain /chromium or /chrome routes, it has no effect: the parameter is ignored and the session runs with its default identity.
Accepted values
| Value | Emulated identity |
|---|---|
windows | Windows / Chrome on Win64 |
macos | macOS / Chrome on Intel Mac |
linux | Native Linux identity (the default when omitted) |
android | Mobile Chrome on Android — see Android (mobile) emulation |
ios | Mobile Safari on an iPhone or iPad — see iOS (mobile and tablet) emulation |
Desktop windows, macos, and linux and mobile android and ios identities are supported. Values are case-sensitive and must match exactly. Any other value, including a typo or wrong casing like macOS, is rejected with an HTTP 400 and the session doesn't start.
What gets spoofed
When emulationOs is set, the session presents one internally consistent set of signals for the target OS:
- User-Agent (e.g.
Windows NT 10.0; Win64; x64) - UA Client Hints —
Sec-CH-UA-Platform,Sec-CH-UA-Platform-Version,getHighEntropyValues() navigator.platform—Win32,MacIntel, orLinux x86_64- GPU / WebGL renderer and CPU core count (
navigator.hardwareConcurrency) for the platform - Media devices, speech-synthesis voices, and AudioContext latency for the OS
These signals stay consistent for the session's lifetime, including across navigations and new windows.
What it doesn't change
emulationOs only sets OS-derived browser signals. What stays untouched depends on the identity.
Desktop identities
For windows, macos, and linux, emulationOs does not change:
- Timezone, locale, and
Accept-Language— these follow your proxy's location, not the emulated OS. - Screen and viewport size — set these on the client (
defaultViewport/setViewport). - WebRTC handling — applied uniformly to every stealth session.
Android emulation
emulationOs=android does set screen and viewport size: it applies a high-DPI mobile viewport (see Android (mobile) emulation). Everything else stays the same as desktop. It does not change:
- Timezone, locale, and
Accept-Language— these follow your proxy's location, not the emulated OS. - WebRTC handling — applied uniformly to every stealth session.
iOS emulation
emulationOs=ios also sets screen and viewport size from the device profile (see iOS (mobile and tablet) emulation), so screen and deviceScaleFactor are ignored. It does not change:
- Timezone, locale, and
Accept-Language— these follow your proxy's location, not the emulated OS. - WebRTC handling — applied uniformly to every stealth session.
An emulated identity served with a mismatched timezone or locale is itself a detection signal, so pair emulationOs with a region-matched proxy for a fully coherent profile.
Usage with stealth routes
Stealth routes (/stealth, /chromium/stealth, /chrome/stealth) already run the full stealth stack. Adding emulationOs shifts the whole identity to the target OS:
- Puppeteer
- Playwright
import puppeteer from "puppeteer-core";
const TOKEN = "YOUR_API_TOKEN_HERE";
const browser = await puppeteer.connect({
browserWSEndpoint:
`wss://production-sfo.browserless.io/stealth?token=${TOKEN}&emulationOs=windows`,
});
const page = await browser.newPage();
const platform = await page.evaluate(() => navigator.platform);
console.log(platform); // "Win32"
await browser.close();
- Javascript
- Python
import { chromium } from "playwright-core";
const TOKEN = "YOUR_API_TOKEN_HERE";
const browser = await chromium.connectOverCDP(
`wss://production-sfo.browserless.io/stealth?token=${TOKEN}&emulationOs=windows`
);
const context = browser.contexts()[0] || (await browser.newContext());
const page = await context.newPage();
const platform = await page.evaluate(() => navigator.platform);
console.log(platform); // "Win32"
await browser.close();
import asyncio
from playwright.async_api import async_playwright
TOKEN = "YOUR_API_TOKEN_HERE"
async def main():
async with async_playwright() as p:
browser = await p.chromium.connect_over_cdp(
f"wss://production-sfo.browserless.io/stealth?token={TOKEN}&emulationOs=windows"
)
context = browser.contexts[0] if browser.contexts else await browser.new_context()
page = await context.new_page()
platform = await page.evaluate("navigator.platform")
print(platform) # "Win32"
await browser.close()
asyncio.run(main())
With emulationOs=windows or macos, the session's User-Agent is authoritative: any --user-agent you pass in launch options is overridden to keep the identity coherent. To control the User-Agent yourself, omit emulationOs or use BrowserQL's userAgent() mutation.
Usage on BQL routes
BQL routes (/chromium/bql, /chrome/bql, /stealth/bql) accept emulationOs the same way, and all of them run stealth-hardened. See OS emulation in BrowserQL for BQL-specific usage.
Android (mobile) emulation
Set emulationOs=android to make the session present as mobile Chrome on Android instead of a desktop OS. Add emulatedDevice=<slug> to pick a specific phone, or omit it and Browserless picks a real device for you and keeps it consistent for the whole session. Android emulation runs on the Chromium and Brave stealth engines.
Enabling Android emulation
emulationOs and emulatedDevice are connection query-string parameters you add to the stealth connection URL, the same way you add emulationOs=windows for desktop. Add them to a /stealth connection:
wss://production-sfo.browserless.io/stealth?token=YOUR_API_TOKEN_HERE&emulationOs=android&emulatedDevice=pixel-8-pro
Omit emulatedDevice to let Browserless pick a device for you:
wss://production-sfo.browserless.io/stealth?token=YOUR_API_TOKEN_HERE&emulationOs=android
Connect Puppeteer or Playwright to that endpoint and the session runs as normal, presenting the mobile persona. The same parameters also work on BQL routes — see OS emulation in BrowserQL.
Choosing a device
emulatedDevice takes one of the supported Android slugs — for example pixel-8-pro or galaxy-s25-ultra. See Supported mobile devices for the full list. Omitting emulatedDevice is fine: Browserless picks a real device automatically and keeps it stable across reconnects within the session.
What gets emulated
emulationOs=android shifts the whole identity to a coherent mobile persona:
- Mobile User-Agent and Client Hints — the browser reports as Chrome on Android, and the specific model is exposed through UA Client Hints.
- Phone screen size and pixel ratio — a high-DPI mobile viewport.
- Touch input — coarse-pointer and no-hover behavior.
- Portrait orientation.
- Motion sensors — accelerometer, gyroscope, and orientation.
- Mobile GPU / WebGL renderer identity, Android system fonts, mobile media devices and voices, and Android-appropriate battery and network signals.
Rules and errors
emulatedDevicerequiresemulationOs=androidorios. SendingemulatedDeviceon a stealth session without one of them returns an HTTP 400 with the message:emulatedDevice requires emulationOs=android or ios on a stealth request (a /stealth/*, BQL, or /chromium/agent route).- Device slugs are case-sensitive and matched exactly. Use them as listed (
pixel-8, notPixel-8orpixel8). - An unrecognized
emulatedDevicevalue is not an error. Browserless falls back to an automatically chosen device. emulationOsaccepts only the exact lowercase valueswindows,macos,linux,android, andios. Any other value, including wrong casing likeAndroid, returns an HTTP 400.deviceType=phoneis accepted and changes nothing on Android.deviceType=tabletreturns an HTTP 400 with the message:deviceType=tablet requires emulationOs=ios on a stealth request (a /stealth/*, BQL, or /chromium/agent route).
Limitations
- Phones only. For an iPhone or iPad, use
emulationOs=ios. - All emulated devices are modern flagship phones in portrait orientation.
iOS (mobile and tablet) emulation
Set emulationOs=ios to make the session present as Safari on an iPhone. Add deviceType=tablet for an iPad, or emulatedDevice=<slug> to pick an exact model. Omit both and Browserless picks an iPhone for you and keeps it consistent for the whole session, including reconnects. iOS emulation runs on the Chromium and Brave stealth engines.
The browser underneath is Chromium with an iOS identity. It reports what an iPhone or iPad reports to the page and the network, while traits that come from the engine itself stay Chromium's (see the limitations below).
Enabling iOS emulation
emulationOs, deviceType, and emulatedDevice are connection query-string parameters, the same as for Android. Add them to a /stealth connection.
Pin an iPhone model:
wss://production-sfo.browserless.io/stealth?token=YOUR_API_TOKEN_HERE&emulationOs=ios&emulatedDevice=iphone-16
Let Browserless pick an iPad:
wss://production-sfo.browserless.io/stealth?token=YOUR_API_TOKEN_HERE&emulationOs=ios&deviceType=tablet
Pin an iPad model:
wss://production-sfo.browserless.io/stealth?token=YOUR_API_TOKEN_HERE&emulationOs=ios&emulatedDevice=ipad-pro-11
Let Browserless pick an iPhone:
wss://production-sfo.browserless.io/stealth?token=YOUR_API_TOKEN_HERE&emulationOs=ios
Connect Puppeteer with defaultViewport: null and read the identity back:
import puppeteer from "puppeteer-core";
const TOKEN = "YOUR_API_TOKEN_HERE";
const browser = await puppeteer.connect({
browserWSEndpoint:
`wss://production-sfo.browserless.io/stealth?token=${TOKEN}&emulationOs=ios&emulatedDevice=iphone-16`,
// Puppeteer's default 800x600 viewport would overwrite the device viewport.
defaultViewport: null,
});
const page = await browser.newPage();
await page.goto("https://example.com");
const identity = await page.evaluate(() =>
JSON.stringify({
platform: navigator.platform,
width: window.innerWidth,
dpr: window.devicePixelRatio,
touch: navigator.maxTouchPoints,
})
);
console.log(identity);
await browser.close();
Response:
{"platform":"iPhone","width":393,"dpr":3,"touch":5}
Playwright works the same way over chromium.connectOverCDP(). Use the browser's default context (browser.contexts()[0]), because a context from newContext() gets Playwright's default 1280×720 viewport unless you pass viewport: null. The same parameters also work on BQL routes. See OS emulation in BrowserQL.
Choosing a device and device type
deviceType picks the pool Browserless draws from when emulatedDevice is absent: phone (the default) or tablet. emulatedDevice names an exact model, and a named model decides the device. If you send both, they must agree. See Supported mobile devices for every iPhone and iPad slug.
An unrecognized emulatedDevice value is not an error. Browserless falls back to an automatically chosen device from the deviceType pool.
What gets emulated
emulationOs=ios shifts the whole identity to a coherent iPhone or iPad:
- Safari User-Agent for an iPhone or iPad, on every engine. On
/stealthand/stealth/bql, which run the Brave engine, the string ends with aBravetoken. - UA Client Hints are absent, as on every iOS browser: the session sends no
Sec-CH-UArequest headers, andnavigator.userAgentDataisundefined. navigator.platform—iPhoneoriPad, withnavigator.vendorset toApple Computer, Inc.- Device screen size and pixel ratio — a pixel ratio of 3 for iPhones and 2 for iPads.
- Touch input — five touch points and a coarse pointer.
- Portrait orientation.
- Apple GPU / WebGL renderer identity and four CPU cores (
navigator.hardwareConcurrency).navigator.deviceMemoryis absent, as in Safari. - WebKit-style page surface —
window.chromeis absent, and Chromium-specific APIs such as WebHID, Web Serial, and EyeDropper are hidden.
Rules and errors
emulatedDevicerequiresemulationOs=androidorios, as described for Android. Sending it without one of them returns an HTTP 400 with the message:emulatedDevice requires emulationOs=android or ios on a stealth request (a /stealth/*, BQL, or /chromium/agent route).deviceTypemust bephoneortablet. Any other value returns an HTTP 400 with the message:deviceType must be phone or tablet.deviceTypeneeds a mobileemulationOson a stealth request. Sending it with a desktop value or with none returns an HTTP 400 with the message:deviceType requires a mobile emulationOs (android|ios) on a stealth request (a /stealth/*, BQL, or /chromium/agent route).deviceType=tabletneedsemulationOs=ios. WithemulationOs=androidit returns an HTTP 400 with the message:deviceType=tablet requires emulationOs=ios on a stealth request (a /stealth/*, BQL, or /chromium/agent route).- A named iOS slug of the other kind, such as
emulatedDevice=ipad-pro-11&deviceType=phone, returns an HTTP 400 with the message:deviceType contradicts emulatedDevice. - Device slugs are case-sensitive and matched exactly. Use them as listed, in lowercase.
screenanddeviceScaleFactorare ignored, because the device profile sets both.deviceSlotbelongs to desktop personas, so sending it withemulationOs=iosreturns an HTTP 400. A valid slot number gets the message:deviceSlot requires a desktop emulationOs (windows|macos|linux) on a stealth request (a /stealth/*, BQL, or /chromium/agent route).
Limitations
- iOS emulation is Chromium with an iOS identity. Traits that come from the engine stay Chromium's: V8 error wording and stack shape, the TLS and HTTP/2 fingerprint, fonts, CSS feature support, and media codecs.
- The WebKit-style surface is applied to the page itself. Workers and cross-site iframes keep Chromium's.
- Safari's own engine (WebKit) is available separately through Playwright. See Supported browsers.
- Devices are the listed iPhone and iPad models, in portrait orientation.
FAQ & Troubleshooting
I set emulationOs but the site still detects me. What else can I do?
OS emulation is one layer of the stealth stack. For heavily protected sites, pair it with a region-matched residential proxy — which also aligns timezone and locale — and make sure you're on a stealth or BQL route rather than a plain /chromium connection. Some sites also fingerprint TLS and HTTP/2 traits that are independent of the OS identity.
Does emulationOs work on plain (non-stealth) WebSocket routes?
No. emulationOs only takes effect on stealth routes, the unblock and scrape REST APIs (/unblock, /chromium/unblock, /chrome/unblock, /smart-scrape), BQL routes, and the Agent route (/chromium/agent). On a plain route like /chromium or /chrome it is ignored rather than rejected, so the session silently keeps its default identity. Use a stealth route (/stealth), /unblock, /smart-scrape, a BQL route, or /chromium/agent.
Can I emulate an iPhone or iOS?
Yes. Set emulationOs=ios for an iPhone, and add deviceType=tablet for an iPad. See iOS (mobile and tablet) emulation for the rules, and Supported mobile devices for the model slugs.
Can I change emulationOs mid-session?
No. The emulated OS identity is fixed when the session is created and reused for the connection's lifetime, including across reconnects — you don't need to re-append emulationOs to a reconnect URL. (The User-Agent itself can still be replaced mid-session with BrowserQL's userAgent() mutation, but that doesn't change the emulated platform or GPU.)