High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.
docs: update core-concepts.md with proper API examples and references
Marioe954a9994a67
diff --git a/docs/core-concepts.md b/docs/core-concepts.mdindex 66391aa3..1908c5a9 100644--- a/docs/core-concepts.md+++ b/docs/core-concepts.md@@ -2,57 +2,101 @@PinchTab is an HTTP server that controls four key entities: **PinchTab itself**, **Instances**, **Profiles**, and **Tabs**.+**See also:**+- [Instance API Reference](references/instance-api.md) — Complete instance endpoints+- [Tabs API Reference](references/tabs-api.md) — Tab management endpoints+- [Profile API Reference](references/profile-api.md) — Profile management endpoints+---## PinchTab-The **HTTP server controller** that manages all instances, profiles, and tabs.+The **HTTP server controller** (orchestrator) that manages all instances, profiles, and tabs.-- Listens on a port (default `9867`)+- Listens on port `9867` (configurable, dashboard + API)- Routes requests to the appropriate instance-- Manages instance lifecycle-- Provides a unified HTTP API+- Manages instance lifecycle (launch, monitor, stop)+- Provides unified HTTP API for all operations+- No Chrome process itself — purely orchestrator```bash-# Start PinchTab (the controller)+# Start PinchTab orchestrator (default: port 9867)pinchtab# Listening on http://localhost:9867++# Or specify port+BRIDGE_PORT=9870 pinchtab+# Listening on http://localhost:9870```---## Instance-A **running Chrome process** with an optional profile, listening on a port.+A **running Chrome process** with an optional profile, auto-allocated to a unique port (9868-9968 by default).- One Chrome browser per instance- Optional profile (see [Profile](#profile) below)- Can host multiple tabs-- Isolated from other instances-- Identified by port or instance ID+- Completely isolated from other instances+- Identified by instance ID: `inst_XXXXXXXX` (hash-based, stable)+- Auto-allocated to unique port in 9868-9968 range+- Lazy Chrome initialization (starts on first request, not at creation)**Key constraint:** One instance = one Chrome process = zero or one profile.+### Creating Instances++Instances are managed by the orchestrator via the API (not by running separate processes).+```bash-# Start an instance (default: no profile)-pinchtab-# or with a specific profile-BRIDGE_PROFILE=work pinchtab --port 9867+# CLI: Create instance (headless by default)+pinchtab instance launch++# CLI: Create headed (visible) instance+pinchtab instance launch --mode headed++# CLI: Create with specific port+pinchtab instance launch --mode headed --port 9999++# Curl: Create instance via API+curl -X POST http://localhost:9867/instances/launch \+ -H "Content-Type: application/json" \+ -d '{"mode": "headed", "port": "9999"}'++# Response+{+ "id": "inst_0a89a5bb",+ "profileId": "prof_278be873",+ "profileName": "Instance-...",+ "port": "9868",+ "headless": false,+ "status": "starting"+}```### Multiple Instances-You can run multiple instances in parallel for isolation and scalability:+You can run multiple instances simultaneously for isolation and scalability. The orchestrator manages them automatically:```bash-# Terminal 1: Instance 1 (no profile)-pinchtab --port 9867+# Terminal 1: Start orchestrator+pinchtab-# Terminal 2: Instance 2 (with profile "work")-BRIDGE_PROFILE=work pinchtab --port 9868+# Terminal 2: Create multiple instances+for i in 1 2 3; do+ pinchtab instance launch --mode headless+done-# Terminal 3: Instance 3 (with profile "personal")-BRIDGE_PROFILE=personal pinchtab --port 9869+# List all instances+curl http://localhost:9867/instances | jq .++# Response: 3 independent instances on ports 9868, 9869, 9870+[+ {"id": "inst_0a89a5bb", "port": "9868", "status": "running"},+ {"id": "inst_1b9a5dcc", "port": "9869", "status": "running"},+ {"id": "inst_2c8a5eef", "port": "9870", "status": "running"}+]```Each instance is completely independent — no shared state, no cookie leakage, no resource contention.@@ -61,99 +105,162 @@ Each instance is completely independent — no shared state, no cookie leakage,## Profile-A **browser profile** within an instance. Optional.+A **browser profile** (Chrome user data directory) containing browser state. Optional per instance.-- Holds browser state: cookies, local storage, cache, browsing history+- Holds browser state: cookies, local storage, cache, browsing history, extensions- Only one profile per instance- Multiple tabs can share the same profile (and its state)+- Identified by profile ID: `prof_XXXXXXXX` (hash-based, stable)- Useful for: user accounts, login sessions, multi-tenant workflows+- Persistent across instance restarts++**Key constraint:** Instance without a profile = ephemeral, no persistent state across restarts.-**Key constraint:** Instance without a profile = no persistent state across restarts.+### Managing Profiles```bash-# Instance with default (no) profile-pinchtab+# CLI: List all profiles+pinchtab profiles++# CLI: Create profile+pinchtab profile create my-profile++# Curl: List profiles (excludes temporary auto-generated profiles)+curl http://localhost:9867/profiles | jq .++# Response+[+ {+ "id": "278be873",+ "name": "my-profile",+ "created": "2026-03-01T05:21:38.274Z",+ "diskUsage": 5242880,+ "source": "created"+ }+]+```++### Using Profiles with Instances-# Instance with "work" profile-BRIDGE_PROFILE=work pinchtab+```bash+# Create instance with specific profile+curl -X POST http://localhost:9867/instances/start \+ -H "Content-Type: application/json" \+ -d '{"profileId": "278be873"}'-# Instance with "personal" profile-BRIDGE_PROFILE=personal pinchtab+# Or via CLI+pinchtab instance launch # Uses temp auto-generated profile```### Profile Use Cases**Separate User Accounts:**```text-Instance 1 (profile: user-alice)+Instance 1 (profile: alice)├── Tab 1: [email protected] logged in└── Tab 2: [email protected] dashboard-Instance 2 (profile: user-bob)+Instance 2 (profile: bob)├── Tab 1: [email protected] logged in└── Tab 2: [email protected] dashboard```+```bash+# Create profiles for each user+pinchtab profile create alice+pinchtab profile create bob++# Start instances with profiles+curl -X POST http://localhost:9867/instances/start \+ -d '{"profileId": "alice-profile-id"}'++curl -X POST http://localhost:9867/instances/start \+ -d '{"profileId": "bob-profile-id"}'++# Each instance has isolated cookies/auth+```+**Login Once, Use Anywhere:**```bash-# Instance 1: Login-curl -X POST http://localhost:9867/tab \- -d '{"action":"new","url":"https://example.com/login"}'+# Start instance with persistent profile+curl -X POST http://localhost:9867/instances/start \+ -d '{"profileId": "work"}'++# Navigate and log in+curl -X POST http://localhost:9867/instances/inst_xyz/navigate \+ -d '{"url": "https://example.com/login"}'# ... fill login form, click submit ...-# Later (even after restart): Reuse session-BRIDGE_PROFILE=work pinchtab # Profile restored-curl ... # Cookies intact, still logged in+# Later (even after instance restart): Profile is persistent+pinchtab instance launch # Or restart orchestrator+# Cookies intact, still logged in via profile's saved state```---## Tab-A **browser tab** within an instance (and its profile).+A **browser tab** (webpage) within an instance and its profile.-- Single webpage-- Has its own DOM, URL, accessibility tree-- Identified by `tabId`+- Single webpage with its own DOM, URL, accessibility tree+- Identified by tab ID: `tab_XXXXXXXX` (hash-based, stable)- Tabs are ephemeral (don't survive instance restart unless using a profile)- Multiple tabs can be open simultaneously in one instance-- Each tab has stable element references (e0, e1...) for interaction+- Each tab has stable element references (e0, e1...) for DOM interaction+- Can navigate, take snapshots, execute actions, evaluate JavaScript```bash-# Create tab (returns tabId)-curl -X POST http://localhost:9867/tab \- -d '{"action":"new","url":"https://example.com"}' | jq '.tabId'-# Returns: "abc123"+# Create tab in instance (returns tabId)+curl -X POST http://localhost:9867/tabs/open \+ -H "Content-Type: application/json" \+ -d '{"instanceId": "inst_0a89a5bb", "url": "https://example.com"}' | jq '.id'+# Returns: "tab_abc123"++# Or via CLI+pinchtab tab open inst_0a89a5bb https://example.com++# Get tab info+curl http://localhost:9867/tabs/tab_abc123 | jq .++# Navigate tab+curl -X POST http://localhost:9867/instances/inst_0a89a5bb/navigate \+ -d '{"url": "https://google.com"}'++# Take snapshot (DOM structure)+curl http://localhost:9867/instances/inst_0a89a5bb/snapshot | jq .-# Interact with tab-curl "http://localhost:9867/snapshot?tabId=abc123"-curl -X POST http://localhost:9867/action \- -d '{"kind":"click","ref":"e5","tabId":"abc123"}'+# Interact with tab (click, type, etc.)+curl -X POST http://localhost:9867/instances/inst_0a89a5bb/action \+ -d '{"kind": "click", "ref": "e5"}'# Close tab-curl -X POST http://localhost:9867/tab \- -d '{"action":"close","tabId":"abc123"}'+curl -X POST http://localhost:9867/tabs/tab_abc123/close++# Or via CLI+pinchtab tab close tab_abc123```+**See:** [Tabs API Reference](references/tabs-api.md) for complete operations.+---## Hierarchy```text-PinchTab (HTTP server controller on port 9867)+PinchTab Orchestrator (HTTP server on port 9867)│- ├── Instance 1 (port 9867, default profile)- │ ├── Tab 1 (https://example.com)- │ ├── Tab 2 (https://google.com)- │ └── Tab 3 (https://github.com)+ ├── Instance 1 (inst_0a89a5bb, port 9868, temp profile)+ │ ├── Tab 1 (tab_xyz123, https://example.com)+ │ ├── Tab 2 (tab_xyz124, https://google.com)+ │ └── Tab 3 (tab_xyz125, https://github.com)│- ├── Instance 2 (port 9868, profile "work")- │ ├── Tab 1 (internal dashboard, logged in as alice)- │ └── Tab 2 (internal docs)+ ├── Instance 2 (inst_1b9a5dcc, port 9869, profile: work)+ │ ├── Tab 1 (tab_abc001, internal dashboard, logged in as alice)+ │ └── Tab 2 (tab_abc002, internal docs)│- └── Instance 3 (port 9869, profile "personal")- ├── Tab 1 (gmail, logged in as [email protected])- └── Tab 2 (bank.com)+ └── Instance 3 (inst_2c8a5eef, port 9870, profile: personal)+ ├── Tab 1 (tab_def001, gmail, logged in as [email protected])+ └── Tab 2 (tab_def002, bank.com)```---@@ -175,56 +282,120 @@ PinchTab (HTTP server controller on port 9867)### Workflow 1: Single Instance, Multiple Tabs```bash-# Start instance+# Terminal 1: Start orchestratorpinchtab-# Terminal 2: Create tabs and work-curl -X POST http://localhost:9867/tab -d '{"action":"new","url":"https://example.com"}'-curl -X POST http://localhost:9867/tab -d '{"action":"new","url":"https://google.com"}'-curl http://localhost:9867/tabs # List all tabs+# Terminal 2: Create instance+INST=$(pinchtab instance launch --mode headless)+# Returns: inst_0a89a5bb++# Create multiple tabs in the same instance+curl -X POST http://localhost:9867/tabs/open \+ -d '{"instanceId":"'$INST'","url":"https://example.com"}'++curl -X POST http://localhost:9867/tabs/open \+ -d '{"instanceId":"'$INST'","url":"https://google.com"}'++# List all tabs across all instances+curl http://localhost:9867/tabs | jq .++# Or tabs in specific instance+curl http://localhost:9867/instances/$INST/tabs | jq .```### Workflow 2: Multiple Instances, Separate Profiles```bash-# Terminal 1: Instance for user Alice-BRIDGE_PROFILE=alice pinchtab --port 9867+# Create persistent profiles for Alice and Bob+pinchtab profile create alice+pinchtab profile create bob-# Terminal 2: Instance for user Bob-BRIDGE_PROFILE=bob pinchtab --port 9868+# Get profile IDs+ALICE_ID=$(pinchtab profiles | jq -r '.[] | select(.name=="alice") | .id')+BOB_ID=$(pinchtab profiles | jq -r '.[] | select(.name=="bob") | .id')-# Terminal 3: Create tabs in both-curl -X POST http://localhost:9867/tab \- -d '{"action":"new","url":"https://app.example.com"}' # Alice's tab+# Start instance for Alice+INST_ALICE=$(curl -X POST http://localhost:9867/instances/start \+ -d '{"profileId":"'$ALICE_ID'"}' | jq -r '.id')-curl -X POST http://localhost:9868/tab \- -d '{"action":"new","url":"https://app.example.com"}' # Bob's tab-```+# Start instance for Bob+INST_BOB=$(curl -X POST http://localhost:9867/instances/start \+ -d '{"profileId":"'$BOB_ID'"}' | jq -r '.id')++# Create tabs in both instances with isolated cookies+curl -X POST http://localhost:9867/tabs/open \+ -d '{"instanceId":"'$INST_ALICE'","url":"https://app.example.com"}'++curl -X POST http://localhost:9867/tabs/open \+ -d '{"instanceId":"'$INST_BOB'","url":"https://app.example.com"}'-Both users are logged in simultaneously, cookies isolated.+# Login in each instance separately — profiles keep sessions isolated+```-### Workflow 3: Stateless (No Profile)+### Workflow 3: Ephemeral Instance (No Profile)```bash-# Start instance without profile-pinchtab+# Create instance without persistent profile (temporary auto-generated)+INST=$(pinchtab instance launch)-# Create tab, use it, close it-curl -X POST http://localhost:9867/tab -d '{"action":"new","url":"https://example.com"}'+# Create tab, use it+curl -X POST http://localhost:9867/tabs/open \+ -d '{"instanceId":"'$INST'","url":"https://example.com"}'# ... work ...-# Restart instance-pkill pinchtab-pinchtab-# Tab is gone, state is gone++# Stop instance+pinchtab instance stop $INST++# Tab is gone, all cookies gone — clean slate next time+```++### Workflow 4: Polling for Instance Ready Status++```bash+# Create instance (returns with status "starting")+INST=$(pinchtab instance launch | jq -r '.id')++# Poll until running (monitor's health check initializes Chrome)+while true; do+ STATUS=$(curl http://localhost:9867/instances/$INST | jq -r '.status')+ if [ "$STATUS" == "running" ]; then+ echo "Instance ready!"+ break+ fi+ echo "Instance status: $STATUS, waiting..."+ sleep 0.5+done++# Now safe to make requests to the instance+curl -X POST http://localhost:9867/instances/$INST/navigate \+ -d '{"url":"https://example.com"}'```---+## Mental Model++```+What you control │ What it is │ Identified by+─────────────────────────┼──────────────────────────┼─────────────────────+PinchTab Orchestrator │ HTTP server controller │ port (9867 default)+Instance │ Chrome process │ inst_XXXXXXXX (hash ID)+Profile (optional) │ Browser state directory │ prof_XXXXXXXX (hash ID)+Tab │ Single webpage │ tab_XXXXXXXX (hash ID)+```+## Summary-- **PinchTab** is the HTTP server controller-- **Instance** is a Chrome process (optional profile, multiple tabs)-- **Profile** is optional state (cookies, auth, history)-- **Tab** is the actual webpage you interact with+- **PinchTab Orchestrator** is the HTTP server that manages everything+- **Instance** is a running Chrome process with optional profile and multiple tabs+- **Profile** is optional persistent browser state (cookies, auth, history)+- **Tab** is the actual webpage you navigate and interact with++**Key insights:**+- Instances are launched via API and auto-allocated unique ports (9868-9968)+- Instances are lazy: Chrome initializes on first request, not at creation time+- Profiles are optional but provide persistent state across instance restarts+- Tabs are ephemeral unless using a persistent profile+- Instance + Profile + Tabs = the complete mental model for using PinchTab effectively-**Key insight:** Instance + Profile + Tabs = the complete mental model for using PinchTab effectively.+**Next:** See [Instance API Reference](references/instance-api.md), [Tabs API Reference](references/tabs-api.md), and [Profile API Reference](references/profile-api.md) for complete endpoint documentation.