Instances

Instances are running Chrome processes managed by PinchTab. Each managed instance has:

  • an instance ID
  • a profile
  • a port
  • a mode (headless or headed)
  • an execution status

One profile can have at most one active managed instance at a time.

List Instances

terminal 
pinchtab instances
curl http://localhost:9867/instances
Response 
[
  {
    "id": "inst_0a89a5bb",
    "profileId": "prof_278be873",
    "profileName": "work",
    "port": "9868",
    "headless": true,
    "status": "running",
    "startTime": "2026-03-01T05:21:38.27432Z"
  }
]

pinchtab instances is the simplest way to inspect the current fleet from the CLI.

Start An Instance

terminal 
pinchtab instance start --profileId 278be873adeb --mode headed --port 9999
curl -X POST http://localhost:9867/instances/start \  -H "Content-Type: application/json" \  -d '{"profileId":"278be873adeb","mode":"headed","port":"9999"}'
Response 
{
  "id": "inst_ea2e747f",
  "profileId": "prof_278be873",
  "profileName": "work",
  "port": "9999",
  "headless": false,
  "status": "starting",
  "startTime": "2026-03-01T05:21:38.27432Z"
}

Notes:

  • POST /instances/start is the primary endpoint.

  • if profileId is omitted, PinchTab creates an auto-generated temporary profile such as instance-...

  • if port is omitted, PinchTab allocates one from the configured instance port range

Get One Instance

terminal 
curl http://localhost:9867/instances/inst_ea2e747f
curl http://localhost:9867/instances/inst_ea2e747f
Response 
{
  "id": "inst_ea2e747f",
  "profileId": "prof_278be873",
  "profileName": "work",
  "port": "9999",
  "headless": false,
  "status": "running",
  "startTime": "2026-03-01T05:21:38.27432Z"
}

Common status values:

  • starting
  • running
  • stopping
  • stopped
  • error

Get Instance Logs

terminal 
pinchtab instance logs inst_ea2e747f
curl http://localhost:9867/instances/inst_ea2e747f/logs

Response is plain text.

Stop An Instance

terminal 
pinchtab instance stop inst_ea2e747f
curl -X POST http://localhost:9867/instances/inst_ea2e747f/stop
Response 
{
  "id": "inst_ea2e747f",
  "status": "stopped"
}

Stopping an instance preserves the profile unless it was a temporary auto-generated profile.

Start By Profile

You can also start an instance from a profile-oriented route:

terminal 
curl -X POST http://localhost:9867/profiles/278be873adeb/start \  -H "Content-Type: application/json" \  -d '{"headless":false,"port":"9999"}'
curl -X POST http://localhost:9867/profiles/278be873adeb/start \  -H "Content-Type: application/json" \  -d '{"headless":false,"port":"9999"}'
Response 
{
  "id": "inst_ea2e747f",
  "profileId": "prof_278be873",
  "profileName": "work",
  "port": "9999",
  "headless": false,
  "status": "starting"
}

This route accepts a profile ID or profile name in the path. Its request body uses headless rather than mode.

Open A Tab In An Instance

terminal 
curl -X POST http://localhost:9867/instances/inst_ea2e747f/tabs/open \  -H "Content-Type: application/json" \  -d '{"url":"https://pinchtab.com"}'
curl -X POST http://localhost:9867/instances/inst_ea2e747f/tabs/open \  -H "Content-Type: application/json" \  -d '{"url":"https://pinchtab.com"}'
Response 
{
  "tabId": "8f9c7d4e1234567890abcdef12345678",
  "url": "https://pinchtab.com",
  "title": "PinchTab"
}

There is no dedicated instance-scoped tab open CLI command today. The CLI shortcut is:

terminal 
pinchtab instance navigate inst_ea2e747f https://pinchtab.com
pinchtab instance navigate inst_ea2e747f https://pinchtab.com

That command opens a tab for the instance and then navigates it.

List Tabs For One Instance

terminal 
curl http://localhost:9867/instances/inst_ea2e747f/tabs
curl http://localhost:9867/instances/inst_ea2e747f/tabs
Response 
[
  {
    "id": "8f9c7d4e1234567890abcdef12345678",
    "instanceId": "inst_ea2e747f",
    "url": "https://pinchtab.com",
    "title": "PinchTab"
  }
]

List All Tabs Across Running Instances

terminal 
curl http://localhost:9867/instances/tabs
curl http://localhost:9867/instances/tabs

This is the fleet-wide tab listing endpoint. It is different from GET /tabs, which is shorthand/bridge-style and not a fleet-wide inventory.

List Metrics Across Instances

terminal 
curl http://localhost:9867/instances/metrics
curl http://localhost:9867/instances/metrics

Use this when you want per-instance memory metrics across all running instances.

Attach An Existing Chrome

terminal 
curl -X POST http://localhost:9867/instances/attach \  -H "Content-Type: application/json" \  -d '{"name":"shared-chrome","cdpUrl":"ws://127.0.0.1:9222/devtools/browser/..."}'
curl -X POST http://localhost:9867/instances/attach \  -H "Content-Type: application/json" \  -d '{"name":"shared-chrome","cdpUrl":"ws://127.0.0.1:9222/devtools/browser/..."}'
Response 
{
  "id": "inst_0a89a5bb",
  "profileId": "prof_278be873",
  "profileName": "shared-chrome",
  "status": "running",
  "attached": true,
  "cdpUrl": "ws://127.0.0.1:9222/devtools/browser/..."
}

Notes:

  • there is no CLI attach command
  • attach is allowed only when enabled in config under attach