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.

```bash
# 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`:

```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:

```bash
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:

```bash
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