docs/guides/identifying-instances.md

Identifying Instances

When you run PinchTab alongside your normal browser, the easiest way to distinguish its Chrome processes is to combine three signals:

• a dedicated Chrome binary name
• recognizable command-line flags
• the PinchTab dashboard and instance metadata

1. Use A Distinct Chrome Binary Name

If you copy Chrome or Chromium to a custom filename, that filename appears in process listings.

# macOS example
cp "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" /usr/local/bin/pinchtab-chrome
chmod +x /usr/local/bin/pinchtab-chrome

# Set in config.json
pinchtab config set browser.chromeBinary /usr/local/bin/pinchtab-chrome
pinchtab

Now a process listing such as ps -axo pid,command | rg pinchtab-chrome gives you a quick way to spot the browser PinchTab launches.

2. Add Recognizable Chrome Flags

Extra Chrome flags are configured through browser.extraFlags in config.json:

{
  "browser": {
    "extraFlags": "--user-agent=PinchTab-Automation/1.0 --disable-dev-shm-usage"
  }
}

Those flags appear in the Chrome command line, which makes process inspection easier:

ps -axo pid,command | rg 'PinchTab-Automation|user-data-dir'

Use this when you want to differentiate roles such as “scraper”, “monitor”, or “debug”.

3. Use Profile Paths As An Identifier

Each managed profile lives under the configured profile base directory. By default that is the OS-specific PinchTab config directory under profiles/.

PinchTab-launched Chrome processes include a --user-data-dir=... argument that points at that profile location. That is often the fastest way to confirm that a browser process belongs to PinchTab rather than your personal Chrome profile.

4. Use The Dashboard For The Most Reliable View

Open the dashboard at:

• http://localhost:9867/
• or http://localhost:9867/dashboard

The dashboard and instance APIs show:

• instance IDs
• profile IDs and profile names
• assigned ports
• headless vs headed mode
• current status

If you need an API-based view instead of the UI:

curl http://localhost:9867/instances

Practical Combination

For most setups, this combination is enough:

1. point PinchTab to a renamed Chrome binary via browser.chromeBinary in config
2. add a recognizable browser.extraFlags marker in config
3. verify the profile path or instance ID in the dashboard

Docker

The same approach works in containers:

• set browser.chromeBinary in config if you need to override the bundled browser path
• put identifying flags in browser.extraFlags
• inspect the instance list from the API or dashboard rather than relying only on process names inside the container