Instance Charts

This page captures the current instance model in PinchTab.

It is intentionally limited to the instance types and relationships that exist now in the codebase.

Chart 1: Current Instance Types

Architecture Diagram Mermaid 
flowchart TD
    I["Instance"] --> M["Managed"]
    I --> A["Attached"]

    M --> MB["Bridge-backed"]
    A --> EX["External Chrome registration"]

Current meaning:

  • managed means PinchTab launches and owns the runtime lifecycle
  • attached means PinchTab registers an already running external Chrome
  • bridge-backed means the server reaches the browser through a pinchtab bridge runtime

Chart 2: Managed Instance Shape

Architecture Diagram Mermaid 
flowchart LR
    S["PinchTab Server"] --> O["Orchestrator"]
    O --> B["pinchtab bridge child"]
    B --> C["Chrome"]
    C --> T["Tabs"]
    O --> P["Profile directory"]

For managed instances today:

  • the orchestrator launches a bridge child process
  • the bridge owns one browser runtime
  • tabs live inside that runtime
  • browser state is tied to the associated profile directory

Chart 3: Attached Instance Shape

Architecture Diagram Mermaid 
flowchart LR
    S["PinchTab Server"] --> O["Orchestrator"]
    O -. "attach via CDP URL" .-> E["External Chrome"]
    E --> T["Tabs"]

For attached instances today:

  • PinchTab does not launch the browser
  • PinchTab stores registration metadata in the instance registry
  • ownership of the external browser process stays outside PinchTab
  • attached registration exists today, but the normal managed-instance tab proxy path is still centered on bridge-backed instances

Chart 4: Ownership Model

Architecture Diagram Mermaid 
flowchart TD
    I["Instance"] --> L["Lifecycle owner"]

    L --> P["PinchTab"]
    L --> X["External process owner"]

    P --> M["Managed instance"]
    X --> A["Attached instance"]

This is the key distinction:

  • managed instances are lifecycle-owned by PinchTab
  • attached instances are tracked by PinchTab but not process-owned by PinchTab

Chart 5: Routing Relationship

Architecture Diagram Mermaid 
flowchart TD
    I["Instance"] --> T["Tabs"]
    T --> R["Tab-scoped routes"]
    R --> O["Owning instance resolution"]

The important runtime rule is:

  • tabs belong to one instance
  • for managed bridge-backed instances, tab-scoped server routes are resolved to the owning instance before proxying

Current Instance Fields

The main instance fields surfaced by the current API are:

  • id
  • profileId
  • profileName
  • port
  • headless
  • status
  • startTime
  • error
  • attached
  • cdpUrl

Useful interpretation:

  • attached: false usually means a managed bridge-backed instance
  • attached: true means an externally registered instance
  • port is relevant for managed bridge-backed instances
  • cdpUrl is relevant for attached instances