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.

terminal

pinchtab instance start

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

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.

terminal

pinchtab instance start --mode headed

curl -X POST http://localhost:9867/instances/start \  -H "Content-Type: application/json" \  -d '{"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:

terminal

pinchtab instance start --mode headed

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

When you need persistence, create a profile first:

terminal

curl -X POST http://localhost:9867/profiles \  -H "Content-Type: application/json" \  -d '{"name":"dev"}'

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:

terminal

pinchtab instance start --profileId prof_278be873 --mode headed

curl -X POST http://localhost:9867/instances/start \  -H "Content-Type: application/json" \  -d '{"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:

terminal

for i in 1 2 3; do  pinchtab instance startdone

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

Inspecting a headless instance

You can debug a headless instance through tab APIs.

List the instance tabs:

terminal

curl http://localhost:9867/instances/inst_0a89a5bb/tabs | jq .

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:

terminal

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

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

terminal

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

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

terminal

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

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.

terminal

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

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:

terminal

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

docker run -d -p 9867:9867 pinchtab/pinchtabcurl -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.