docs/reference/strategies.md

Strategies And Allocation

PinchTab has two separate multi-instance controls:

• multiInstance.strategy
• multiInstance.allocationPolicy

They solve different problems:

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

{
  "multiInstance": {
    "strategy": "explicit",
    "allocationPolicy": "round_robin",
    "instancePortStart": 9868,
    "instancePortEnd": 9968
  }
}

Recommended Defaults

Always-On Service

{
  "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

{
  "multiInstance": {
    "strategy": "simple",
    "allocationPolicy": "fcfs"
  }
}

Use this when you want shorthand routes to feel like a single local browser service.

Explicit Orchestration

{
  "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

{
  "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

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