docs/guides/multi-instance.md

Multi-Instance

PinchTab can run multiple isolated Chrome instances at the same time. Each running instance has its own browser process, port, tabs, and profile-backed state.

Mental Model

• a profile is stored browser state on disk
• an instance is a running Chrome process
• one profile can have at most one active managed instance at a time
• tabs belong to an instance, and tab IDs should be treated as opaque values returned by the API

Start The Orchestrator

pinchtab

By default the orchestrator listens on http://localhost:9867.

Start An Instance

Use the explicit instance API when you want predictable multi-instance behavior:

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

Notes:

• POST /instances/launch still exists as a compatibility endpoint, but POST /instances/start is the clearer primary form.
• If you omit profileId, PinchTab creates a managed instance with an auto-generated profile name.
• Starting an instance is only optional in workflows that use shorthand routes with auto-launch behavior, such as the simple strategy. In explicit, you should assume you need to start one yourself.

Open A Tab In A Specific Instance

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

For follow-up operations, keep using the returned tabId:

curl "http://localhost:9867/tabs/<tabId>/snapshot"
curl "http://localhost:9867/tabs/<tabId>/text"
curl "http://localhost:9867/tabs/<tabId>/metrics"

Reuse A Persistent Profile

List existing profiles first:

curl http://localhost:9867/profiles

Then start an instance for a known profile:

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

Because a profile can have only one active managed instance, starting the same profile again while it is already active returns an error instead of creating a duplicate browser.

Monitor Running Instances

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

Useful fields:

• id: stable instance identifier
• profileId and profileName: the profile backing that instance
• port: the instance's HTTP port
• headless: whether Chrome was launched headless
• status: usually starting, running, stopping, or stopped

Stop An Instance

curl -X POST http://localhost:9867/instances/inst_0a89a5bb/stop
# CLI Alternative
pinchtab instance stop inst_0a89a5bb
# Response
{
  "id": "inst_0a89a5bb",
  "status": "stopped"
}

Stopping the instance frees its port. If the profile is persistent, its browser state remains on disk.

Port Allocation

If you do not pass a port, PinchTab allocates one from the configured range:

{
  "multiInstance": {
    "instancePortStart": 9868,
    "instancePortEnd": 9968
  }
}

When an instance stops, its port becomes available for reuse.

When To Use Explicit Multi-Instance APIs

Prefer explicit instance APIs when:

• multiple browser sessions must stay isolated
• you want separate headed and headless browsers at the same time
• you need stable profile-to-instance ownership rules
• you are building tooling that should never depend on implicit auto-launch