Headless label in the browser identity
The browser's name tag can say it is running without a screen.
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
| API | navigator.userAgent contains 'HeadlessChrome'; Sec-CH-UA brand 'HeadlessChrome'; navigator.userAgentData.brands |
| Browser compat keys | api.Navigator.userAgentapi.NavigatorUAData.brands |
| How access is granted | none |
| What the user sees | None |
| Needs a secure context (HTTPS) | No |
| Needs a user gesture | No |
| How long it lasts | Not listed |
| How to take it back | Not listed |
| Inside an iframe | Not listed |
Typical flow
- Browser sends User-Agent and Sec-CH-UA on every request
- Server or page script reads the brand names
- Compare the label with the other headers and the JavaScript values
Data you get
Shape: string
How often: static per session
| Field | Type | Unit | Range | Precision |
|---|---|---|---|---|
userAgent | string | None | contains HeadlessChrome/<version> in headless Chrome | Not listed |
Sec-CH-UA | header | None | brand list that may include HeadlessChrome | Not listed |
userAgentData.brands | list | None | same brands as the header when not patched | Not 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
| Type | Example | Apps |
|---|---|---|
| security | A firewall serves a challenge to any request whose brand list says HeadlessChrome. | Cloudflare |
| shopping | A ticket seller drops queue requests from headless browsers. | None named |
| ads | An ad network does not count views from clients that report a headless brand. | None named |
| analytics | A site analytics tool files headless visits under bots. | Google Analytics |
| developer | A tester sees the label in server logs and knows the run was headless. | Puppeteer, Playwright |
| travel | A fare site hides prices from clients that announce headless mode. | None named |
Risks
- Blocks useful agents
- Easy to hide
What the platform says
- Chrome for Developers: Headless Chrome. Docs describe running Chrome without a visible UI for automation and testing.
Good uses and abuse
Legitimate uses
- Bot defense
- Cleaner analytics
Known abuse
- Blocking legitimate agents
Scores
| Score | Value | Meaning |
|---|---|---|
| Sensitivity | 1 of 5 | How revealing the data is |
| Utility | 4 of 5 | How useful it is to honest apps |
| Friction | 0 of 5 | How much the user has to do |
| Fingerprint bits | 0.2 | Rough 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
Related capabilities
Related
- Automation (webdriver) flag. Can tell if Selenium, Playwright, or Puppeteer is controlling the browser
- User-Agent string. Can see your browser brand, version, OS family, and chip family on every request
- Sec-CH-UA low entropy hints and reduced User-Agent. Can see your browser brand, major version, phone or computer type, and system in Chromium browsers
- Bot detection and CAPTCHA signals. Can combine many browser and network clues to guess if you are a bot
Sources
How well checked: Based on official documentation.