| # 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 |
|
|
| ```bash |
| 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: |
|
|
| ```bash |
| 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 |
|
|
| ```bash |
| 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`: |
|
|
| ```bash |
| 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: |
|
|
| ```bash |
| curl http://localhost:9867/profiles |
| ``` |
|
|
| Then start an instance for a known profile: |
|
|
| ```bash |
| 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 |
|
|
| ```bash |
| 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 |
|
|
| ```bash |
| 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: |
|
|
| ```json |
| { |
| "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 |
|
|
