High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.
Orchestration
This page describes the current orchestration layer in PinchTab: how the server launches, tracks, routes to, and stops browser instances.
Scope
The orchestrator is part of server mode. It is responsible for:
- launching managed instances as child
pinchtab bridgeprocesses - attaching externally managed Chrome instances when attach policy allows it
- tracking instance status and metadata
- routing tab-scoped requests to the owning managed instance
- stopping managed instances and cleaning up registry state
It does not execute browser actions directly. That work happens inside the bridge runtime.
Current Runtime Shape
flowchart TD
S["PinchTab Server"] --> O["Orchestrator"]
O --> M1["Managed Instance"]
O --> M2["Managed Instance"]
O -.->|attach| A1["Attached External Instance"]
M1 --> B1["pinchtab bridge child"]
M2 --> B2["pinchtab bridge child"]
B1 --> C1["Chrome"]
B2 --> C2["Chrome"]
Launch Flow
For a managed instance, the orchestration flow is:
flowchart LR
R["Start Request"] --> V["Validate profile + port"]
V --> W["Write child config"]
W --> P["Spawn pinchtab bridge"]
P --> H["Poll /health on configured bind or loopback"]
H --> S{"Healthy before timeout?"}
S -->|Yes| OK["Mark running"]
S -->|No| ER["Mark error"]
What the code does today:
- validates the profile name before launch
- allocates a port when one is not supplied
- prevents more than one active managed instance per profile
- prevents reusing a port already in use
- writes a child config file under the profile state directory
- launches
pinchtab bridge - polls
/healthon the configured child bind first when present, then falls back to127.0.0.1,::1, andlocalhost - moves the instance from
startingtorunningorerror
Attach Flow
Attach is a separate path for an already running browser or bridge.
flowchart LR
R["POST /instances/attach"] --> P["Validate attach policy"]
P --> B["Spawn pinchtab bridge --cdp-attach child"]
B --> H{"Child healthy before timeout?"}
H -->|Yes| L["Registry: attached, attachType cdp-bridge"]
H -->|No| X["Stop child, return error"]
RB["POST /instances/attach-bridge"] --> PB["Validate attach policy"]
PB --> LB["Health-check + registry: attached, attachType bridge"]
Current attach behavior:
- requires
security.attach.enabled - validates the URL against
security.attach.allowSchemes - validates the host against
security.attach.allowHosts POST /instances/attach(CDP URL) launches a childpinchtab bridge --cdp-attach <url>on an allocated port, waits for its/health, and registers it asattached: true,attachType: "cdp-bridge"POST /instances/attach-bridgeregisters an already running bridge server asattachType: "bridge"(upserted by name when the token matches)- never starts or kills the external Chrome process itself
Routing Model
The orchestrator is also the routing layer for multi-instance server mode.
flowchart LR
R["Tab-scoped request"] --> C["Locator (cache, then /tabs scan)"]
C -->|found| P["Proxy to owning instance URL"]
C -->|miss| F["Scan running instances: /tabs?includeTransient=1"]
F -->|found| P
F -->|not found| S{"Exactly one running instance?"}
S -->|Yes| P
S -->|No| N["404 tab not found"]
Today, tab routing (routeByTabOwner in internal/orchestrator/route.go) works like this:
- for routes such as
/tabs/{id}/navigateand/tabs/{id}/action, the server resolves which instance owns the tab - it first asks the instance locator (
internal/instance), which checks its tab→instance cache and on a miss scans each running instance's user-facing/tabslist - if that misses, the orchestrator scans running instances with
/tabs?includeTransient=1, the unfiltered list that also contains tabs the UI list hides (for exampleabout:blank,file://, or the instance's own port), and records the owner in the locator - if no owner is found and exactly one instance is running, the request falls through to it; otherwise it returns 404
- a
browserthat conflicts with the owner's browser is rejected before proxying - after resolution, it proxies the request to the owning instance's URL
Requests without a tab id go to the instance bound to the caller's session or agent identity when there is one, and otherwise to the active strategy's fallback, which targets the earliest-started running instance matching the requested or default browser (the simple strategy launches one when none is running). With no browser requested, that is the same instance /health reports as defaultInstance (DefaultInstance()).
This keeps the public server API stable while the bridge instances remain isolated. Attached instances (both attach types) expose a bridge HTTP URL, so they use the same proxy path.
Stop Flow
Stopping a managed instance is a server-owned lifecycle operation.
flowchart LR
R["Stop Request"] --> S["Mark stopping"]
S --> G["POST /shutdown to instance"]
G --> W{"Exited?"}
W -->|No| T["SIGTERM"]
T --> K{"Exited?"}
K -->|No| X["SIGKILL"]
W -->|Yes| D["Remove from registry"]
K -->|Yes| D
X --> D
Current stop behavior:
- marks the instance as
stopping - tries graceful shutdown through the instance HTTP API
- falls back to process-group termination when needed
- releases the allocated port
- removes the instance from the registry and locator cache
For CDP-attached instances, the child bridge is stopped the same way; the external Chrome is left running. For attach-bridge instances there is no child process: the orchestrator sends POST /shutdown to the registered bridge, waits for its endpoint to go away, and then removes the registration.
Instance States
The main statuses surfaced today are:
startingrunningstoppingstoppederror
The orchestrator also emits lifecycle events such as:
instance.launchedinstance.startedinstance.stoppedinstance.errorinstance.attachedinstance.reattached
Orchestrator.List() returns instances ordered by start time (ties broken by ID), so listings are stable across calls.
Relationship To Other Layers
- Strategy layer decides how shorthand requests are exposed or routed in server mode
- Scheduler is optional and sits above the same routed execution path
- Bridge owns browser state, tab state, and CDP execution
- Profiles provide persistent browser data on disk