Headless documentation

Browser control,
made useful.

Persistent browser control for agents, without Playwright scripts or screen coordinates.

01 / First run

Start a session.

Start the host, create a session, then visit the app. The session stays isolated until you close it.

headless start
headless session create qa
headless --session qa visit localhost:3000/designers/dashboard
headless --session qa inspect --context summary --task "finish onboarding"

On macOS, agent startup opens visible browser windows behind the app currently in use. Change the persistent default with headless config set startup-presentation foreground or restore background startup with headless config set startup-presentation background; inspect it with headless config get startup-presentation. headless start --foreground and headless start --background are one-launch overrides. Settings and overrides apply only when launching a new host and do not reorder an already-running host.

02 / A QA workflow

Capture the proof.

Record the path you need, then stop and create a report.

headless --session qa record start --fps 10
headless --session qa click --role button --name Continue
headless --session qa wait --url /next --settled
headless --session qa record stop --output dashboard-flow.mp4
headless --session qa qa report

03 / Command groups

Use intent, not pixels.

Host lifecycle

version, start, status, stop, runtime, config

start launches the host if it is not already running. status and stop control it afterwards. runtime reports which engine is active and where it came from.

Navigation and interaction

visit, inspect, click, fill, press, scroll

visit accepts HTTP/HTTPS only. Bare hostnames normalize to HTTP (localhost:3000 → http://localhost:3000). URLs carrying credentials are rejected. Downloads and unsafe schemes never navigate.

Capture and evidence

capture-info, screenshot, artifacts, record, qa, report

Screenshots and recordings become private artifacts in the per-user store, created O_EXCL with 0600. They never overwrite and never leave it unless you copy them.

Diagnostics

console, network, styles, cookies, storage, visual

network emulate and network mock are Chromium-engine features. WebKit returns UNSUPPORTED_CAPABILITY instead of approximating them.

04 / Context pruning

Reveal only what matters.

Inspection is progressively disclosed instead of forcing an entire page into an agent prompt. Start with --context summary, use --context outline to receive structural region references such as @r4, then inspect only that region with --within @r4. --context text returns bounded semantic snippets and --context actions returns visible executable controls. --task, --limit, --budget, and --depth rank and bound every focused response; omitted and contextStats make pruning explicit. --context full --text remains the explicit broad-page escape hatch.

05 / Scrollable evidence

Capture the whole scroll.

For scrollable-page QA, use screenshot --every-viewport --output PREFIX for up to 80 viewport-height scroll stops, always including the final bottom position. Results report truncated and totalPoints when a longer page is bounded. Use screenshot --by-section --output PREFIX to capture around visible headings and sections. Series capture restores the original scroll position. Add --format jpg for JPEG series; PDF requires --full-page and is not a series format. The output prefix creates numbered artifacts such as dashboard-scroll-001.png or dashboard-scroll-001.jpg.

06 / Safety by default

Keep the browser local.

No TCP control or Chromium debugger port. 0600 Unix socket in a 0700 per-user directory, with peer-UID checks. Chromium control over inherited fd 3/4 pipes.

macOS: visible WKWebView windows.

Linux: sandboxed Chromium, headless by default or visible with DISPLAY.