BLOG
Browser User Agent: What It Is and How to Control It
Learn what a browser user agent is, how servers read it, and how to set or override it in Playwright, Puppeteer, and hosted Chromium sessions.

A browser user agent is the string a browser sends in the User-Agent HTTP header with every request, identifying the browser, its version, and the operating system it runs on. Servers, CDNs, and bot-detection systems read it to decide what content to return and whether to trust the client. If you run browser automation, the user agent is one of the first signals you need to understand, because a mismatch between the string you send and the browser you actually run is a common cause of blocked requests, broken layouts, and failed agent tasks.
This guide covers what the user agent string contains, how it is read on the server side, how to set it correctly in Playwright and Puppeteer, and what changes when you move automation to a hosted Chromium runtime like Remote Browser.
What a browser user agent actually is
The user agent is a single header line. A typical Chrome string looks like this:
Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36Each segment has a purpose, even the legacy ones:
- `Mozilla/5.0` — a historical token kept for compatibility. Nearly every browser sends it.
- `(Windows NT 10.0; Win64; x64)` — the platform comment: OS, architecture, and sometimes device type.
- `AppleWebKit/537.36` — the rendering engine token. Chrome and Edge still report WebKit for compatibility even though they use Blink.
- `(KHTML, like Gecko)` — another legacy compatibility token.
- `Chrome/131.0.0.0` — the actual browser and major version.
- `Safari/537.36` — a trailing token Chrome includes so naive Safari checks do not break.
The string is not a reliable fingerprint on its own. It is self-reported, trivially spoofed, and increasingly frozen by browser vendors to reduce its value for tracking. But servers still parse it, so automation that ignores it will hit edge cases.
Client Hints replaced much of the user agent
Modern Chromium browsers send User-Agent Client Hints (UA-CH) alongside the legacy string. Headers like Sec-CH-UA, Sec-CH-UA-Platform, and Sec-CH-UA-Mobile carry structured data that servers can request at different levels of detail. Chrome has been reducing the information in the classic user agent string for years and pushing sites toward Client Hints instead.
This matters for automation because a spoofed User-Agent header alone may not match the Client Hints the browser sends. If you set the header to claim Firefox but the browser still emits Chromium Client Hints, a detection system can spot the inconsistency. Consistent spoofing means aligning the header, the Client Hints, navigator.userAgent, navigator.userAgentData, and the actual rendering engine.
How servers use the user agent
Servers do three broad things with the string:
- Content negotiation. Serving mobile versus desktop layouts, WebP versus JPEG, or blocking unsupported browsers.
- Analytics and logging. Segmenting traffic by browser and OS.
- Bot detection. Flagging known automation strings, headless markers, or mismatches between the claimed browser and observed behavior.
The third use is where automation runs into trouble. A default headless Chromium session may send a string containing HeadlessChrome, which many bot-detection vendors flag immediately. Even without that marker, a user agent that claims a recent Chrome version but lacks the Client Hints, TLS fingerprint, or JavaScript behavior of that version can be scored as suspicious.
The practical takeaway: treat the user agent as one signal among several. Setting it correctly is necessary but not sufficient for reliable automation against sites that actively detect bots.
Setting the user agent in Playwright
Playwright exposes the user agent as a context option. Setting it at the context level is cleaner than mutating headers per request, because it also updates navigator.userAgent inside the page.
import { chromium } from "playwright";
const browser = await chromium.connectOverCDP(
process.env.REMOTE_BROWSER_CDP_URL as string
);
const context = await browser.newContext({
userAgent:
"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) " +
"AppleWebKit/537.36 (KHTML, like Gecko) " +
"Chrome/131.0.0.0 Safari/537.36",
viewport: { width: 1440, height: 900 },
locale: "en-US",
});
const page = await context.newPage();
await page.goto("https://example.com");
const reported = await page.evaluate(() => navigator.userAgent);
console.log(reported);
await context.close();
await browser.close();Two details matter here. First, connectOverCDP attaches to a remote Chromium instance rather than launching a local one, which is how hosted runtimes work. Second, newContext with a userAgent option sets both the outgoing header and the in-page navigator.userAgent, so client-side scripts that read the property see the same value the server sees.
If you need to override the header per request instead, use page.setExtraHTTPHeaders, but be aware this does not change navigator.userAgent and can create the exact mismatch described earlier.
Aligning Client Hints
Playwright does not automatically rewrite Client Hints when you set userAgent. If the target site checks Sec-CH-UA, you may need to set those headers explicitly:
await context.setExtraHTTPHeaders({
"Sec-CH-UA":
'"Chromium";v="131", "Not_A Brand";v="24", "Google Chrome";v="131"',
"Sec-CH-UA-Platform": '"macOS"',
"Sec-CH-UA-Mobile": "?0",
});Keep the values consistent with the user agent string. A macOS Chrome string paired with a Windows platform hint is a contradiction that detection systems can catch.
Setting the user agent in Puppeteer
Puppeteer takes a similar approach. You can pass userAgent to page.setUserAgent, which updates both the header and navigator.userAgent:
await page.setUserAgent(
"Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 " +
"(KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36"
);For Client Hints in Puppeteer, use page.setExtraHTTPHeaders or the newer userAgentMetadata option on page.setUserAgent where supported. Check the Puppeteer version you are running, because the API has changed across major releases.
Local Chrome versus hosted Chromium
The mechanics of setting a user agent are the same whether the browser runs on your laptop or on a remote host. What differs is the surrounding environment, and that environment affects whether the string is believable.
| Factor | Local Chrome | Hosted Chromium (Remote Browser) |
|---|---|---|
| User agent default | Reflects your OS and installed Chrome | Reflects the hosted image; configurable per session |
| Client Hints consistency | Native to the browser | Configurable browser settings; align headers with the string |
| IP address | Your network | Proxy settings configurable per session |
| TLS fingerprint | Matches your local stack | Matches the hosted Chromium build |
| Session isolation | Shared with your machine | Isolated per session |
| Scaling | One machine, limited concurrency | Sessions provisioned via API |
| Debugging | Local DevTools | Live viewer plus CDP access |
The user agent string is only one part of the picture. A hosted runtime lets you control the browser build, proxy, and session settings together, which is what makes a consistent identity possible. If you are still running automation on a local machine and hitting detection or scaling limits, the remote browser for AI agents guide covers the migration path.
When to override the user agent
Override the user agent when you have a specific, defensible reason:
- Testing responsive behavior. Emulate a mobile device by pairing a mobile user agent with a matching viewport and touch settings.
- Reproducing a bug. Match the exact browser version a user reported.
- Accessing content gated by browser checks. Some sites serve different markup to older browsers; a modern string avoids legacy fallbacks.
- Maintaining a consistent identity across a session. If your workflow logs in and navigates multiple pages, keep the same user agent throughout.
Do not override it to impersonate a browser you are not running. A Firefox string on a Chromium engine will fail JavaScript feature checks, CSS rendering assumptions, and Client Hints validation. The goal is consistency, not disguise.
Headless markers
Older headless Chromium builds included HeadlessChrome in the user agent. Current versions of Chrome's new headless mode report a standard Chrome string. If you are on an older build or a tool that injects the marker, override it to the standard string for the same version. Verify by loading a page and reading navigator.userAgent rather than assuming.
Production criteria for user agent handling
Before you ship automation that depends on a specific user agent, check these:
- Consistency across surfaces. The header,
navigator.userAgent, Client Hints, and the actual engine should agree. - Version currency. A string claiming Chrome 90 in 2026 is a signal in itself. Pin to a recent stable version and update on a schedule.
- Session stability. The user agent should not change mid-session. Rotating it between requests within a logged-in flow breaks server-side session assumptions.
- Proxy alignment. If you route through a proxy in a specific region, the user agent's platform and locale should be plausible for that region.
- Observability. Log the user agent each session actually sent so you can debug failures without guessing.
These criteria are easier to meet on a hosted runtime where the browser build, proxy, and session settings are configured together. The remote browser online overview explains how sessions are provisioned and what you can configure per session. For current usage limits and pricing, see /pricing.
Debugging user agent problems
When a site behaves differently under automation than in a manual browser, check the user agent first:
- Read what the page sees. Run
page.evaluate(() => navigator.userAgent)and compare it to the header your requests send. Use a request interception handler or a logging proxy to capture the outgoing header. - Check Client Hints. Inspect
navigator.userAgentDatain the page and theSec-CH-UA*headers on the wire. - Compare against a manual session. Load the same URL in a normal browser and diff the headers.
- Look for headless markers. Search the string for
Headless,Electron, or other automation tokens. - Verify the engine. A user agent claiming Safari on a Chromium build will fail feature detection. Confirm the rendering engine matches the claim.
The Chrome DevTools Protocol exposes the network layer directly, so you can inspect headers without a proxy. The CDP documentation covers the Network domain and Network.setUserAgentOverride, which is the underlying mechanism many automation libraries use. Playwright's CDP guide explains how to attach to a remote browser and drive it over the protocol.
If you are debugging a live session, the remote control browser walkthrough shows how to open the viewer and inspect a running session alongside your code.
Summary
The browser user agent is a self-reported string that servers use for content negotiation, analytics, and bot detection. It is easy to set and easy to get wrong. The reliable approach is to keep the header, navigator.userAgent, Client Hints, and the actual rendering engine consistent, pin to a current browser version, and keep the string stable across a session. In Playwright, set it at the context level; in Puppeteer, use setUserAgent and align Client Hints manually. On a hosted Chromium runtime, you can configure the browser build, proxy, and session settings together, which is what makes a consistent identity practical at scale. Start with the documentation to see what is configurable per session.