High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.
feat: profile IDs + start/stop by ID endpoints + headed mode guide
Mario7063988e8b86
diff --git a/README.md b/README.mdindex 3c6bd958..8f60efc6 100644--- a/README.md+++ b/README.md@@ -262,6 +262,14 @@ In headed mode, log into sites in the visible Chrome window once; cookies and lo| `PINCHTAB_HEADED` | *(unset)* | If set, auto-launched instance is headed; unset means headless || `PINCHTAB_DASHBOARD_URL` | `http://localhost:$BRIDGE_PORT` | CLI helper base URL for `pinchtab connect` |+## Headed Mode: Human + Agent Workflows++Headed mode lets humans and agents share the same browser session. Human logs in, handles 2FA and CAPTCHAs. Agent takes over via HTTP API — same cookies, same session. Profiles persist across restarts, so you log in once and automate forever.++The dashboard exposes `POST /start/{id}` and `POST /stop/{id}` for easy profile lifecycle management — agents can spin up a profile, do their work, and shut it down with three API calls.++See **[docs/headed-mode-guide.md](docs/headed-mode-guide.md)** for the full walkthrough with real examples.+## Identifying Pinchtab Chrome InstancesNeed to distinguish Pinchtab's Chrome from your regular browser? Use `CHROME_BINARY` to point at a renamed Chrome copy, `CHROME_FLAGS` to tag instances in `ps`, or rely on the separate profile directory that's already built-in.diff --git a/cmd_dashboard.go b/cmd_dashboard.goindex 16539978..ce406421 100644--- a/cmd_dashboard.go+++ b/cmd_dashboard.go@@ -33,6 +33,7 @@ func runDashboard() {profMgr := NewProfileManager(profilesDir)dashboard := NewDashboard(nil)orchestrator := NewOrchestrator(profilesDir)+ orchestrator.SetProfileManager(profMgr)mux := http.NewServeMux()diff --git a/docs/headed-mode-guide.md b/docs/headed-mode-guide.mdnew file mode 100644index 00000000..4f0dcdc8--- /dev/null+++ b/docs/headed-mode-guide.md@@ -0,0 +1,185 @@+# Headed Mode: When Your Agent Needs a Human in the Loop++Most browser automation assumes you're either fully automated or fully manual. Real workflows aren't like that.++Your agent can fill out a 50-field form in seconds, but it can't solve a CAPTCHA. It can navigate to the right page, but it can't approve a bank transfer. It can scrape a dashboard, but first someone needs to log in with 2FA.++That's what headed mode is for.++## The Problem with Headless-Only++Headless browsers are great until they aren't. The moment you hit any of these, you're stuck:++- **Login walls** — OAuth flows, 2FA, SMS codes+- **CAPTCHAs** — reCAPTCHA, hCaptcha, Cloudflare challenges+- **Visual verification** — "does this look right?" before submitting+- **Sensitive actions** — payments, deletions, things you want a human to approve++The usual workaround? Copy cookies from a real browser, hope they don't expire, pray the session doesn't get flagged. Fragile, annoying, doesn't scale.++## How Pinchtab Solves It++Pinchtab's headed mode gives you a real Chrome window that both humans and agents share. Same browser, same session, same cookies. No hacks.++The flow is simple:++1. **Human** opens a profile, logs in, handles 2FA+2. **Agent** takes over via HTTP API — same browser, same session+3. **Human** can watch, intervene, or take back control at any time++The agent doesn't need screenshots to "see" the page. It reads the accessibility tree — the same structure screen readers use. Structured, fast, cheap on tokens.++## Profiles: Persistent Identity++Each Chrome profile is a complete browser identity — cookies, localStorage, saved passwords, extensions, everything. Pinchtab stores them in `~/.pinchtab/profiles/`.++Profiles persist across restarts. Log in once to Gmail on Monday, and your agent can read email on Friday without re-authenticating.++```bash+# List profiles+curl http://localhost:9867/profiles+```++```json+[+ {+ "id": "278be873adeb",+ "name": "Pinchtab org",+ "accountEmail": "[email protected]",+ "accountName": "Luigi Agosti",+ "useWhen": "For gmail and x.com"+ }+]+```++Every profile gets a stable 12-character hex ID derived from its name. Use IDs in automation — they're URL-safe and won't break if you have spaces or special characters in profile names.++## Start and Stop with One Call++The dashboard exposes two endpoints that make profile management trivial for agents:++```bash+# Start a profile (port auto-allocated)+curl -X POST http://localhost:9867/start/278be873adeb+```++```json+{+ "id": "Pinchtab org-56490",+ "name": "Pinchtab org",+ "port": "56490",+ "status": "starting",+ "url": "http://localhost:56490"+}+```++The response tells you which port the instance landed on. All your API calls go to that port:++```bash+PORT=56490++# Navigate+curl -X POST http://localhost:$PORT/navigate \+ -d '{"url": "https://mail.google.com"}'++# Read the inbox+curl "http://localhost:$PORT/snapshot?maxTokens=4000"++# Done — shut it down+curl -X POST http://localhost:9867/stop/278be873adeb+```++You can also pass a specific port or run headless if you want:++```bash+curl -X POST http://localhost:9867/start/278be873adeb \+ -H 'Content-Type: application/json' \+ -d '{"port": "9868", "headless": true}'+```++## A Real Example: Reading Email++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/278be873adeb)+PORT=$(echo $INSTANCE | jq -r .port)++# 2. Navigate to Gmail+curl -s -X POST http://localhost:$PORT/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+```++Output:+```+"unread, X, New login to X from ChromeDesktop on Mac, 11:44 AM, ..."+"unread, Amazon Route 53, Registration of narrowexperts.com succeeded, 11:26 AM, ..."+"unread, Amazon Route 53, Registration of expertsytem.com succeeded, 11:26 AM, ..."+```++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/278be873adeb+```++## When to Use Headed vs Headless++| Scenario | Mode | Why |+|---|---|---|+| First login to a service | **Headed** | Human handles 2FA/CAPTCHA |+| Daily email check | Either | Session persists, no login needed |+| Scraping public data | **Headless** | No human interaction needed |+| Filling forms with approval | **Headed** | Human reviews before submit |+| CI/CD automation | **Headless** | No display available |+| Debugging agent behavior | **Headed** | Watch what the agent does |++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++Running `pinchtab dashboard` gives you a web UI at `http://localhost:9867/dashboard` 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+- Stop instances gracefully++The dashboard itself doesn't run Chrome. It's a lightweight control plane that spawns and manages profile instances as separate processes.++For agents that prefer CLI over UI:++```bash+# Resolve a running profile to its URL+pinchtab connect "Pinchtab org"+# → http://localhost:56490+```++## Multiple Profiles, Multiple Agents++Nothing stops you from running several profiles at once. Different accounts, different purposes:++```bash+# Work email+curl -X POST http://localhost:9867/start/278be873adeb++# Personal Twitter+curl -X POST http://localhost:9867/start/a1b2c3d4e5f6++# Research browser (no login, disposable)+curl -X POST http://localhost:9867/start/f6e5d4c3b2a1+```++Each gets its own port, its own Chrome process, its own isolated session. Agents can work across all of them simultaneously.++---++Headed mode isn't about choosing between humans and agents. It's about letting them work together — each doing what they're best at. Humans handle the messy, contextual, trust-requiring parts. Agents handle the repetitive, fast, scale-requiring parts.++That's the whole point. 🦀diff --git a/main.go b/main.goindex 084de466..99ef71a6 100644--- a/main.go+++ b/main.go@@ -114,6 +114,7 @@ func main() {profMgr := NewProfileManager(profilesDir)dashboard := NewDashboard(nil)orchestrator := NewOrchestrator(profilesDir)+ orchestrator.SetProfileManager(profMgr)initTargetID := chromedp.FromContext(browserCtx).Target.TargetIDbridge.RegisterTab(string(initTargetID), browserCtx)diff --git a/orchestrator_handlers.go b/orchestrator_handlers.goindex 637b437c..4a4ccc0e 100644--- a/orchestrator_handlers.go+++ b/orchestrator_handlers.go@@ -4,6 +4,7 @@ import ("encoding/json""fmt""log/slog"+ "net""net/http""strings")@@ -17,6 +18,8 @@ func (o *Orchestrator) RegisterHandlers(mux *http.ServeMux) {mux.HandleFunc("GET /instances/{id}/logs", o.handleLogs)mux.HandleFunc("GET /instances/tabs", o.handleAllTabs)mux.HandleFunc("GET /instances/{id}/proxy/screencast", o.handleProxyScreencast)+ mux.HandleFunc("POST /start/{id}", o.handleStartByID)+ mux.HandleFunc("POST /stop/{id}", o.handleStopByID)}func (o *Orchestrator) handleList(w http.ResponseWriter, r *http.Request) {@@ -137,6 +140,79 @@ func (o *Orchestrator) handleProxyScreencast(w http.ResponseWriter, r *http.RequjsonResp(w, 200, map[string]string{"wsUrl": targetURL})}+func (o *Orchestrator) handleStartByID(w http.ResponseWriter, r *http.Request) {+ id := r.PathValue("id")+ if o.profiles == nil {+ jsonErr(w, 500, fmt.Errorf("profile manager not configured"))+ return+ }+ name, err := o.profiles.FindByID(id)+ if err != nil {+ jsonErr(w, 404, err)+ return+ }++ // Optional port from request body; auto-allocate if not provided.+ var req struct {+ Port string `json:"port"`+ Headless bool `json:"headless"`+ }+ _ = json.NewDecoder(r.Body).Decode(&req)+ port := req.Port+ if port == "" {+ p, err := findFreePort()+ if err != nil {+ jsonErr(w, 500, fmt.Errorf("failed to allocate port: %w", err))+ return+ }+ port = p+ }++ slog.Info("start-by-id request", "profileId", id, "profile", name, "port", port, "headless", req.Headless)+ inst, err := o.Launch(name, port, req.Headless)+ if isStartingConflict(err) {+ slog.Warn("start-by-id blocked by starting instance; stopping and retrying", "profile", name)+ if stopErr := o.StopProfile(name); stopErr != nil {+ jsonErr(w, 409, err)+ return+ }+ inst, err = o.Launch(name, port, req.Headless)+ }+ if err != nil {+ jsonErr(w, 409, err)+ return+ }+ jsonResp(w, 201, inst)+}++func (o *Orchestrator) handleStopByID(w http.ResponseWriter, r *http.Request) {+ id := r.PathValue("id")+ if o.profiles == nil {+ jsonErr(w, 500, fmt.Errorf("profile manager not configured"))+ return+ }+ name, err := o.profiles.FindByID(id)+ if err != nil {+ jsonErr(w, 404, err)+ return+ }+ if err := o.StopProfile(name); err != nil {+ jsonErr(w, 404, err)+ return+ }+ jsonResp(w, 200, map[string]string{"status": "stopped", "id": id, "name": name})+}++func findFreePort() (string, error) {+ l, err := net.Listen("tcp", "127.0.0.1:0")+ if err != nil {+ return "", err+ }+ port := l.Addr().(*net.TCPAddr).Port+ _ = l.Close()+ return fmt.Sprintf("%d", port), nil+}+func isStartingConflict(err error) bool {return err != nil && strings.Contains(err.Error(), "already has an active instance (starting)")}diff --git a/orchestrator_types.go b/orchestrator_types.goindex a5a66dac..79c56df6 100644--- a/orchestrator_types.go+++ b/orchestrator_types.go@@ -16,6 +16,7 @@ type Orchestrator struct {instances map[string]*InstancebaseDir stringbinary string+ profiles *ProfileManagermu sync.RWMutexclient *http.Client}@@ -99,6 +100,11 @@ func NewOrchestrator(baseDir string) *Orchestrator {}}+// SetProfileManager sets the profile manager for ID-based lookups.+func (o *Orchestrator) SetProfileManager(pm *ProfileManager) {+ o.profiles = pm+}+func installStableBinary(src, dst string) error {in, err := os.Open(src)if err != nil {diff --git a/profiles_manager.go b/profiles_manager.goindex a509ead7..2dd79064 100644--- a/profiles_manager.go+++ b/profiles_manager.go@@ -1,6 +1,8 @@package mainimport (+ "crypto/sha256"+ "encoding/hex""encoding/json""fmt""io/fs"@@ -13,6 +15,12 @@ import ("time")+// profileID generates a stable 12-char hex ID from the profile name.+func profileID(name string) string {+ h := sha256.Sum256([]byte(name))+ return hex.EncodeToString(h[:6])+}+type ProfileManager struct {baseDir stringtracker *ActionTracker@@ -20,11 +28,13 @@ type ProfileManager struct {}type ProfileMeta struct {+ ID string `json:"id,omitempty"`UseWhen string `json:"useWhen,omitempty"`Description string `json:"description,omitempty"`}type ProfileInfo struct {+ ID string `json:"id,omitempty"`Name string `json:"name"`Path string `json:"path"`CreatedAt time.Time `json:"createdAt"`@@ -91,7 +101,14 @@ func (pm *ProfileManager) profileInfo(name string) (ProfileInfo, error) {chromeProfileName, accountEmail, accountName, hasAccount := readChromeProfileIdentity(dir)meta := readProfileMeta(dir)+ // Backfill ID for profiles created before ID generation was added.+ if meta.ID == "" {+ meta.ID = profileID(name)+ _ = writeProfileMeta(dir, meta)+ }+return ProfileInfo{+ ID: meta.ID,Name: name,Path: dir,CreatedAt: fi.ModTime(),@@ -137,6 +154,9 @@ func (pm *ProfileManager) ImportWithMeta(name, sourcePath string, meta ProfileMeif err := pm.Import(name, sourcePath); err != nil {return err}+ if meta.ID == "" {+ meta.ID = profileID(name)+ }dest := filepath.Join(pm.baseDir, name)return writeProfileMeta(dest, meta)}@@ -157,6 +177,9 @@ func (pm *ProfileManager) CreateWithMeta(name string, meta ProfileMeta) error {if err := pm.Create(name); err != nil {return err}+ if meta.ID == "" {+ meta.ID = profileID(name)+ }dest := filepath.Join(pm.baseDir, name)return writeProfileMeta(dest, meta)}@@ -383,3 +406,24 @@ func (pm *ProfileManager) UpdateMeta(name string, meta map[string]string) errorreturn writeProfileMeta(dir, existing)}++// FindByID returns the profile name matching the given ID, or empty string if not found.+func (pm *ProfileManager) FindByID(id string) (string, error) {+ pm.mu.RLock()+ defer pm.mu.RUnlock()++ entries, err := os.ReadDir(pm.baseDir)+ if err != nil {+ return "", err+ }+ for _, entry := range entries {+ if !entry.IsDir() {+ continue+ }+ meta := readProfileMeta(filepath.Join(pm.baseDir, entry.Name()))+ if meta.ID == id {+ return entry.Name(), nil+ }+ }+ return "", fmt.Errorf("profile with id %q not found", id)+}diff --git a/skill/pinchtab/SKILL.md b/skill/pinchtab/SKILL.mdindex 3693b7d3..a041a39b 100644--- a/skill/pinchtab/SKILL.md+++ b/skill/pinchtab/SKILL.md@@ -146,6 +146,68 @@ PINCHTAB_BASE_URL="$(pinchtab connect <profile-name>)"curl "$PINCHTAB_BASE_URL/health"```+## Profile Management (Dashboard Mode)++When running `pinchtab dashboard`, profiles are managed via the dashboard API on port 9867.++### List profiles++```bash+curl http://localhost:9867/profiles+```++Returns array of profiles with `id`, `name`, `accountEmail`, `useWhen`, etc.++### Start a profile by ID++```bash+# Auto-allocate port (recommended)+curl -X POST http://localhost:9867/start/278be873adeb++# With specific port and headless mode+curl -X POST http://localhost:9867/start/278be873adeb \+ -H 'Content-Type: application/json' \+ -d '{"port": "9868", "headless": true}'+```++Returns the instance info including the allocated `port`. Use that port for all subsequent API calls (navigate, snapshot, action, etc.).++### Stop a profile by ID++```bash+curl -X POST http://localhost:9867/stop/278be873adeb+```++### Check profile instance status++```bash+curl http://localhost:9867/profiles/Pinchtab%20org/instance+```++### Typical agent flow with profiles++```bash+# 1. List profiles to find the right one+PROFILES=$(curl -s http://localhost:9867/profiles)+# Pick the profile ID you need++# 2. Start the profile+INSTANCE=$(curl -s -X POST http://localhost:9867/start/$PROFILE_ID)+PORT=$(echo $INSTANCE | jq -r .port)++# 3. Use the instance (all API calls go to the instance port)+curl -X POST http://localhost:$PORT/navigate -H 'Content-Type: application/json' \+ -d '{"url": "https://mail.google.com"}'+curl http://localhost:$PORT/snapshot?maxTokens=4000++# 4. Stop when done+curl -s -X POST http://localhost:9867/stop/$PROFILE_ID+```++### Profile IDs++Each profile gets a stable 12-char hex ID (SHA-256 of name, truncated) stored in `profile.json`. The ID is generated at creation time and never changes. Use IDs instead of names in automation — they're URL-safe and stable.+## Core WorkflowThe typical agent loop: