High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.
docs: update guides/common-patterns.md for orchestrator architecture
Mariofe53a872735a
diff --git a/docs/guides/common-patterns.md b/docs/guides/common-patterns.mdindex 40bd45f4..1eff8655 100644--- a/docs/guides/common-patterns.md+++ b/docs/guides/common-patterns.md@@ -13,7 +13,7 @@ Use when you need to **see what's happening**:```bashcurl -X POST http://localhost:9867/instances/launch \-H "Content-Type: application/json" \- -d '{"name":"debug","headless":false}'+ -d '{"mode":"headed"}'```**Use cases:**@@ -38,21 +38,23 @@ curl -X POST http://localhost:9867/instances/launch \# Create a headed instance for manual testingINST=$(curl -s -X POST http://localhost:9867/instances/launch \-H "Content-Type: application/json" \- -d '{"name":"manual-qa","headless":false}' | jq -r '.id')+ -d '{"mode":"headed"}' | jq -r '.id')-PORT=$(curl -s http://localhost:9867/instances/$INST | jq -r '.port')--echo "Manual testing instance running on port $PORT"+echo "Manual testing instance: $INST"echo "Chrome window is open - interact manually or use API calls"-# Optionally navigate to starting URL-curl -s -X POST "http://localhost:$PORT/navigate" \+# Wait for Chrome to initialize+sleep 2++# Optionally navigate to starting URL (via orchestrator proxy)+curl -s -X POST "http://localhost:9867/instances/$INST/navigate" \-H "Content-Type: application/json" \-d '{"url":"https://app.example.com"}'echo "Navigate the app manually, then run automated tests..."-sleep 300 # Keep instance running for 5 minutes+sleep 300+# Keep instance running for 5 minutescurl -X POST "http://localhost:9867/instances/$INST/stop"```@@ -63,7 +65,7 @@ Use when you need **speed and efficiency**:```bashcurl -X POST http://localhost:9867/instances/launch \-H "Content-Type: application/json" \- -d '{"name":"worker","headless":true}'+ -d '{"mode":"headless"}'```**Use cases:**@@ -91,10 +93,9 @@ INSTANCES=()for i in {1..5}; doINST=$(curl -s -X POST http://localhost:9867/instances/launch \-H "Content-Type: application/json" \- -d "{\"name\":\"test-worker-$i\",\"headless\":true}" | jq -r '.id')+ -d '{"mode":"headless"}' | jq -r '.id')- PORT=$(curl -s http://localhost:9867/instances/$INST | jq -r '.port')- INSTANCES+=("$INST:$PORT")+ INSTANCES+=("$INST")doneecho "Created 5 parallel test workers"@@ -109,17 +110,17 @@ TEST_URLS=()for i in "${!INSTANCES[@]}"; do- IFS=: read INST PORT <<< "${INSTANCES[$i]}"+ INST="${INSTANCES[$i]}"URL="${TEST_URLS[$i]}"- # Run test in parallel+ # Run test in parallel (via orchestrator proxy)(- curl -s -X POST "http://localhost:$PORT/navigate" \+ curl -s -X POST "http://localhost:9867/instances/$INST/navigate" \-H "Content-Type: application/json" \-d "{\"url\":\"$URL\"}" > /dev/null# Verify page loaded- TITLE=$(curl -s "http://localhost:$PORT/snapshot" | jq -r '.title')+ TITLE=$(curl -s "http://localhost:9867/instances/$INST/snapshot" | jq -r '.title')echo "Test $i: $TITLE") &done@@ -127,8 +128,7 @@ donewait# Cleanup-for INST_PORT in "${INSTANCES[@]}"; do- IFS=: read INST PORT <<< "$INST_PORT"+for INST in "${INSTANCES[@]}"; docurl -s -X POST "http://localhost:9867/instances/$INST/stop" > /dev/nulldone@@ -143,14 +143,15 @@ Typical production setup:# 1 headed for interactive debuggingHEADED=$(curl -s -X POST http://localhost:9867/instances/launch \-H "Content-Type: application/json" \- -d '{"name":"qa-debug","headless":false}' | jq -r '.id')+ -d '{"mode":"headed"}' | jq -r '.id')# 10 headless for bulk operationsfor i in {1..10}; docurl -s -X POST http://localhost:9867/instances/launch \-H "Content-Type: application/json" \- -d "{\"name\":\"worker-$i\",\"headless\":true}" > /dev/null+ -d '{"mode":"headless"}' > /dev/null &done+waitecho "Setup: 1 headed (debug) + 10 headless (workers)"```@@ -161,18 +162,22 @@ echo "Setup: 1 headed (debug) + 10 headless (workers)"### Round-Robin Distribution-Distribute requests evenly across instances:+Distribute requests evenly across instances via orchestrator:```bash#!/bin/bash-INSTANCES=(- "http://localhost:9868"- "http://localhost:9869"- "http://localhost:9870"- "http://localhost:9871"- "http://localhost:9872"-)+# Create 5 instances+INSTANCES=()+for i in {1..5}; do+ INST=$(curl -s -X POST http://localhost:9867/instances/launch \+ -H "Content-Type: application/json" \+ -d '{"mode":"headless"}' | jq -r '.id')+ INSTANCES+=("$INST")+done++# Wait for Chrome initialization+sleep 3URLS=("https://example.com/page1"@@ -185,12 +190,12 @@ URLS=("https://example.com/page8")-# Distribute evenly+# Distribute evenly via orchestrator proxyfor i in "${!URLS[@]}"; doURL="${URLS[$i]}"- INSTANCE="${INSTANCES[$((i % ${#INSTANCES[@]}))]}"+ INST="${INSTANCES[$((i % ${#INSTANCES[@]}))]}"- curl -s -X POST "$INSTANCE/navigate" \+ curl -s -X POST "http://localhost:9867/instances/$INST/navigate" \-H "Content-Type: application/json" \-d "{\"url\":\"$URL\"}" &done@@ -199,43 +204,46 @@ wait```**Result:**-- URLs 1,6 → Instance 1 (9868)-- URLs 2,7 → Instance 2 (9869)-- URLs 3,8 → Instance 3 (9870)-- URLs 4 → Instance 4 (9871)-- URLs 5 → Instance 5 (9872)--Each instance handles roughly equal work.+Each instance handles roughly equal work (round-robin).### Weighted Distribution-Send more work to faster instances:+Send more work to better instances (e.g., faster systems get more requests):```bash#!/bin/bash-# Instances with weights-declare -A WEIGHTS=(- ["http://localhost:9868"]=3 # Fast SSD- ["http://localhost:9869"]=2 # Standard- ["http://localhost:9870"]=1 # Slower-)--# Create weighted list+# Create weighted instance poolINSTANCES=()-for INST in "${!WEIGHTS[@]}"; do- WEIGHT=${WEIGHTS[$INST]}- for ((j=0; j<WEIGHT; j++)); do- INSTANCES+=("$INST")- done++# Add 3 copies of fast instance (handles 3/6 = 50% of work)+for i in {1..3}; do+ INST=$(curl -s -X POST http://localhost:9867/instances/launch \+ -H "Content-Type: application/json" \+ -d '{"mode":"headless"}' | jq -r '.id')+ INSTANCES+=("$INST")done+# Add 2 copies of standard instance (handles 2/6 = 33% of work)+for i in {1..2}; do+ INST=$(curl -s -X POST http://localhost:9867/instances/launch \+ -H "Content-Type: application/json" \+ -d '{"mode":"headless"}' | jq -r '.id')+ INSTANCES+=("$INST")+done++# Add 1 copy of slow instance (handles 1/6 = 17% of work)+INST=$(curl -s -X POST http://localhost:9867/instances/launch \+ -H "Content-Type: application/json" \+ -d '{"mode":"headless"}' | jq -r '.id')+INSTANCES+=("$INST")+# Distribute using weighted listfor i in "${!URLS[@]}"; doURL="${URLS[$i]}"- INSTANCE="${INSTANCES[$((i % ${#INSTANCES[@]}))]}"+ INST="${INSTANCES[$((i % ${#INSTANCES[@]}))]}"- curl -s -X POST "$INSTANCE/navigate" \+ curl -s -X POST "http://localhost:9867/instances/$INST/navigate" \-H "Content-Type: application/json" \-d "{\"url\":\"$URL\"}" &done@@ -244,60 +252,75 @@ wait```**Result:**-- Fast instance handles 50% of work (3/6 slots)-- Standard instance handles 33% of work (2/6 slots)-- Slow instance handles 17% of work (1/6 slots)+Fast instances handle more load, slower instances handle less.### Queue-Based Distribution-Process a work queue, distributing dynamically:+Process a work queue dynamically, keeping a fixed number of concurrent jobs:```bash#!/bin/bash-# Instance pool-INSTANCE_POOL=(- "http://localhost:9868"- "http://localhost:9869"- "http://localhost:9870"-)+# Create instance pool (3 workers)+INSTANCES=()+for i in {1..3}; do+ INST=$(curl -s -X POST http://localhost:9867/instances/launch \+ -H "Content-Type: application/json" \+ -d '{"mode":"headless"}' | jq -r '.id')+ INSTANCES+=("$INST")+done-# Work queue+# Work queue (100 URLs)QUEUE=("https://example.com/1""https://example.com/2""https://example.com/3"- ...+ # ... up to ..."https://example.com/100")-# Process queue with max concurrent jobs-MAX_JOBS=${#INSTANCE_POOL[@]}+# Process queue with max concurrent jobs (use 'wait -n' for job-level control)+MAX_JOBS=3CURRENT_JOB=0-RUNNING=0-while [ $CURRENT_JOB -lt ${#QUEUE[@]} ] || [ $RUNNING -gt 0 ]; do- # Start new jobs while under limit and queue has items- while [ $RUNNING -lt $MAX_JOBS ] && [ $CURRENT_JOB -lt ${#QUEUE[@]} ]; do- URL="${QUEUE[$CURRENT_JOB]}"- INSTANCE="${INSTANCE_POOL[$((CURRENT_JOB % MAX_JOBS))]}"-- (- curl -s -X POST "$INSTANCE/navigate" \- -H "Content-Type: application/json" \- -d "{\"url\":\"$URL\"}"- echo "Processed: $URL"- ) &-- ((CURRENT_JOB++))- ((RUNNING++))- done+# Start initial batch+for i in $(seq 0 $((MAX_JOBS - 1))); do+ [ $CURRENT_JOB -lt ${#QUEUE[@]} ] || break- # Wait for a job to complete+ URL="${QUEUE[$CURRENT_JOB]}"+ INST="${INSTANCES[$((CURRENT_JOB % MAX_JOBS))]}"++ (+ curl -s -X POST "http://localhost:9867/instances/$INST/navigate" \+ -H "Content-Type: application/json" \+ -d "{\"url\":\"$URL\"}" > /dev/null+ echo "Processed: $URL"+ ) &++ ((CURRENT_JOB++))+done++# Process remaining queue+while [ $CURRENT_JOB -lt ${#QUEUE[@]} ]; do+ URL="${QUEUE[$CURRENT_JOB]}"+ INST="${INSTANCES[$((CURRENT_JOB % MAX_JOBS))]}"++ (+ curl -s -X POST "http://localhost:9867/instances/$INST/navigate" \+ -H "Content-Type: application/json" \+ -d "{\"url\":\"$URL\"}" > /dev/null+ echo "Processed: $URL"+ ) &++ # Wait for a background job to completewait -n- ((RUNNING--))++ ((CURRENT_JOB++))done+# Wait for remaining jobs+wait+echo "Queue processing complete"```@@ -312,34 +335,38 @@ Each user gets their own instance with persistent state:```bash#!/bin/bash-# Create instance per user-function create_user_instance() {- local USER_ID=$1-- curl -s -X POST http://localhost:9867/instances/launch \- -H "Content-Type: application/json" \- -d "{\"name\":\"user-$USER_ID\",\"headless\":true}"-}+# Create persistent profiles for each user+pinchtab profile create user-1+pinchtab profile create user-2+pinchtab profile create user-3-# User 1: Gets instance with profile 'user-1'-U1=$(create_user_instance 1 | jq -r '.id')+# Get profile IDs+U1_PROF=$(pinchtab profiles | jq -r '.[] | select(.name=="user-1") | .id')+U2_PROF=$(pinchtab profiles | jq -r '.[] | select(.name=="user-2") | .id')+U3_PROF=$(pinchtab profiles | jq -r '.[] | select(.name=="user-3") | .id')-# User 2: Gets instance with profile 'user-2'-U2=$(create_user_instance 2 | jq -r '.id')+# Create instances with profiles+U1=$(curl -s -X POST http://localhost:9867/instances/start \+ -H "Content-Type: application/json" \+ -d '{"profileId":"'$U1_PROF'","mode":"headless"}' | jq -r '.id')-# User 3: Gets instance with profile 'user-3'-U3=$(create_user_instance 3 | jq -r '.id')+U2=$(curl -s -X POST http://localhost:9867/instances/start \+ -H "Content-Type: application/json" \+ -d '{"profileId":"'$U2_PROF'","mode":"headless"}' | jq -r '.id')++U3=$(curl -s -X POST http://localhost:9867/instances/start \+ -H "Content-Type: application/json" \+ -d '{"profileId":"'$U3_PROF'","mode":"headless"}' | jq -r '.id')# Each user has:# - Separate Chrome process-# - Separate cookies (login sessions)-# - Separate history-# - Separate local storage+# - Persistent profile (survives restarts)+# - Separate cookies (login sessions preserved)+# - Separate history, local storage# - No interference between users-# User 1 navigates-PORT_U1=$(curl -s http://localhost:9867/instances/$U1 | jq -r '.port')-curl -s -X POST "http://localhost:$PORT_U1/navigate" \+# User 1 navigates (via orchestrator proxy)+curl -s -X POST "http://localhost:9867/instances/$U1/navigate" \-H "Content-Type: application/json" \-d '{"url":"https://app.example.com/login?user=1"}'