File size: 5,284 Bytes
6a7089a | 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 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 | # Strategies And Allocation
PinchTab has two separate multi-instance controls:
- `multiInstance.strategy`
- `multiInstance.allocationPolicy`
They solve different problems:
```text
strategy = what routes PinchTab exposes and how shorthand requests behave
allocationPolicy = which running instance gets picked when PinchTab must choose one
```
## Strategy
Valid strategies in the current implementation:
- `always-on` - default
- `simple`
- `explicit`
- `simple-autorestart`
### `simple`
Behavior:
- registers the full orchestrator API
- keeps shorthand routes such as `/snapshot`, `/text`, `/navigate`, and `/tabs`
- if a shorthand request arrives and no instance is running, PinchTab auto-launches one managed instance and waits for it to become healthy
Best fit:
- local development
- single-user automation
- “just make the browser service available” setups
### `explicit`
`explicit` also exposes the orchestrator API and shorthand routes, but it does not auto-launch on shorthand requests.
Behavior:
- you start instances explicitly with `/instances/start`, `/instances/launch`, or `/profiles/{id}/start`
- shorthand routes proxy to the first running instance only if one already exists
- if nothing is running, shorthand routes return an error instead of launching a browser for you
Best fit:
- controlled multi-instance environments
- agents that should name instances deliberately
- deployments where hidden auto-launch would be surprising
### `always-on`
`always-on` behaves like a managed single-instance service that should stay up for the full lifetime of the PinchTab process.
Behavior:
- launches one managed instance when the strategy starts
- exposes the same shorthand routes as `simple`
- watches that managed instance and keeps restarting it after unexpected exits until the configured restart limit is reached
- exposes `GET /always-on/status` for current managed-instance state
Best fit:
- daemon-style local services
- agent hosts that expect one default browser to always be present
- setups where startup availability matters, but you still want a bounded failure policy
### `simple-autorestart`
`simple-autorestart` behaves like a managed single-instance service with recovery.
Behavior:
- launches one managed instance when the strategy starts
- exposes the same shorthand routes as `simple`
- watches that managed instance and tries to restart it after unexpected exits under the configured restart policy
- exposes `GET /autorestart/status` for restart state
Best fit:
- kiosk or appliance-style setups
- unattended local services
- environments where one browser should come back after a crash
## Allocation Policy
Valid policies in the current implementation:
- `fcfs`
- `round_robin`
- `random`
Allocation policy matters only when PinchTab has multiple eligible running instances and needs to choose one. If your request already targets `/instances/{id}/...`, no allocation policy is involved for that request.
### `fcfs`
First running candidate wins.
Best fit:
- predictable behavior
- simplest operational model
- “always use the earliest running instance” workflows
### `round_robin`
Candidates are selected in rotation.
Best fit:
- light balancing across a stable pool
- repeated shorthand-style traffic where you want even distribution over time
### `random`
PinchTab picks a random eligible candidate.
Best fit:
- looser balancing
- experiments where deterministic ordering is not important
## Example Config
```json
{
"multiInstance": {
"strategy": "explicit",
"allocationPolicy": "round_robin",
"instancePortStart": 9868,
"instancePortEnd": 9968
}
}
```
## Recommended Defaults
### Always-On Service
```json
{
"multiInstance": {
"strategy": "always-on",
"allocationPolicy": "fcfs",
"restart": {
"maxRestarts": 20,
"initBackoffSec": 2,
"maxBackoffSec": 60,
"stableAfterSec": 300
}
}
}
```
Use this when the default managed browser should be started immediately and kept available with a bounded restart policy.
### Simple Local Service
```json
{
"multiInstance": {
"strategy": "simple",
"allocationPolicy": "fcfs"
}
}
```
Use this when you want shorthand routes to feel like a single local browser service.
### Explicit Orchestration
```json
{
"multiInstance": {
"strategy": "explicit",
"allocationPolicy": "round_robin"
}
}
```
Use this when your client is instance-aware and you want to control lifecycle directly.
### Self-Healing Single Service
```json
{
"multiInstance": {
"strategy": "simple-autorestart",
"allocationPolicy": "fcfs",
"restart": {
"maxRestarts": 3,
"initBackoffSec": 2,
"maxBackoffSec": 60,
"stableAfterSec": 300
}
}
}
```
Use this when one managed browser should stay available and recover after crashes.
## Decision Rule
```text
always-on = default, launched at startup, restarted under restart policy
simple = on-demand shorthand auto-launch
explicit = most control, no shorthand auto-launch
simple-autorestart = one managed browser with crash recovery
fcfs = deterministic
round_robin = balanced rotation
random = loose distribution
```
|