Skip to content

High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.

docs: add instance identification guide + BRIDGE_MAX_TABS to README

Marioe3e2d862d6a8
diff --git a/README.md b/README.md
index 2552291f..816fdd2f 100644
--- a/README.md
+++ b/README.md
@@ -238,6 +238,7 @@ In headed mode, log into sites in the visible Chrome window once; cookies and lo
| `BRIDGE_STATE_DIR` | `~/.pinchtab` | State/session storage |
| `BRIDGE_NO_RESTORE` | `false` | Skip restoring tabs from previous session |
| `BRIDGE_STEALTH` | `light` | Stealth level: `light` (basic) or `full` (canvas/WebGL/font spoofing) |
+| `BRIDGE_MAX_TABS` | `20` | Max open tabs (0 = unlimited) |
| `BRIDGE_BLOCK_IMAGES` | `false` | Block image loading |
| `BRIDGE_BLOCK_MEDIA` | `false` | Block all media (images + fonts + CSS + video) |
| `BRIDGE_NO_ANIMATIONS` | `false` | Disable CSS animations/transitions globally |
@@ -261,6 +262,60 @@ In headed mode, log into sites in the visible Chrome window once; cookies and lo
| `PINCHTAB_HEADED` | *(unset)* | If set, auto-launched instance is headed; unset means headless |
| `PINCHTAB_DASHBOARD_URL` | `http://localhost:$BRIDGE_PORT` | CLI helper base URL for `pinchtab connect` |
+## Identifying Pinchtab Chrome Instances
+
+Running multiple Chrome instances? Here's how to tell Pinchtab's apart from your regular browser.
+
+### Rename the Chrome binary (recommended)
+
+Copy Chrome to a custom name — changes the actual process name in `ps`, Activity Monitor, Task Manager:
+
+```bash
+# macOS
+cp "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" /usr/local/bin/pinchtab-chrome
+
+# Linux
+cp $(which google-chrome) /usr/local/bin/pinchtab-chrome
+
+chmod +x /usr/local/bin/pinchtab-chrome
+```
+
+Then point Pinchtab at it:
+
+```bash
+CHROME_BINARY=/usr/local/bin/pinchtab-chrome ./pinchtab
+```
+
+Now `ps aux | grep pinchtab-chrome` instantly identifies the automation instance. Name it whatever you want — `ai-agent-chrome`, `bot-chrome`, etc.
+
+### Add custom flags (visible in command line)
+
+```bash
+CHROME_FLAGS="--pinchtab-instance=prod-scraper-01" ./pinchtab
+```
+
+Chrome ignores unknown flags but they show up in the full command line:
+
+```bash
+ps aux | grep pinchtab-instance
+```
+
+### Separate profile directory (built-in)
+
+Pinchtab already uses `~/.pinchtab/chrome-profile` by default — completely separate from your real Chrome profile. You'll see `--user-data-dir=/.../.pinchtab/...` in the process args.
+
+### Full example
+
+```bash
+CHROME_BINARY=/usr/local/bin/pinchtab-chrome \
+BRIDGE_PROFILE=~/.pinchtab/bot-prod \
+BRIDGE_HEADLESS=true \
+CHROME_FLAGS="--pinchtab-id=prod-scraper-01" \
+./pinchtab
+```
+
+> **Tip:** [Chrome for Testing](https://googlechromelabs.github.io/chrome-for-testing/) provides standalone Chrome binaries perfect for this — no installer needed, won't conflict with your system Chrome.
+
## Architecture
```