docs/reference/instances.md

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

curl http://localhost:9867/instances
# CLI Alternative
pinchtab 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

Primary: Start by profileId and mode

curl -X POST http://localhost:9867/instances/start \
  -H "Content-Type: application/json" \
  -d '{"profileId":"prof_278be873","mode":"headed","port":"9999"}'
# CLI Alternative
pinchtab instance start --profileId prof_278be873 --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:

• 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

Alternative: Start by profile name

You can also start an instance using a profile name and headless flag:

curl -X POST http://localhost:9867/instances/launch \
  -H "Content-Type: application/json" \
  -d '{"name":"work","headless":false}'
# Response
{
  "id": "inst_ea2e747f",
  "profileId": "prof_278be873",
  "profileName": "work",
  "port": "9999",
  "headless": false,
  "status": "starting",
  "startTime": "2026-03-01T05:21:38.27432Z"
}

The POST /instances/launch endpoint takes:

• name — profile name (required)
• headless — true for headless mode, false for headed mode (optional, defaults to true)

Port is automatically allocated from the configured instance port range.

Get One Instance

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

curl http://localhost:9867/instances/inst_ea2e747f/logs
# CLI Alternative
pinchtab instance logs inst_ea2e747f

Response is plain text.

Stop An Instance

curl -X POST http://localhost:9867/instances/inst_ea2e747f/stop
# CLI Alternative
pinchtab instance stop inst_ea2e747f
# 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:

curl -X POST http://localhost:9867/profiles/prof_278be873/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

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:

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

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

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

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

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

Attach An Existing Chrome

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 security.attach

Attach An Existing Bridge

curl -X POST http://localhost:9867/instances/attach-bridge \
  -H "Content-Type: application/json" \
  -d '{
    "name":"shared-bridge",
    "baseUrl":"http://10.0.12.24:9868",
    "token":"bridge-secret-token"
  }'
# Response
{
  "id": "inst_0a89a5bb",
  "profileId": "prof_278be873",
  "profileName": "shared-bridge",
  "port": "",
  "url": "http://10.0.12.24:9868",
  "status": "running",
  "attached": true,
  "attachType": "bridge"
}

Notes:

• baseUrl must point at a running PinchTab bridge
• the orchestrator performs a health check before registering it
• security.attach.allowHosts must allow the bridge host
• security.attach.allowSchemes must include http or https for bridge attachment