File size: 4,020 Bytes
25b930c | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 | # 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
|