High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.
docs: add server mode example, remove duplicate
Bosch7896bec28c5a
diff --git a/docs/examples/pinchtab-server.md b/docs/examples/pinchtab-server.mdnew file mode 100644index 00000000..f18fcdbc--- /dev/null+++ b/docs/examples/pinchtab-server.md@@ -0,0 +1,358 @@+# Example: Server Smoke Test++This example is a happy-path smoke test for a running `pinchtab server` (orchestrator mode) on `127.0.0.1:9867`.++It is useful when you want to verify that the multi-instance orchestrator can:+- respond to health checks+- list and manage profiles+- launch and stop instances+- route requests to instances+- use the `--instance` CLI flag++For the server-mode mental model, see [Multi-Instance Guide](../guides/multi-instance.md).++## Prerequisites++Start the server:++```bash+pinchtab server+# or just: pinchtab (server is the default mode)+```++Set the base URL:++```bash+BASE=http://127.0.0.1:9867+```++The commands below assume `jq` is installed.++## 1. Check Health++```bash+curl -s "$BASE/health" | jq .+```++```bash+# CLI alternative+pinchtab health+```++```jsonc+// Response+{+ "status": "ok",+ "mode": "dashboard"+}+```++## 2. List Profiles++```bash+curl -s "$BASE/profiles" | jq .+```++```bash+# CLI alternative+pinchtab profiles+```++```jsonc+// Response+[+ {+ "id": "prof_967ae079",+ "name": "default",+ "path": "/Users/you/.pinchtab/profiles/default",+ "pathExists": true,+ "running": false,+ "sizeMB": 160.17+ }+]+```++## 3. List Instances++```bash+curl -s "$BASE/instances" | jq .+```++```bash+# CLI alternative+pinchtab instances+```++```jsonc+// Response (empty initially)+[]+```++## 4. Launch An Instance++```bash+INST=$(curl -s -X POST "$BASE/instances/launch" \+ -H "Content-Type: application/json" \+ -d '{"name":"my-profile","mode":"headless"}' \+ | jq -r '.id')++echo "$INST"+```++```jsonc+// Response+{+ "id": "inst_944a07ad",+ "profileId": "prof_910b1739",+ "profileName": "my-profile",+ "port": "9871",+ "headless": true,+ "status": "starting",+ "startTime": "2026-03-07T19:29:54.066542+01:00",+ "attached": false+}+```++> **Note:** The instance will transition from `starting` to `running` within a few seconds.++## 5. Get Instance Details++```bash+curl -s "$BASE/instances/$INST" | jq .+```++```jsonc+// Response+{+ "id": "inst_944a07ad",+ "profileId": "prof_910b1739",+ "profileName": "my-profile",+ "port": "9871",+ "headless": true,+ "status": "running",+ "startTime": "2026-03-07T19:29:54.066542+01:00",+ "attached": false+}+```++## 6. Navigate On An Instance++Use the orchestrator proxy:++```bash+curl -s -X POST "$BASE/instances/$INST/navigate" \+ -H "Content-Type: application/json" \+ -d '{"url":"https://github.com/pinchtab/pinchtab"}' | jq .+```++Or connect directly to the instance port:++```bash+PORT=$(curl -s "$BASE/instances/$INST" | jq -r '.port')+curl -s -X POST "http://127.0.0.1:$PORT/navigate" \+ -H "Content-Type: application/json" \+ -d '{"url":"https://github.com/pinchtab/pinchtab"}' | jq .+```++```bash+# CLI alternative (uses --instance flag)+pinchtab nav --instance $INST https://github.com/pinchtab/pinchtab+```++```jsonc+// Response+{+ "tabId": "E291F6815F61C58B0C9EA9129F960744",+ "title": "GitHub - pinchtab/pinchtab",+ "url": "https://github.com/pinchtab/pinchtab"+}+```++## 7. List Tabs On An Instance++```bash+curl -s "$BASE/instances/$INST/tabs" | jq .+```++```bash+# CLI alternative+pinchtab tabs --instance $INST+```++```jsonc+// Response+{+ "tabs": [+ {+ "id": "E291F6815F61C58B0C9EA9129F960744",+ "title": "GitHub - pinchtab/pinchtab",+ "type": "page",+ "url": "https://github.com/pinchtab/pinchtab"+ }+ ]+}+```++## 8. Snapshot On An Instance++```bash+curl -s "$BASE/instances/$INST/snapshot?filter=interactive" | jq '.nodes[:5]'+```++```bash+# CLI alternative+pinchtab snap -i -c --instance $INST+```++```bash+# CLI output+# GitHub - pinchtab/pinchtab | https://github.com/pinchtab/pinchtab | 144 nodes+e0:link "Skip to content"+e1:link "GitHub Homepage"+e2:link "pinchtab"+e5:button "Search or jump to…"+...+```++## 9. Click On An Instance++```bash+curl -s "$BASE/instances/$INST/snapshot?filter=interactive" > /dev/null+curl -s -X POST "$BASE/instances/$INST/action" \+ -H "Content-Type: application/json" \+ -d '{"kind":"click","ref":"e5"}' | jq .+```++```bash+# CLI alternative+pinchtab snap -i --instance $INST > /dev/null+pinchtab click e5 --instance $INST+```++```jsonc+// Response+{+ "success": true,+ "result": {+ "clicked": true+ }+}+```++## 10. Screenshot On An Instance++```bash+curl -s "$BASE/instances/$INST/screenshot" > screenshot.jpg+ls -lh screenshot.jpg+```++```bash+# CLI alternative+pinchtab ss -o screenshot.jpg --instance $INST+```++```bash+# Output+Saved screenshot.jpg (97376 bytes)+```++## 11. PDF On An Instance++```bash+curl -s "$BASE/instances/$INST/pdf" > page.pdf+ls -lh page.pdf+```++```bash+# CLI alternative+pinchtab pdf -o page.pdf --instance $INST+```++```bash+# Output+Saved page.pdf (1492879 bytes)+```++## 12. Launch A Second Instance++```bash+INST2=$(curl -s -X POST "$BASE/instances/launch" \+ -H "Content-Type: application/json" \+ -d '{"name":"another-profile","mode":"headless"}' \+ | jq -r '.id')++echo "Instance 2: $INST2"+curl -s "$BASE/instances" | jq '.[].profileName'+```++```jsonc+// Response+"my-profile"+"another-profile"+```++## 13. Stop An Instance++```bash+curl -s -X DELETE "$BASE/instances/$INST" | jq .+```++```jsonc+// Response+{+ "stopped": true+}+```++## 14. Attach To External Chrome (Optional)++If you have Chrome running with `--remote-debugging-port=9222`:++```bash+# Get the CDP URL+CDP_URL=$(curl -s http://localhost:9222/json/version | jq -r '.webSocketDebuggerUrl')++# Attach via Pinchtab (requires attach.enabled: true in config)+curl -s -X POST "$BASE/instances/attach" \+ -H "Content-Type: application/json" \+ -d "{\"cdpUrl\":\"$CDP_URL\"}" | jq .+```++```jsonc+// Response+{+ "id": "inst_abc123",+ "attached": true,+ "cdpUrl": "ws://localhost:9222/devtools/browser/..."+}+```++## CLI Quick Reference (Server Mode)++| Action | CLI Command |+|--------|-------------|+| Health check | `pinchtab health` |+| List profiles | `pinchtab profiles` |+| List instances | `pinchtab instances` |+| Navigate | `pinchtab nav <url> --instance <id>` |+| Snapshot | `pinchtab snap -i -c --instance <id>` |+| Click | `pinchtab click <ref> --instance <id>` |+| Screenshot | `pinchtab ss -o file.jpg --instance <id>` |+| PDF export | `pinchtab pdf -o file.pdf --instance <id>` |++> **Tip:** Use `pinchtab instances` to get instance IDs, then use `--instance <id>` or `-I <id>` with other commands.++## What This Example Proves++If the full sequence works, your server/orchestrator can:+- start and manage multiple Chrome instances+- launch instances with different profiles+- route requests to specific instances+- proxy all bridge endpoints through the orchestrator+- stop instances cleanly+- optionally attach to external Chrome instances++If this example fails, check:+- the server is running on `127.0.0.1:9867`+- Chrome can be started successfully+- for attach: `attach.enabled: true` is set in configdiff --git a/docs/examples/pinchtab.md b/docs/examples/pinchtab.mddeleted file mode 100644index 036fdac4..00000000--- a/docs/examples/pinchtab.md+++ /dev/null@@ -1,200 +0,0 @@-# Example: Bridge Smoke Test--This example is a happy-path smoke test for a running `pinchtab bridge` instance on `127.0.0.1:9867`.--It is useful when you want to verify that the single-instance runtime can:-- respond to health checks-- open and list tabs-- navigate and inspect pages-- perform actions-- capture screenshots and PDFs-- read cookies-- use tab locking--For the bridge-mode mental model, see [Expert Guide: Bridge Mode](../guides/expert-bridge-mode.md).--## Prerequisites--Start the bridge:--```bash-pinchtab bridge-```--Set the base URL:--```bash-BASE=http://127.0.0.1:9867-```--The commands below assume `jq` is installed.--## 1. Check Health--```bash-curl -s "$BASE/health" | jq .-```--You should get a JSON health response from the bridge runtime.--## 2. Open A Tab--```bash-TAB=$(curl -s -X POST "$BASE/tab" \- -H "Content-Type: application/json" \- -d '{"action":"new","url":"https://www.wikipedia.org"}' \- | jq -r '.tabId // .id')--echo "$TAB"-```--This opens a new tab and stores the tab ID in `TAB`.--## 3. List Tabs--```bash-curl -s "$BASE/tabs" | jq .-```--This confirms the bridge sees the tab you just opened.--## 4. Capture An Interactive Snapshot--```bash-curl -s "$BASE/tabs/$TAB/snapshot?filter=interactive" | jq .-```--This returns the accessibility-style tree used for refs and actions.--## 5. Extract Page Text--```bash-curl -s "$BASE/tabs/$TAB/text" | jq .-```--This verifies text extraction works for the current tab.--## 6. Find A Search Input Ref--```bash-SEARCH_REF=$(curl -s "$BASE/tabs/$TAB/snapshot?filter=interactive" \- | jq -r '.. | objects | select(.role? == "textbox" or .role? == "searchbox" or .name? == "Search Wikipedia") | .ref' \- | head -1)--echo "$SEARCH_REF"-```--This extracts one interactive ref from the snapshot.--## 7. Fill And Press Enter--```bash-curl -s -X POST "$BASE/tabs/$TAB/action" \- -H "Content-Type: application/json" \- -d "{\"kind\":\"fill\",\"ref\":\"$SEARCH_REF\",\"text\":\"Browser automation\"}" | jq .--curl -s -X POST "$BASE/tabs/$TAB/action" \- -H "Content-Type: application/json" \- -d '{"kind":"press","key":"Enter"}' | jq .-```--This verifies action execution and should trigger navigation.--## 8. Snapshot Again After Navigation--```bash-curl -s "$BASE/tabs/$TAB/snapshot?filter=interactive" | jq .-```--This confirms the bridge remains usable after a page transition.--## 9. Take A Screenshot--```bash-curl -s "$BASE/tabs/$TAB/screenshot" > smoke.jpg-ls -lh smoke.jpg-```--This verifies screenshot generation.--## 10. Export A PDF--```bash-curl -s "$BASE/tabs/$TAB/pdf" > smoke.pdf-ls -lh smoke.pdf-```--This verifies PDF export.--## 11. Read Cookies--```bash-curl -s "$BASE/tabs/$TAB/cookies" | jq .-```--This checks cookie retrieval for the active page.--## 12. Lock And Unlock The Tab--```bash-curl -s -X POST "$BASE/tabs/$TAB/lock" \- -H "Content-Type: application/json" \- -d '{"owner":"smoke-test","ttl":60}' | jq .--curl -s -X POST "$BASE/tabs/$TAB/unlock" \- -H "Content-Type: application/json" \- -d '{"owner":"smoke-test"}' | jq .-```--This verifies tab ownership locking works.--## 13. Open A Second Tab--```bash-TAB2=$(curl -s -X POST "$BASE/tab" \- -H "Content-Type: application/json" \- -d '{"action":"new","url":"https://example.com"}' \- | jq -r '.tabId // .id')--echo "$TAB2"-curl -s "$BASE/tabs" | jq .-```--This confirms the bridge handles multiple tabs in one runtime.--## Optional: Evaluate JavaScript--This only works if `evaluate` is enabled in config.--```bash-curl -s -X POST "$BASE/tabs/$TAB/evaluate" \- -H "Content-Type: application/json" \- -d '{"expression":"document.title"}' | jq .-```--## Optional: Use The Top-Level Shorthand Endpoints--```bash-curl -s -X POST "$BASE/navigate" \- -H "Content-Type: application/json" \- -d '{"url":"https://example.com"}' | jq .--curl -s "$BASE/snapshot?filter=interactive" | jq .-```--These verify the direct bridge shortcuts in addition to the tab-scoped endpoints.--## What This Example Proves--If the full sequence works, your bridge runtime can:-- start and respond to API requests-- manage multiple tabs-- inspect page structure and text-- execute actions-- render visual outputs-- support locking and basic browser state APIs--If this example fails, check:-- the bridge is running on `127.0.0.1:9867`-- Chrome can be started successfully-- required features such as `evaluate` are enabled before testing them