OS emulation

BrowserQL 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.

Prerequisites

• A Browserless API token from your account dashboard
• Familiarity with BrowserQL basics

emulationOs is a URL query parameter on the endpoint — it is not a header, a launch option, or a mutation, and it behaves identically whether you call BQL over HTTP POST or WebSocket. It works on any regional endpoint.

Emulating an OS on BQL routes

Every BQL route — /chromium/bql, /chrome/bql, and /stealth/bql — runs a stealth-hardened browser. emulationOs selects the operating system identity the session presents: pass windows or macos to apply that platform's full fingerprint stack, or omit it to keep the native Linux identity.

# Windows identity on /stealth/bql
curl -X POST \
  'https://production-sfo.browserless.io/stealth/bql?token=YOUR_API_TOKEN_HERE&emulationOs=windows' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "mutation { goto(url: \"https://example.com\") { status } }"
  }'

Accepted values

Value	Emulated identity
windows	Windows / Chrome on Win64
macos	macOS / Chrome on Intel Mac
linux	Native Linux identity (the default when omitted)

Only desktop Windows and macOS identities are supported — mobile OS emulation (Android, iOS) is not available. Any unrecognized value (a mobile OS name, a typo, or wrong casing) is silently ignored and the session runs as native Linux with no error, so verify navigator.platform if you're unsure the value took effect.

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, or Linux 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. It 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.
• WebRTC handling — applied uniformly to every stealth session.

A Windows 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.

Using with the BQL IDE

In the BQL IDE, select the Stealth browser (which uses /stealth/bql) and append emulationOs to the endpoint URL in your session settings:

https://production-sfo.browserless.io/stealth/bql?token=YOUR_API_TOKEN_HERE&emulationOs=macos

Without emulationOs the session keeps the native Linux identity; append &emulationOs=windows or &emulationOs=macos to switch.

Using with the WebSocket BQL route

The BQL WebSocket route speaks GraphQL over WebSocket: send { "query": "..." } JSON messages and read { "data": ... } replies (this is not CDP, so Puppeteer/Playwright clients don't apply here). Pass emulationOs in the connection URL. From Node.js with the ws package:

import WebSocket from "ws";

const TOKEN = "YOUR_API_TOKEN_HERE";

const ws = new WebSocket(
  `wss://production-sfo.browserless.io/stealth/bql?token=${TOKEN}&emulationOs=windows`
);

ws.on("open", () => {
  ws.send(JSON.stringify({
    query: `mutation { goto(url: "https://example.com") { status } }`,
  }));
});

ws.on("message", (data) => console.log(JSON.parse(data.toString())));

Combining with other BQL features

emulationOs composes with other BQL mutations:

• userAgent() mutation overrides the User-Agent for the rest of the session. For a desktop Windows or macOS Chrome/Chromium User-Agent, navigator.platform and UA Client Hints are derived from it automatically to stay coherent; a Linux, mobile, or non-Chromium User-Agent is applied as-is and leaves the emulated platform and Client Hints unchanged — so keep the User-Agent consistent with the emulated OS.
• proxy mutation adds a residential or datacenter proxy. The OS fingerprint and proxy are independent layers — match the proxy region to the emulated OS for a coherent timezone and locale.
• solve() mutation for CAPTCHA solving works normally on emulated sessions.

mutation {
  goto(url: "https://protected-site.com") { status }
  solve(wait: true) { solved }
}

The above query, sent to /stealth/bql?emulationOs=windows, runs with a full Windows identity and solves any detected CAPTCHA.

FAQ & Troubleshooting

Does emulationOs work without a stealth or BQL route?

No. On plain WebSocket routes (/chromium, /chrome), the parameter passes through the query filter but no stealth hardening is injected, so the spoofing never takes effect. Use a /stealth route or a /bql route.

Can I verify what OS identity my session is reporting?

Yes. Use a JavaScript evaluate in BQL to check the exposed APIs:

mutation {
  goto(url: "https://example.com") { status }
  evaluate(content: "JSON.stringify({ platform: navigator.platform, ua: navigator.userAgent })")
}

With emulationOs=windows, this returns {"platform":"Win32","ua":"Mozilla/5.0 (Windows NT 10.0; Win64; x64) ..."}.

Next Steps

Stealth Route

How the /stealth/bql route and BQL stealth hardening work.

Proxies

Add residential proxies for IP-level evasion alongside OS emulation.

Solving CAPTCHAs

Handle Cloudflare, reCAPTCHA, and other challenges automatically.