Skip to content

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

docs: update guides/identifying-instances.md for orchestrator and dashboard

Mario90dedf110bb7
diff --git a/docs/guides/identifying-instances.md b/docs/guides/identifying-instances.md
index d0efdd64..6def03be 100644
--- a/docs/guides/identifying-instances.md
+++ b/docs/guides/identifying-instances.md
@@ -19,47 +19,72 @@ chmod +x /usr/local/bin/pinchtab-chrome
Then point Pinchtab at it:
```bash
-CHROME_BINARY=/usr/local/bin/pinchtab-chrome ./pinchtab
+CHROME_BIN=/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.
+Now `ps aux | grep pinchtab-chrome` instantly identifies the Chrome processes. Name it whatever you want — `ai-agent-chrome`, `bot-chrome`, etc.
-## 2. Add custom flags (visible in command line)
+## 2. Add custom Chrome flags (visible in process)
```bash
-CHROME_FLAGS="--pinchtab-instance=prod-scraper-01" ./pinchtab
+CHROME_FLAGS="--user-agent=Custom-Agent/1.0" pinchtab
```
-Chrome ignores unknown flags but they show up in the full command line:
+Custom flags show up in the full process command line:
```bash
-ps aux | grep pinchtab-instance
+ps aux | grep pinchtab
+# Shows Chrome processes with custom flags
```
-Useful for distinguishing multiple Pinchtab instances too:
+Useful for identifying different agent roles:
```bash
-# Instance A
-CHROME_FLAGS="--pinchtab-id=scraper" ./pinchtab
+# Scraper agent (with custom flag)
+CHROME_FLAGS="--user-agent=Scraper/1.0" pinchtab &
-# Instance B
-BRIDGE_PORT=9868 CHROME_FLAGS="--pinchtab-id=monitor" ./pinchtab
+# Monitor agent (different flag)
+BRIDGE_PORT=9868 CHROME_FLAGS="--user-agent=Monitor/1.0" pinchtab &
```
## 3. 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.
+Each Pinchtab profile gets its own directory under `~/.pinchtab/profiles/<name>/` — completely separate from your real Chrome profile.
-For dashboard-managed instances, each profile gets its own directory under `~/.pinchtab/profiles/<name>/`.
+Instance Chrome processes show `--user-data-dir=/.../.pinchtab/profiles/...` in their args.
+
+When you create instances via API, they automatically use isolated profiles.
+
+## 4. Identify via Dashboard
+
+The easiest way: Open the dashboard at `http://localhost:9867/dashboard`
+
+You'll see:
+- Instance IDs (`inst_XXXXXXXX`)
+- Which profile each instance uses
+- Whether it's headed or headless
+- When it was started
+- Current status
## 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
+# Start orchestrator with custom Chrome binary
+CHROME_BIN=/usr/local/bin/pinchtab-chrome pinchtab
+```
+
+Or for agents/instances with custom Chrome flags:
+
+```bash
+# Orchestrator
+CHROME_BIN=/usr/local/bin/pinchtab-chrome pinchtab &
+
+# Create instances with identifying info
+# View in dashboard: http://localhost:9867/dashboard
+curl -X POST http://localhost:9867/instances/launch \
+ -d '{"mode":"headless"}'
+
+# Instance appears in dashboard with its ID, port, profile info
```
## Docker
@@ -67,14 +92,23 @@ CHROME_FLAGS="--pinchtab-id=prod-scraper-01" \
Volume-mount your renamed binary and set the env var:
```dockerfile
+FROM alpine:latest
+
COPY pinchtab-chrome /usr/local/bin/pinchtab-chrome
-ENV CHROME_BINARY=/usr/local/bin/pinchtab-chrome
-ENV CHROME_FLAGS="--pinchtab-id=docker-prod"
+RUN chmod +x /usr/local/bin/pinchtab-chrome
+
+ENV CHROME_BIN=/usr/local/bin/pinchtab-chrome
+
+EXPOSE 9867
+
+CMD ["pinchtab"]
```
## Tips
- **[Chrome for Testing](https://googlechromelabs.github.io/chrome-for-testing/)** provides standalone Chrome binaries — no installer, won't conflict with system Chrome. Ideal for automation setups.
- **`chrome-headless-shell`** from the same source is even smaller — headless-only, perfect for server deployments.
-- The parent process is always `pinchtab`, so `pkill -f pinchtab` won't touch your real Chrome.
-- Combine all three approaches (renamed binary + custom flags + separate profile) for maximum clarity.
+- The orchestrator process is always `pinchtab`, so `pkill -f pinchtab` cleanly shuts down all instances.
+- Instance IDs (`inst_XXXXXXXX`) are hash-based and stable — great for identifying instances in logs, dashboards, and monitoring.
+- Combine approaches (renamed binary + custom flags + dashboard visibility) for maximum clarity in production.
+- The dashboard shows all running instances with their profiles, status, and real-time activity — easiest way to identify what's running.