Skip to Content
Platform Ontology

Headless label in the browser identity

The browser's name tag can say it is running without a screen.

Gets silentlyWhen the page loads

Headless Chrome announces itself as HeadlessChrome in the User-Agent string and in the Sec-CH-UA brand list unless the operator overrides it. Bot defenses read it first. Agents that patch the user agent often forget the client hint brands, so the two disagree and give the agent away.

What it can and can't do

What the user does: Nothing. It is sent with every request

It can

  • Read the browser name and brand list
  • Spot the HeadlessChrome label
  • Compare the user agent with client hints to find patched agents
  • Block or challenge clients that look headless

It cannot

  • Tell a real person from a well disguised agent
  • See what the script is doing
  • Prove who runs the browser
  • Stop operators from changing the label

How it differs between platforms: Operators change it with one launch flag, so a clean label proves little. A mismatch between the user agent and the client hints is the stronger clue.

Browser support

Version notes
  • Chrome: Headless mode added in Chrome 59
  • Edge: Chromium Edge headless
  • Firefox: Headless Firefox sends the normal user agent
  • Safari: No headless mode label

How a site asks for it

APInavigator.userAgent contains 'HeadlessChrome'; Sec-CH-UA brand 'HeadlessChrome'; navigator.userAgentData.brands
Browser compat keysapi.Navigator.userAgent
api.NavigatorUAData.brands
How access is grantednone
What the user seesNone
Needs a secure context (HTTPS)No
Needs a user gestureNo
How long it lastsNot listed
How to take it backNot listed
Inside an iframeNot listed

Typical flow

  1. Browser sends User-Agent and Sec-CH-UA on every request
  2. Server or page script reads the brand names
  3. Compare the label with the other headers and the JavaScript values

Data you get

Shape: string
How often: static per session

FieldTypeUnitRangePrecision
userAgentstringNonecontains HeadlessChrome/<version> in headless ChromeNot listed
Sec-CH-UAheaderNonebrand list that may include HeadlessChromeNot listed
userAgentData.brandslistNonesame brands as the header when not patchedNot listed

Technical limits

  • Trivially rewritten with a launch flag
  • A patched user agent with unpatched client hints is the stronger tell
  • Says nothing about intent

The story

What it is

Headless Chrome tells every site it has no window, in the same place it states its name and version.

For you

You never see it. Your normal browser reports its plain name. If you run an agent in headless mode, some sites challenge it on arrival.

For makers

It is the cheapest headless check and sits at the network layer, before any script runs. Check that the user agent string, the Sec-CH-UA brands and navigator.userAgentData all agree.

Where you see it

TypeExampleApps
securityA firewall serves a challenge to any request whose brand list says HeadlessChrome.Cloudflare
shoppingA ticket seller drops queue requests from headless browsers.None named
adsAn ad network does not count views from clients that report a headless brand.None named
analyticsA site analytics tool files headless visits under bots.Google Analytics
developerA tester sees the label in server logs and knows the run was headless.Puppeteer, Playwright
travelA fare site hides prices from clients that announce headless mode.None named

Risks

  • Blocks useful agents
  • Easy to hide

What the platform says

Good uses and abuse

Legitimate uses

  • Bot defense
  • Cleaner analytics

Known abuse

  • Blocking legitimate agents

Scores

ScoreValueMeaning
Sensitivity1 of 5How revealing the data is
Utility4 of 5How useful it is to honest apps
Friction0 of 5How much the user has to do
Fingerprint bits0.2Rough identifying entropy, when known

History

  • 2017-06, Chrome 59: Headless mode ships and sends a HeadlessChrome user agent
  • 2023, Chrome 112: New headless mode shares the full browser code but keeps the HeadlessChrome label by default

Sources

How well checked: Based on official documentation.

On this page