docs/headless-vs-headed.md

Headless vs Headed

PinchTab instances can run Chrome in two modes:

• Headless: no visible browser window
• Headed: visible browser window

You usually run one server with pinchtab, then start instances in either mode through the API or CLI.

---

Headless mode

Headless is the default mode for managed instances.

curl -X POST http://localhost:9867/instances/start \
  -H "Content-Type: application/json" \
  -d '{"mode":"headless"}'
# CLI Alternative
pinchtab instance start
# Response
{
  "id": "inst_0a89a5bb",
  "profileId": "prof_278be873",
  "profileName": "instance-1741400000000000000",
  "port": "9868",
  "headless": true,
  "status": "starting"
}

Good fit for

• agents and automation
• CI and batch jobs
• containers and remote servers
• higher-throughput workloads

Tradeoffs

• no visible browser window
• debugging usually happens through snapshots, screenshots, text extraction, and logs

---

Headed mode

Headed mode launches a visible Chrome window.

curl -X POST http://localhost:9867/instances/start \
  -H "Content-Type: application/json" \
  -d '{"mode":"headed"}'
# CLI Alternative
pinchtab instance start --mode headed
# Response
{
  "id": "inst_1b9a5dcc",
  "profileId": "prof_278be873",
  "profileName": "instance-1741400000000000001",
  "port": "9869",
  "headless": false,
  "status": "starting"
}

Good fit for

• development
• debugging
• local testing
• visual verification
• human-in-the-loop workflows

Tradeoffs

• requires a display environment
• usually uses more CPU and memory than headless mode

---

Side-by-side comparison

Aspect	Headless	Headed
Visibility	No window	Visible window
Debugging	Snapshot- and log-based	Direct visual feedback
Display required	No	Yes
CI use	Strong fit	Usually poor fit
Local development	Fine	Usually easier
Resource usage	Lower	Higher

---

Recommended workflows

Development workflow

Use a visible browser while you are building and validating the flow:

curl -X POST http://localhost:9867/instances/start \
  -H "Content-Type: application/json" \
  -d '{"mode":"headed"}'
# CLI Alternative
pinchtab instance start --mode headed

When you need persistence, create a profile first:

curl -X POST http://localhost:9867/profiles \
  -H "Content-Type: application/json" \
  -d '{"name":"dev"}'
# Response
{
  "status": "created",
  "id": "prof_278be873",
  "name": "dev"
}

Then launch the profile in headed mode:

curl -X POST http://localhost:9867/instances/start \
  -H "Content-Type: application/json" \
  -d '{"profileId":"prof_278be873","mode":"headed"}'
# CLI Alternative
pinchtab instance start --profileId prof_278be873 --mode headed
# Response
{
  "id": "inst_ea2e747f",
  "profileId": "prof_278be873",
  "profileName": "dev",
  "port": "9868",
  "headless": false,
  "status": "starting"
}

Production workflow

Use headless mode for repeatable unattended work:

for i in 1 2 3; do
  curl -s -X POST http://localhost:9867/instances/start \
    -H "Content-Type: application/json" \
    -d '{"mode":"headless"}' | jq .
done
# CLI Alternative
for i in 1 2 3; do
  pinchtab instance start
done

---

Inspecting a headless instance

You can debug a headless instance through tab APIs.

List the instance tabs:

curl http://localhost:9867/instances/inst_0a89a5bb/tabs | jq .
# Response
[
  {
    "id": "CDP_TARGET_ID",
    "instanceId": "inst_0a89a5bb",
    "url": "https://pinchtab.com",
    "title": "PinchTab"
  }
]

Then inspect the tab:

curl http://localhost:9867/tabs/CDP_TARGET_ID/snapshot | jq .

curl http://localhost:9867/tabs/CDP_TARGET_ID/text | jq .

curl http://localhost:9867/tabs/CDP_TARGET_ID/screenshot > page.jpg

---

Display requirements

Headed instances need a display environment.

macOS

Headed mode works with the native desktop session.

Linux

Headless works anywhere. Headed mode needs X11 or Wayland.

ssh -X user@server 'pinchtab instance start --mode headed'

Windows

Headed mode works with the native desktop session.

Docker

Headless is the normal choice in containers:

docker run -d -p 9867:9867 pinchtab/pinchtab
curl -X POST http://localhost:9867/instances/start \
  -H "Content-Type: application/json" \
  -d '{"mode":"headless"}'

---

Dashboard

The dashboard lets you monitor running instances and profiles while you use either mode.

Useful views:

• Monitoring: running instances, status, tabs, and optional memory metrics
• Profiles: saved profiles, launch actions, and live details
• Settings: runtime and dashboard preferences

---

Summary

• Use headless for unattended automation and scale.
• Use headed for local debugging and human-visible workflows.
• Choose the mode per instance, not per server.