Skip to content

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

docs: update guides/multi-instance.md and guides/headed-mode-guide.md for orchestrator

Mario7d0911e08c4e
diff --git a/docs/guides/headed-mode-guide.md b/docs/guides/headed-mode-guide.md
index 1df0ea57..ea053d4f 100644
--- a/docs/guides/headed-mode-guide.md
+++ b/docs/guides/headed-mode-guide.md
@@ -56,45 +56,58 @@ Every profile gets a stable 12-character hex ID derived from its name. Use IDs i
## Start and Stop with One Call
-The dashboard exposes two endpoints that make profile management trivial for agents:
+The orchestrator API makes profile management trivial for agents:
```bash
-# Start a profile (port auto-allocated)
-curl -X POST http://localhost:9867/start/a1b2c3d4e5f6
+# List profiles (get profile ID)
+curl http://localhost:9867/profiles | jq '.[] | {id, name}'
+
+# Start a profile instance
+curl -X POST http://localhost:9867/instances/start \
+ -H "Content-Type: application/json" \
+ -d '{"profileId":"a1b2c3d4e5f6"}'
```
+**Response:**
```json
{
- "id": "Work-56490",
- "name": "Work",
- "port": "56490",
+ "id": "inst_work123",
+ "profileId": "a1b2c3d4e5f6",
+ "profileName": "Work",
+ "port": "9868",
"status": "starting",
- "url": "http://localhost:56490"
+ "headless": false
}
```
-The response tells you which port the instance landed on. All your API calls go to that port:
+The response tells you the instance ID. All your API calls go through the orchestrator proxy:
```bash
-PORT=56490
+INST="inst_work123"
-# Navigate
-curl -X POST http://localhost:$PORT/navigate \
+# Navigate (via orchestrator)
+curl -X POST http://localhost:9867/instances/$INST/navigate \
-d '{"url": "https://mail.google.com"}'
# Read the inbox
-curl "http://localhost:$PORT/snapshot?maxTokens=4000"
+curl "http://localhost:9867/instances/$INST/snapshot"
# Done — shut it down
-curl -X POST http://localhost:9867/stop/a1b2c3d4e5f6
+curl -X POST http://localhost:9867/instances/$INST/stop
```
-You can also pass a specific port or run headless if you want:
+You can also specify mode (headed/headless):
```bash
-curl -X POST http://localhost:9867/start/a1b2c3d4e5f6 \
- -H 'Content-Type: application/json' \
- -d '{"port": "9868", "headless": true}'
+# Start profile in headless mode (faster, no display)
+curl -X POST http://localhost:9867/instances/start \
+ -H "Content-Type: application/json" \
+ -d '{"profileId":"a1b2c3d4e5f6","mode":"headless"}'
+
+# Start profile in headed mode (visible window, debug)
+curl -X POST http://localhost:9867/instances/start \
+ -H "Content-Type: application/json" \
+ -d '{"profileId":"a1b2c3d4e5f6","mode":"headed"}'
```
## A Real Example: Reading Email
@@ -102,19 +115,27 @@ curl -X POST http://localhost:9867/start/a1b2c3d4e5f6 \
Here's what a full agent workflow looks like. The human already logged into Gmail through the profile once. Now the agent can check email any time:
```bash
-# 1. Start the profile
-INSTANCE=$(curl -s -X POST http://localhost:9867/start/a1b2c3d4e5f6)
-PORT=$(echo $INSTANCE | jq -r .port)
+# 1. Get profile ID
+PROFILE_ID=$(curl -s http://localhost:9867/profiles \
+ | jq -r '.[] | select(.name=="Work") | .id')
-# 2. Navigate to Gmail
-curl -s -X POST http://localhost:$PORT/navigate \
+# 2. Start the profile instance
+INST=$(curl -s -X POST http://localhost:9867/instances/start \
+ -H "Content-Type: application/json" \
+ -d '{"profileId":"'$PROFILE_ID'"}' | jq -r '.id')
+
+# 3. Wait for instance to initialize
+sleep 2
+
+# 4. Navigate to Gmail (uses orchestrator proxy)
+curl -s -X POST http://localhost:9867/instances/$INST/navigate \
-d '{"url": "https://mail.google.com"}'
-# 3. Read the inbox (accessibility tree, not screenshots)
-curl -s "http://localhost:$PORT/snapshot?maxTokens=4000" | jq '.nodes[] | select(.role == "row") | .name' | head -5
+# 5. Read the inbox (accessibility tree, not screenshots)
+curl -s "http://localhost:9867/instances/$INST/snapshot" | jq '.nodes[] | select(.role == "row") | .name' | head -5
```
-Output:
+**Output:**
```
"unread, GitHub, [org/repo] New pull request #42, 11:44 AM, ..."
"unread, Stripe, Your January invoice is ready, 11:26 AM, ..."
@@ -124,8 +145,8 @@ Output:
No screenshots. No vision models. No token-heavy page dumps. Just structured data from the accessibility tree — the same way a screen reader would see it.
```bash
-# 4. Clean up
-curl -s -X POST http://localhost:9867/stop/a1b2c3d4e5f6
+# 6. Clean up
+curl -X POST http://localhost:9867/instances/$INST/stop
```
## When to Use Headed vs Headless
@@ -141,24 +162,41 @@ curl -s -X POST http://localhost:9867/stop/a1b2c3d4e5f6
The key insight: you don't have to choose one mode forever. Start headed when you need human involvement, then switch to headless for routine automation. The profile carries the session either way.
-## Dashboard: The Control Plane
+## Dashboard & Control Plane
-Running `pinchtab dashboard` gives you a web UI at `http://localhost:9867` for managing everything:
+Running `pinchtab` gives you a web UI at `http://localhost:9867` for managing everything:
-- Create and import Chrome profiles
-- Launch instances (headed or headless) on any port
-- Monitor running instances — status, tabs, logs
-- Live view of what the agent is doing
+- Create and import Chrome profiles (persistent)
+- Launch instances (headed or headless) with any profile
+- Monitor running instances — status, tabs, logs, Chrome initialization
+- View all agents connected to each instance
- Stop instances gracefully
+- Real-time activity feed of all operations
-The dashboard itself doesn't run Chrome. It's a lightweight control plane that spawns and manages profile instances as separate processes.
+The dashboard doesn't run Chrome itself. It's a lightweight orchestrator that manages profile instances as separate processes.
-For agents that prefer CLI over UI:
+**Web UI:**
+```bash
+# Start orchestrator and dashboard
+pinchtab
+
+# Open in browser
+open http://localhost:9867/dashboard
+```
+**CLI for agents:**
```bash
-# Resolve a running profile to its URL
-pinchtab connect "Work"
-# → http://localhost:56490
+# List profiles
+pinchtab profiles
+
+# List running instances
+pinchtab instances
+
+# Start instance with profile
+pinchtab instance launch # Temporary profile
+PROFILE_ID=$(pinchtab profiles | jq -r '.[] | select(.name=="Work") | .id')
+curl -X POST http://localhost:9867/instances/start \
+ -d '{"profileId":"'$PROFILE_ID'"}'
```
## Multiple Profiles, Multiple Agents
@@ -166,17 +204,43 @@ pinchtab connect "Work"
Nothing stops you from running several profiles at once. Different accounts, different purposes:
```bash
-# Work email
-curl -X POST http://localhost:9867/start/a1b2c3d4e5f6
+# Get profile IDs
+WORK_ID=$(pinchtab profiles | jq -r '.[] | select(.name=="Work") | .id')
+PERSONAL_ID=$(pinchtab profiles | jq -r '.[] | select(.name=="Personal") | .id')
-# Personal Twitter
-curl -X POST http://localhost:9867/start/a1b2c3d4e5f6
+# Start Work profile instance (headed for debugging)
+WORK_INST=$(curl -s -X POST http://localhost:9867/instances/start \
+ -H "Content-Type: application/json" \
+ -d '{"profileId":"'$WORK_ID'","mode":"headed"}' | jq -r '.id')
+
+# Start Personal profile instance (headless for automation)
+PERSONAL_INST=$(curl -s -X POST http://localhost:9867/instances/start \
+ -H "Content-Type: application/json" \
+ -d '{"profileId":"'$PERSONAL_ID'","mode":"headless"}' | jq -r '.id')
-# Research browser (no login, disposable)
-curl -X POST http://localhost:9867/start/f6e5d4c3b2a1
+# Start temporary instance (no persistent profile)
+RESEARCH_INST=$(curl -s -X POST http://localhost:9867/instances/launch \
+ -H "Content-Type: application/json" \
+ -d '{"mode":"headless"}' | jq -r '.id')
```
-Each gets its own port, its own Chrome process, its own isolated session. Agents can work across all of them simultaneously.
+Each gets its own port (auto-allocated), its own Chrome process, its own isolated session. Agents can work across all of them simultaneously:
+
+```bash
+# Agent A works on Work profile
+curl -X POST http://localhost:9867/instances/$WORK_INST/navigate \
+ -d '{"url":"https://work.slack.com"}'
+
+# Agent B works on Personal profile at the same time
+curl -X POST http://localhost:9867/instances/$PERSONAL_INST/navigate \
+ -d '{"url":"https://twitter.com"}'
+
+# Agent C uses temporary research instance
+curl -X POST http://localhost:9867/instances/$RESEARCH_INST/navigate \
+ -d '{"url":"https://google.com/search?q=..."}'
+
+# All three isolated, no interference
+```
---
@@ -190,65 +254,76 @@ The dashboard gives you that. Open it in your browser and you get a real-time vi
### Setting Up Remote Access
-By default, Pinchtab only listens on `127.0.0.1` — locked to the machine. To access the dashboard from another device on your network, you need two things: open the bind address and set an auth token.
+By default, PinchTab only listens on `127.0.0.1` — locked to the machine. To access the orchestrator and dashboard from another device on your network, you can set environment variables or bind to a different address.
+
+**Simple setup (local network only):**
+```bash
+# Bind to all interfaces (only safe on private network!)
+BRIDGE_BIND=0.0.0.0 pinchtab
+```
+**Secure setup (production):**
```bash
-BRIDGE_BIND=0.0.0.0 BRIDGE_TOKEN=your-secret-token pinchtab dashboard
+# Bind to all interfaces + require auth token
+BRIDGE_BIND=0.0.0.0 BRIDGE_TOKEN=your-secret-token pinchtab
```
-That's it. Now open `http://<server-ip>:9867/dashboard` from your laptop and you'll see the full dashboard.
+Now open `http://<server-ip>:9867/dashboard` from your laptop and you'll see the full dashboard.
-Every API call needs the token too:
+With a token, every API call requires it:
```bash
curl http://192.168.1.100:9867/profiles \
-H "Authorization: Bearer your-secret-token"
```
-Without the token, every request gets a `401`. No exceptions — health check, profiles, everything.
+Without the token, requests get a `401` error. No exceptions.
-### What You See
+**For production:** Consider running behind a reverse proxy (nginx) with HTTPS instead of exposing the orchestrator directly.
-The dashboard has three views:
-
-**Profiles** — your Chrome profiles, their status (running/stopped), account info. Click Details on any profile to get three tabs:
+### What You See
-- **Profile** — metadata, status, path, account info
-- **Live** — real-time screencast of what the browser is showing right now. You're literally watching your agent browse. <!-- screenshot: live-tab.png -->
-- **Logs** — open tabs, connected agents, activity stats, instance logs
+The dashboard has several views:
-<div align="center" style="padding: 12px 0;">
- <img src="../assets/live-view.png" width="400" alt="Pinchtab live view" style="padding: 8px;" />
-</div>
+**Instances** (default) — all running instances, their status, port, profile, Chrome mode (headed/headless). Click any instance to see:
+- Instance metadata (ID, port, profile, status)
+- Open tabs in that instance
+- Instance logs (Chrome output, errors)
+- Quick actions (navigate, take snapshot, stop)
-**Agents** — every agent that's made an API call, across all running profiles. You see their ID, which profile they're using, their last action, and when they were last active. The Activity Feed shows a real-time stream of every navigate, snapshot, and action — filterable by type.
+**Profiles** — all profiles (persistent and temporary), their status, account info. Create new profiles, delete old ones, see which instances are using each profile.
-<div align="center" style="padding: 12px 0;">
- <img src="../assets/agents-feed.png" width="400" alt="Pinchtab agents feed" style="padding: 8px;" />
-</div>
+**Agents** — every agent (identified by X-Agent-Id header) and which instance they're connected to. The Activity Feed shows a real-time stream of every navigate, snapshot, and action — filterable by type.
-**Settings** — screencast quality, stealth level, browser options.
+**Settings** — Configure orchestrator behavior, instance defaults, port ranges.
### The Activity Feed
-The Activity Feed is the heartbeat of your agent fleet. Every action from every agent across every profile streams in real-time:
+The Activity Feed is the heartbeat of your agent fleet. Every action from every agent across every instance streams in real-time:
```
-mario → POST /navigate (Work) — 23ms
-mario → GET /snapshot (Work) — 145ms
-scraper → POST /navigate (Research) — 31ms
-scraper → GET /text (Research) — 89ms
+mario → POST /navigate (inst_abc123) — 23ms
+mario → GET /snapshot (inst_abc123) — 145ms
+scraper → POST /navigate (inst_def456) — 31ms
+scraper → GET /text (inst_def456) — 89ms
```
Filter by type — just navigations, just snapshots, just actions — to focus on what matters.
-This works because the dashboard subscribes to each running child instance's event stream and relays everything through a single SSE connection to your browser. You get one unified view even when agents are spread across multiple profiles on different ports.
+This works because the orchestrator collects events from all running instances and streams them to the dashboard via Server-Sent Events (SSE). You get one unified view even when agents are spread across multiple instances on different ports.
### Agent Identification
-For agents to show up with a name instead of "anonymous", they just need to pass a header:
+For agents to show up with a name in the dashboard instead of "anonymous", they just need to pass a header:
```bash
+# Via orchestrator proxy
+curl -X POST http://localhost:9867/instances/$INST/navigate \
+ -H "X-Agent-Id: mario" \
+ -H "Content-Type: application/json" \
+ -d '{"url": "https://example.com"}'
+
+# Or directly to instance
curl -X POST http://localhost:9868/navigate \
-H "X-Agent-Id: mario" \
-H "Content-Type: application/json" \
@@ -259,7 +334,7 @@ That's all it takes. The `X-Agent-Id` header tags every request, and the dashboa
### Watching Live
-The Live tab in the profile details is a real-time screencast. The dashboard streams JPEG frames from Chrome's DevTools protocol directly to your browser. You see exactly what the agent sees — every page load, every click, every form fill.
+Click on any running instance in the Instances tab to see a real-time screencast. The dashboard streams JPEG frames from Chrome's DevTools protocol directly to your browser. You see exactly what the agent sees — every page load, every click, every form fill.
This is useful for:
@@ -267,30 +342,49 @@ This is useful for:
- **Trust** — your agent is buying something? Watch it fill in the details before it submits.
- **Fun** — there's something oddly satisfying about watching an AI browse the web.
-The screencast is lightweight — configurable FPS (1-15), quality (10-80%), and max width. Default settings use minimal bandwidth.
+**Note:** Screencast only works for headed instances (with visible Chrome window). Headless instances don't have a visual display to capture.
-### A Typical Remote Monitoring Setup
+The screencast is lightweight — you can configure:
+- Frames per second (1-15 FPS)
+- Quality (10-80% JPEG compression)
+- Max width (scale down for bandwidth)
+
+Default settings use minimal bandwidth for remote monitoring.
-On your server:
+### A Typical Remote Monitoring Setup
+**On your server:**
```bash
-# Start the dashboard, open to network, locked with token
+# Start orchestrator, open to network, locked with token
BRIDGE_BIND=0.0.0.0 \
BRIDGE_TOKEN=my-secret-token \
-pinchtab dashboard &
+pinchtab &
-# Your agents start profiles and work as usual
+# Your agents start instances and work as usual
# They just pass X-Agent-Id headers so you can identify them
+AGENT_ID=mario ./my-agent.sh
```
-On your laptop, phone, or tablet:
+**On your laptop, phone, or tablet:**
+
+1. Open `http://<server-ip>:9867/dashboard` in browser
+2. Enter token when prompted
+3. See all instances, profiles, agents in real-time
+4. Click into any **headed** instance → see live screencast
+5. Switch to Agents view → see real-time activity feed of all operations
+
+No SSH tunnels. No VPN. No complex setup. Just a browser and a token.
-1. Open `http://<server-ip>:9867/dashboard`
-2. See all profiles, their status, running agents
-3. Click into any profile → Live tab to watch the screencast
-4. Switch to Agents view to see the real-time activity feed
+**API calls from agents:**
+```bash
+# Agents identify themselves with X-Agent-Id header
+curl -X POST http://orchestrator:9867/instances/$INST/navigate \
+ -H "X-Agent-Id: mario" \
+ -H "Content-Type: application/json" \
+ -d '{"url": "https://example.com"}'
+```
-No SSH tunnels. No VPN. Just a browser and a token.
+The dashboard automatically tracks which agent is doing what, where, and when.
## Security
diff --git a/docs/guides/multi-instance.md b/docs/guides/multi-instance.md
index bc9ffe6e..6fea0bb3 100644
--- a/docs/guides/multi-instance.md
+++ b/docs/guides/multi-instance.md
@@ -4,14 +4,13 @@ Pinchtab's multi-instance architecture enables running multiple isolated Chrome
## Getting Started
-### 1. Start the Dashboard
+### 1. Start the Orchestrator
```bash
-go build -o pinchtab ./cmd/pinchtab
-./pinchtab
+pinchtab
```
-The dashboard runs on **port 9867** and manages all instances.
+The orchestrator runs on **port 9867** and manages all instances.
### 2. Create Your First Instance
@@ -20,7 +19,7 @@ Create a headed instance (visible window) for interactive work:
```bash
curl -X POST http://localhost:9867/instances/launch \
-H "Content-Type: application/json" \
- -d '{"name":"work","headless":false}'
+ -d '{"mode":"headed"}'
```
**Response:**
@@ -28,26 +27,27 @@ curl -X POST http://localhost:9867/instances/launch \
{
"id": "inst_a365262a",
"profileId": "prof_7f3d1e8b",
- "profileName": "work",
+ "profileName": "instance-1672531200",
"port": "9868",
"headless": false,
"status": "starting",
- "startTime": "2026-02-28T21:00:00Z"
+ "startTime": "2026-03-01T06:30:00Z"
}
```
The instance gets:
-- **Auto-allocated port** (9868, 9869, ...)
-- **Hash-based ID** (inst_XXXXX) - stable and portable
-- **Profile isolation** - separate cookies, history, cache
-- **Chrome process** - running independently
+- **Auto-allocated port** (9868, 9869, ...) - unique per instance
+- **Hash-based ID** (`inst_XXXXXXXX`) - stable and portable
+- **Temporary profile** (auto-generated, deleted on stop)
+- **Chrome process** - running independently on its port
+- **Lazy initialization** - Chrome starts on first request
### 3. Navigate and Interact
-Navigate the instance to a URL:
+Navigate the instance via the orchestrator (recommended):
```bash
-curl -X POST http://localhost:9868/navigate \
+curl -X POST http://localhost:9867/instances/inst_a365262a/navigate \
-H "Content-Type: application/json" \
-d '{"url":"https://example.com"}'
```
@@ -63,18 +63,20 @@ curl -X POST http://localhost:9868/navigate \
Each navigation automatically creates a new tab. Use the `tabId` for subsequent operations on that specific tab.
+**Note:** You can also access the instance directly on its port (9868), but using the orchestrator proxy (`9867/instances/{id}/*`) is recommended for consistency.
+
### 4. Get Page Content
-Retrieve page snapshot (DOM, text, structured data):
+Retrieve page snapshot (DOM, text, structured data) via orchestrator:
```bash
-curl http://localhost:9868/snapshot?tabId=tab_19949f62
+curl http://localhost:9867/instances/inst_a365262a/snapshot
```
Or get just the text:
```bash
-curl http://localhost:9868/text?tabId=tab_19949f62
+curl http://localhost:9867/instances/inst_a365262a/text
```
### 5. Stop Instance
@@ -85,7 +87,7 @@ Release the instance and its allocated port:
curl -X POST http://localhost:9867/instances/inst_a365262a/stop
```
-Port 9868 becomes available for the next instance.
+Port 9868 becomes available for reuse by the next instance. The temporary profile is automatically deleted.
---
@@ -108,47 +110,55 @@ URLS=(
INSTANCES=()
-# Create instances
+echo "Creating 5 headless instances..."
+
+# Create instances (in parallel for speed)
for i in {1..5}; do
- INST=$(curl -s -X POST http://localhost:9867/instances/launch \
+ curl -s -X POST http://localhost:9867/instances/launch \
-H "Content-Type: application/json" \
- -d "{\"name\":\"scraper-$i\",\"headless\":true}")
-
- ID=$(echo "$INST" | jq -r '.id')
- PORT=$(echo "$INST" | jq -r '.port')
- INSTANCES+=("$ID:$PORT")
+ -d '{"mode":"headless"}' > /tmp/inst_$i.json &
+done
+wait
- echo "Created instance $i: $ID on port $PORT"
+# Parse instance IDs
+for i in {1..5}; do
+ ID=$(jq -r '.id' /tmp/inst_$i.json)
+ INSTANCES+=("$ID")
+ echo "Created instance $i: $ID"
done
-sleep 2 # Wait for Chrome initialization
+# Wait for instances to initialize (lazy Chrome start)
+sleep 2
-# Navigate all instances concurrently
+echo "Navigating all instances concurrently..."
+
+# Navigate all instances via orchestrator proxy (concurrent)
for i in "${!INSTANCES[@]}"; do
- IFS=: read ID PORT <<< "${INSTANCES[$i]}"
+ ID="${INSTANCES[$i]}"
URL="${URLS[$i]}"
- curl -s -X POST "http://localhost:$PORT/navigate" \
+ curl -s -X POST "http://localhost:9867/instances/$ID/navigate" \
-H "Content-Type: application/json" \
-d "{\"url\":\"$URL\"}" &
done
-
wait
echo "All pages loaded. Getting snapshots..."
# Get snapshots
for i in "${!INSTANCES[@]}"; do
- IFS=: read ID PORT <<< "${INSTANCES[$i]}"
+ ID="${INSTANCES[$i]}"
- curl -s "http://localhost:$PORT/snapshot" > "snapshot-$i.json"
+ curl -s "http://localhost:9867/instances/$ID/snapshot" > "snapshot-$i.json" &
done
+wait
# Cleanup
-for INST in "${INSTANCES[@]}"; do
- IFS=: read ID PORT <<< "$INST"
- curl -s -X POST "http://localhost:9867/instances/$ID/stop" > /dev/null
+echo "Stopping instances..."
+for ID in "${INSTANCES[@]}"; do
+ curl -s -X POST "http://localhost:9867/instances/$ID/stop" &
done
+wait
echo "Done! Scraped ${#URLS[@]} pages in parallel."
```
@@ -156,38 +166,44 @@ echo "Done! Scraped ${#URLS[@]} pages in parallel."
**Benefits:**
- 5 headless instances = 5x faster scraping than sequential
- No cookie/history interference between sites
-- Each instance gets its own port and Chrome process
-- Ports automatically reused when instances stop
+- Each instance gets isolated Chrome process and temporary profile
+- Ports automatically allocated (9868-9872) and reused on stop
+- All API calls go through orchestrator proxy for consistency
### Mixed Headed/Headless Testing
-Test web app with multiple browser profiles:
+Test web app with multiple instances in different modes:
```bash
+echo "Creating mixed instance setup for testing..."
+
# Headed instance for interactive debugging
WORK=$(curl -s -X POST http://localhost:9867/instances/launch \
-H "Content-Type: application/json" \
- -d '{"name":"dev","headless":false}' | jq -r '.id')
+ -d '{"mode":"headed"}' | jq -r '.id')
-# Headless instance for automated testing
+# Headless instance for automated testing (faster)
TEST=$(curl -s -X POST http://localhost:9867/instances/launch \
-H "Content-Type: application/json" \
- -d '{"name":"test","headless":true}' | jq -r '.id')
+ -d '{"mode":"headless"}' | jq -r '.id')
+
+# Another headed instance with persistent profile for state preservation
+pinchtab profile create testing-profile
+PROFILE_ID=$(pinchtab profiles | jq -r '.[] | select(.name=="testing-profile") | .id')
-# Debug instance with preserved state
-DEBUG=$(curl -s -X POST http://localhost:9867/instances/launch \
+DEBUG=$(curl -s -X POST http://localhost:9867/instances/start \
-H "Content-Type: application/json" \
- -d '{"name":"debug","headless":false}' | jq -r '.id')
+ -d '{"profileId":"'$PROFILE_ID'","mode":"headed"}' | jq -r '.id')
-echo "Dev (headed): $WORK on port 9868"
-echo "Test (headless): $TEST on port 9869"
-echo "Debug (headed): $DEBUG on port 9870"
+echo "Dev (headed): $WORK (temporary profile, no persistence)"
+echo "Test (headless): $TEST (temporary profile, fast)"
+echo "Debug (headed): $DEBUG (persistent profile, state saved)"
```
-You now have:
-- **dev instance** - visible window for manual testing, inspect elements, debug
-- **test instance** - headless for automated test suite, faster
-- **debug instance** - separate visible window to preserve state while testing
+You now have three independent instances:
+- **dev instance** - Visible window, temporary profile (good for quick testing)
+- **test instance** - Headless, temporary profile (best for automated tests, no display overhead)
+- **debug instance** - Visible window, persistent profile (login state preserved, can reconnect later)
### Load Distribution with Headless Fleet
@@ -199,32 +215,47 @@ Run a fleet of headless instances for high-throughput work:
FLEET_SIZE=10
INSTANCES=()
-echo "Launching fleet of $FLEET_SIZE instances..."
+echo "Launching fleet of $FLEET_SIZE headless instances..."
+# Create instances in parallel
for i in $(seq 1 $FLEET_SIZE); do
- INST=$(curl -s -X POST http://localhost:9867/instances/launch \
+ curl -s -X POST http://localhost:9867/instances/launch \
-H "Content-Type: application/json" \
- -d "{\"name\":\"fleet-$i\",\"headless\":true}")
+ -d '{"mode":"headless"}' > /tmp/inst_$i.json &
+done
+wait
- ID=$(echo "$INST" | jq -r '.id')
- PORT=$(echo "$INST" | jq -r '.port')
- INSTANCES+=("$ID:$PORT")
+# Collect instance IDs
+for i in $(seq 1 $FLEET_SIZE); do
+ ID=$(jq -r '.id' /tmp/inst_$i.json)
+ INSTANCES+=("$ID")
done
-echo "Fleet ready on ports 9868-9877"
+echo "Fleet ready: ${#INSTANCES[@]} instances allocated (ports 9868-907$((9868 + FLEET_SIZE - 1)))"
+
+# Wait for Chrome initialization
+sleep 3
+
+echo "Processing 100 tasks with round-robin distribution..."
# Distribute work across instances
-WORK_ITEMS=("task1" "task2" "task3" ... "task100")
+TASKS=($(seq 1 100))
INSTANCE_INDEX=0
-for TASK in "${WORK_ITEMS[@]}"; do
- # Round-robin distribution
- IFS=: read ID PORT <<< "${INSTANCES[$INSTANCE_INDEX % $FLEET_SIZE]}"
+# Process tasks in parallel (10 at a time)
+for TASK in "${TASKS[@]}"; do
+ # Round-robin: assign task to next instance in rotation
+ ID="${INSTANCES[$((INSTANCE_INDEX % $FLEET_SIZE))]}"
- # Process task on this instance
- curl -s -X POST "http://localhost:$PORT/navigate" \
+ # Send task to instance via orchestrator proxy
+ curl -s -X POST "http://localhost:9867/instances/$ID/navigate" \
-H "Content-Type: application/json" \
- -d "{\"url\":\"https://api.example.com?task=$TASK\"}" &
+ -d "{\"url\":\"https://api.example.com?task=$TASK\"}" > /dev/null &
+
+ # Keep 10 requests in flight at a time
+ if (( (INSTANCE_INDEX + 1) % 10 == 0 )); then
+ wait
+ fi
((INSTANCE_INDEX++))
done
@@ -232,49 +263,73 @@ done
wait
# Cleanup fleet
-for INST in "${INSTANCES[@]}"; do
- IFS=: read ID PORT <<< "$INST"
+echo "Cleaning up fleet..."
+for ID in "${INSTANCES[@]}"; do
curl -s -X POST "http://localhost:9867/instances/$ID/stop" > /dev/null &
done
-
wait
+
echo "Fleet cleaned up"
```
**Performance:**
-- 10 instances × 10 concurrent requests = 100 req/sec throughput
-- Each instance isolated = no performance degradation
-- Easy to scale: add more instances for more throughput
+- 10 instances = 10x parallelism (10 concurrent navigations)
+- Round-robin distribution = balanced load across fleet
+- Each instance isolated = no resource contention
+- Easy to scale: increase FLEET_SIZE for more throughput
+
+**Scaling tips:**
+- For 100 instances: Allocate 5-10 GB RAM + adjust ulimits
+- Monitor: `curl http://localhost:9867/instances | jq 'length'`
+- Cleanup: Remove instances when done to free resources
### Multi-Agent Coordination
-Have multiple agents work on different instances:
+Have multiple agents work on different instances with isolated state:
```bash
-# Agent A: LinkedIn scraper
-AGENT_A_INST=$(curl -s -X POST http://localhost:9867/instances/launch \
+# Create profiles for each agent (optional but recommended)
+pinchtab profile create agent-linkedin
+pinchtab profile create agent-twitter
+pinchtab profile create agent-news
+
+# Get profile IDs
+LINKEDIN_ID=$(pinchtab profiles | jq -r '.[] | select(.name=="agent-linkedin") | .id')
+TWITTER_ID=$(pinchtab profiles | jq -r '.[] | select(.name=="agent-twitter") | .id')
+NEWS_ID=$(pinchtab profiles | jq -r '.[] | select(.name=="agent-news") | .id')
+
+echo "Starting agents..."
+
+# Agent A: LinkedIn scraper with persistent profile
+AGENT_A=$(curl -s -X POST http://localhost:9867/instances/start \
-H "Content-Type: application/json" \
- -d '{"name":"linkedin","headless":true}' | jq -r '.id')
+ -d '{"profileId":"'$LINKEDIN_ID'","mode":"headless"}' | jq -r '.id')
-# Agent B: Twitter monitor
-AGENT_B_INST=$(curl -s -X POST http://localhost:9867/instances/launch \
+# Agent B: Twitter monitor with persistent profile
+AGENT_B=$(curl -s -X POST http://localhost:9867/instances/start \
-H "Content-Type: application/json" \
- -d '{"name":"twitter","headless":true}' | jq -r '.id')
+ -d '{"profileId":"'$TWITTER_ID'","mode":"headless"}' | jq -r '.id')
-# Agent C: News aggregator
-AGENT_C_INST=$(curl -s -X POST http://localhost:9867/instances/launch \
+# Agent C: News aggregator with persistent profile
+AGENT_C=$(curl -s -X POST http://localhost:9867/instances/start \
-H "Content-Type: application/json" \
- -d '{"name":"news","headless":true}' | jq -r '.id')
+ -d '{"profileId":"'$NEWS_ID'","mode":"headless"}' | jq -r '.id')
+
+echo "Agents running:"
+echo " LinkedIn agent: $AGENT_A"
+echo " Twitter agent: $AGENT_B"
+echo " News agent: $AGENT_C"
-# Each agent has its own isolated browser
-# They can run concurrently without interference
+# Each agent has its own isolated browser with persistent state
+# They can run concurrently without any interference
```
**Isolation Benefits:**
-- Agent A's LinkedIn cookies never touch Agent B's Twitter session
-- Agent B's JavaScript errors don't affect Agent C's news scraping
-- Each agent can have different profiles, user-agents, timezones
-- Clear audit trail: which agent ran on which instance
+- Agent A's LinkedIn login state saved to `agent-linkedin` profile
+- Agent B's Twitter cookies never touch Agent A's LinkedIn cookies
+- Agent C can run in parallel without affecting others
+- State persists: agents can reconnect later and resume work
+- Clear audit trail: which agent ran on which instance, when
---
@@ -322,17 +377,34 @@ This enables:
### Chrome Initialization
-Chrome starts automatically when the instance is created:
+Chrome uses **lazy initialization**: it starts when first needed, not at instance creation.
```bash
-POST /instances/launch → Chrome starts in background
- ↓ (instance ready immediately, no waiting)
- ↓ (Chrome initialization happens concurrently)
- ↓ (1-2 seconds later, Chrome is fully ready)
+POST /instances/launch → Instance created immediately
+ ↓ status: "starting" (orchestrator monitor probes /health)
+ ↓ First /health probe triggers Chrome initialization (8-20 seconds)
+ ↓ Chrome starts, TabManager initializes
+ ↓ Monitor's health check succeeds
+ ↓ status: "running" (instance ready for requests)
→ Ready for navigation requests
```
-**No lazy initialization:** Instance creation includes full Chrome startup, so first navigation is fast.
+**Why lazy init?** Reduces memory overhead for ephemeral instances, initialization happens automatically on first request.
+
+**Wait for ready state:**
+```bash
+# Create instance
+INST=$(curl -s -X POST http://localhost:9867/instances/launch | jq -r '.id')
+
+# Poll until running (Chrome will initialize during health checks)
+while [ "$(curl -s http://localhost:9867/instances/$INST | jq -r '.status')" != "running" ]; do
+ sleep 0.5
+done
+
+# Now safe to use
+curl -X POST http://localhost:9867/instances/$INST/navigate \
+ -d '{"url":"https://example.com"}'
+```
### Instance State
@@ -352,7 +424,7 @@ When instance stops, all state is persisted to disk. Profiles can be reused to r
### List All Instances
```bash
-curl http://localhost:9867/instances
+curl http://localhost:9867/instances | jq .
```
**Response:**
@@ -361,179 +433,334 @@ curl http://localhost:9867/instances
{
"id": "inst_a365262a",
"profileId": "prof_7f3d1e8b",
- "profileName": "work",
+ "profileName": "instance-1672531200",
"port": "9868",
"headless": false,
"status": "running",
- "startTime": "2026-02-28T21:00:00Z"
+ "startTime": "2026-03-01T06:30:00Z"
},
{
"id": "inst_b471d93c",
"profileId": "prof_5e2c7f1a",
- "profileName": "test",
+ "profileName": "instance-1672531205",
"port": "9869",
"headless": true,
"status": "running",
- "startTime": "2026-02-28T21:00:05Z"
+ "startTime": "2026-03-01T06:30:05Z"
}
]
```
-### Instance Health
+### Get Specific Instance Info
```bash
-# Check specific instance
-curl http://localhost:9868/health
+# Check status of specific instance
+curl http://localhost:9867/instances/inst_a365262a | jq .
# Response
-{"status":"ok","tabs":2}
+{
+ "id": "inst_a365262a",
+ "port": "9868",
+ "headless": false,
+ "status": "running",
+ "startTime": "2026-03-01T06:30:00Z",
+ "profileName": "instance-1672531200"
+}
+```
+
+### Instance Health and Tabs
+
+```bash
+# Check health and tab count for specific instance
+curl http://localhost:9867/instances/inst_a365262a/health
+
+# Response
+{
+ "status": "ok",
+ "tabs": 2
+}
+
+# List tabs in instance
+curl http://localhost:9867/instances/inst_a365262a/tabs | jq .
+```
+
+### Get Instance Logs
+
+```bash
+# View logs for debugging
+curl http://localhost:9867/instances/inst_a365262a/logs | head -50
```
### Dashboard Web UI
Open http://localhost:9867 in a browser to see:
-- Live instance list
-- Instance status and uptime
-- Profile information
+- Live instance list (real-time updates)
+- Instance status, port, mode, uptime
+- Profile information per instance
- Tab count per instance
-- Quick actions (create, stop, delete)
+- Quick actions (view logs, stop instance)
---
## Best Practices
-### 1. Name Instances Descriptively
+### 1. Use Persistent Profiles for Important Sessions
```bash
-# Good
-{"name":"linkedin-scraper-v1","headless":true}
-{"name":"user-test-headed","headless":false}
+# For agents that need persistent login state
+pinchtab profile create linkedin-scraper
+
+PROFILE_ID=$(pinchtab profiles | jq -r '.[] | select(.name=="linkedin-scraper") | .id')
-# Not ideal
-{"name":"instance1","headless":true}
-{"name":"test","headless":false}
+# Start instance with profile
+INST=$(curl -s -X POST http://localhost:9867/instances/start \
+ -H "Content-Type: application/json" \
+ -d '{"profileId":"'$PROFILE_ID'","mode":"headless"}' | jq -r '.id')
+
+# Login once, reuse session on next run
```
-Helps with monitoring and debugging.
+Persistent profiles preserve cookies, history, login state across restarts.
-### 2. Use Profiles for State Management
+### 2. Use Ephemeral (Temporary) Profiles for Isolation
```bash
-# Create with specific profile
-POST /instances/launch
-{"name":"customer-123","headless":true}
+# For one-off tasks, temporary profiles auto-delete on stop
+INST=$(curl -s -X POST http://localhost:9867/instances/launch \
+ -H "Content-Type: application/json" \
+ -d '{"mode":"headless"}' | jq -r '.id')
-# Profile persists across instance restarts
-# Same customer always gets same cookies, history, preferences
+# ... do work ...
+
+# Stop instance -> profile automatically deleted
+curl -X POST http://localhost:9867/instances/$INST/stop
```
-### 3. Stop Unused Instances
+Temporary profiles are auto-generated and deleted, good for clean slates.
+
+### 3. Wait for Instance Ready Before Using
```bash
-# Check instance list
-curl http://localhost:9867/instances | jq '.[] | select(.status=="stopped")'
+# Always poll status before first request
+INST=$(curl -s -X POST http://localhost:9867/instances/launch | jq -r '.id')
-# Stop idle instances
-for INST in ...; do
- curl -X POST http://localhost:9867/instances/$INST/stop
+# Wait for Chrome initialization
+while [ "$(curl -s http://localhost:9867/instances/$INST | jq -r '.status')" != "running" ]; do
+ sleep 0.5
done
+
+# Now safe to navigate
+curl -X POST http://localhost:9867/instances/$INST/navigate \
+ -d '{"url":"https://example.com"}'
```
-Frees ports and resources.
+Chrome lazy-initializes on first health check (~8-20 seconds).
### 4. Batch Operations for Performance
```bash
-# Launch 10 instances in parallel
+# Create 10 instances in parallel (faster than sequential)
for i in {1..10}; do
- curl -s -X POST http://localhost:9867/instances/launch ... &
+ curl -s -X POST http://localhost:9867/instances/launch \
+ -H "Content-Type: application/json" \
+ -d '{"mode":"headless"}' > /tmp/inst_$i.json &
done
wait
+
+# Extract IDs
+for i in {1..10}; do
+ jq -r '.id' /tmp/inst_$i.json
+done
```
-Much faster than sequential creation.
+Much faster than sequential instance creation.
-### 5. Handle Errors Gracefully
+### 5. Clean Up Stopped Instances
```bash
-# Check instance status before operations
-if curl -s http://localhost:9868/health | jq -e '.status == "ok"' > /dev/null; then
- echo "Instance ready, proceeding..."
-else
- echo "Instance not ready, waiting..."
- sleep 2
-fi
+# List all instances
+curl http://localhost:9867/instances | jq '.[] | {id, status}'
+
+# Stop idle instances to free resources
+curl http://localhost:9867/instances | jq -r '.[] | select(.status=="running") | .id' | while read ID; do
+ curl -s -X POST http://localhost:9867/instances/$ID/stop
+done
```
+Frees ports and RAM for new instances.
+
+### 6. Route All Requests Through Orchestrator
+
+```bash
+# DO: Use orchestrator proxy (recommended)
+curl -X POST http://localhost:9867/instances/$INST/navigate \
+ -d '{"url":"https://example.com"}'
+
+# AVOID: Direct port access (less consistent)
+curl -X POST http://localhost:$PORT/navigate \
+ -d '{"url":"https://example.com"}'
+```
+
+Orchestrator proxy ensures consistent routing and better monitoring.
+
+### 7. Monitor Resource Usage
+
+```bash
+# Check instance count
+INST_COUNT=$(curl -s http://localhost:9867/instances | jq 'length')
+echo "Running instances: $INST_COUNT"
+
+# Estimate RAM (headless ~80MB, headed ~150MB each)
+HEADLESS=$(curl -s http://localhost:9867/instances | jq '[.[] | select(.headless==true)] | length')
+HEADED=$(curl -s http://localhost:9867/instances | jq '[.[] | select(.headless==false)] | length')
+echo "Headless: $HEADLESS (~$((HEADLESS * 80))MB)"
+echo "Headed: $HEADED (~$((HEADED * 150))MB)"
+```
+
+Keep an eye on resource usage to avoid exhausting system limits.
+
---
## Architecture
```
-Dashboard (9867)
-├─ Orchestrator: manages instances
-├─ Profiles manager: manages Chrome profiles
-└─ Instance list: view all running instances
+Orchestrator (port 9867)
+├─ Instance manager: lifecycle (create, monitor, stop)
+├─ Profile manager: persistent browser state directories
+├─ Port allocator: assigns ports 9868-9968
+└─ Dashboard UI: monitor instances, create/stop via web
-Instance 1 (9868, profile=work, headless=false)
+Instance 1 (port 9868, temp profile)
├─ Bridge: HTTP API for this instance only
-├─ Chrome: independent browser process
+├─ Chrome: independent browser process (lazy-init)
+├─ Profile: temporary, deleted on stop
└─ Tabs: multiple tabs in same browser
-Instance 2 (9869, profile=test, headless=true)
+Instance 2 (port 9869, profile=work)
├─ Bridge: HTTP API for this instance only
-├─ Chrome: independent browser process
+├─ Chrome: independent browser process (lazy-init)
+├─ Profile: persistent (work), survives restarts
└─ Tabs: multiple tabs in same browser
-Instance 3 (9870, profile=scraping, headless=true)
+Instance 3 (port 9870, profile=linkedin)
├─ Bridge: HTTP API for this instance only
-├─ Chrome: independent browser process
+├─ Chrome: independent browser process (lazy-init)
+├─ Profile: persistent (linkedin), survives restarts
└─ Tabs: multiple tabs in same browser
```
-Each instance is **completely isolated**: separate port, separate Chrome process, separate profile.
+Each instance is **completely isolated**:
+- **Separate port** (9868-9968, auto-allocated)
+- **Separate Chrome process** (independent browser, no cross-contamination)
+- **Separate profile** (cookies, history, cache all isolated)
+- **Separate HTTP API** (Bridge server on instance port)
+
+**Orchestrator forwards requests** from `9867/instances/{id}/*` to the appropriate instance port for clean routing.
---
## Troubleshooting
-### Instance not starting
+### Instance Not Starting (Status: "error")
```bash
-# Check logs
-tail -f /var/log/pinchtab.log
+# Check instance error details
+curl http://localhost:9867/instances/$INST | jq '.error'
-# Verify port is free
-lsof -i :9868
+# Get full logs
+curl http://localhost:9867/instances/$INST/logs
-# Check Chrome availability
-which google-chrome chromium-browser chrome
+# Common issues:
+# - "Chrome binary not found" → Set CHROME_BIN env var
+# - "Port already in use" → Change INSTANCE_PORT_START/END
+# - "process exited early" → Check logs for Chrome crash reason
```
-### Chrome window not visible (headed mode)
+### Instance Stuck in "starting"
```bash
-# Ensure DISPLAY is set (Linux)
+# Wait longer (Chrome init takes 8-20 seconds)
+sleep 10
+
+# Check status again
+curl http://localhost:9867/instances/$INST | jq '.status'
+
+# If still "starting" after 30s, likely Chrome init failed
+# Check logs:
+curl http://localhost:9867/instances/$INST/logs | tail -20
+```
+
+### Chrome Window Not Visible (Headed Mode)
+
+```bash
+# On Linux, ensure DISPLAY is set
+echo $DISPLAY # Should show :0 or :1, etc.
+
+# If not set, enable X11 forwarding
export DISPLAY=:0
-# Or use Xvfb (Linux headless display)
-xvfb-run -a ./pinchtab
+# For SSH access, use X11 forwarding
+ssh -X user@server
+pinchtab instance launch --mode headed
```
-### Port conflicts
+### Port Conflicts
```bash
-# If default range is in use, change it
+# Check which ports are in use
+lsof -i :9868 # Check specific port
+netstat -tlnp | grep 986 # Check range
+
+# If port conflict, change instance port range
export INSTANCE_PORT_START=10000
export INSTANCE_PORT_END=10100
-./pinchtab
+pinchtab
+
+# Or specify port for specific instance
+curl -X POST http://localhost:9867/instances/launch \
+ -d '{"mode":"headless","port":"10000"}'
+```
+
+### Chrome Binary Not Found
+
+```bash
+# Check if Chrome is installed
+which google-chrome
+which chromium
+which chromium-browser
+
+# If not found, install Chrome/Chromium
+
+# Or set explicit path
+export CHROME_BIN=/path/to/chrome
+pinchtab
```
-### Memory usage
+### Memory Usage Growing
-Each headless instance: ~50-80 MB
-Each headed instance: ~100-150 MB (includes window server overhead)
+```bash
+# Monitor instance count and resource usage
+curl http://localhost:9867/instances | jq 'length'
+
+# Estimate RAM per instance
+# Headless: ~80 MB each
+# Headed: ~150 MB each
-For 100 instances: ~5-10 GB RAM
+# Stop old instances to free memory
+curl -X POST http://localhost:9867/instances/$OLD_INST/stop
-Monitor with: `top`, `htop`, or systemd memory limits
+# For limits, set systemd cgroup or Docker memory limit
+# docker run --memory=8g pinchtab
+```
+
+### Can't Access Instance After Stop/Start
+
+```bash
+# Instance IDs are stable, but ports change on restart
+# Always use orchestrator proxy:
+curl http://localhost:9867/instances/$INST/navigate \
+ -d '{"url":"https://example.com"}'
+
+# Don't rely on cached port numbers
+PORT=$(curl http://localhost:9867/instances/$INST | jq -r '.port')
+```