Skip to content

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.md
index 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 Instances
Need 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.go
index 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.md
new file mode 100644
index 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.go
index 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.TargetID
bridge.RegisterTab(string(initTargetID), browserCtx)
diff --git a/orchestrator_handlers.go b/orchestrator_handlers.go
index 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.Requ
jsonResp(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.go
index a5a66dac..79c56df6 100644
--- a/orchestrator_types.go
+++ b/orchestrator_types.go
@@ -16,6 +16,7 @@ type Orchestrator struct {
instances map[string]*Instance
baseDir string
binary string
+ profiles *ProfileManager
mu sync.RWMutex
client *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.go
index a509ead7..2dd79064 100644
--- a/profiles_manager.go
+++ b/profiles_manager.go
@@ -1,6 +1,8 @@
package main
import (
+ "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 string
tracker *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 ProfileMe
if 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) error
return 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.md
index 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 Workflow
The typical agent loop: