Skip to content

High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.

chore: clarification on different modes

Luigi Agostiad6a9849ae80
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8933a2fb..235230cd 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,6 +1,36 @@
# Changelog
-## Unreleased (v0.4.0)
+## Unreleased
+
+- TBD
+
+## v0.5.0
+
+### Added
+- **Dashboard orchestrator mode** — `pinchtab dashboard` runs profiles/instances without launching a browser in the dashboard process
+- **Profile lifecycle APIs** — launch, stop-by-profile, per-profile instance status, and aggregated tabs across running instances
+- **`pinchtab connect <profile>`** — resolve a running profile instance URL from dashboard state
+- **Direct launch backup command** in dashboard launch modal for manual fallback
+- **Run helper script** — `scripts/run_pinchtab.sh` for local build + start convenience
+
+### Changed
+- **Default runtime mode** — `pinchtab` now starts headless by default; use `BRIDGE_HEADLESS=false` for headed mode
+- **Headed-first dashboard UX** — profile launches from dashboard are headed, with profile state and account details shown in cards
+- **Live view UX** — live screencast moved from dedicated screen to profile-scoped popup modal
+- **Profiles view defaults** — dashboard opens on Profiles, with profile/status actions prioritized
+- **UI refresh** — icon-based branding + updated color system and action hierarchy
+
+### Fixed
+- **Startup/health handling** for orchestrated instances with clearer timeout errors and stale-start conflict handling
+- **Profile stop flow** now supports graceful stop semantics from the dashboard
+- **Status consistency** between process state and dashboard instance cards
+
+### Docs
+- Updated run mode documentation (headed/headless/dashboard)
+- Expanded architecture and skill docs for headed mode workflows and environment variables
+- Refreshed third-party license coverage
+
+## v0.4.0
### Added
- **Tab locking** — `POST /tab/lock`, `POST /tab/unlock` with timeout-based deadlock prevention for multi-agent coordination
diff --git a/README.md b/README.md
index da6fef7a..2552291f 100644
--- a/README.md
+++ b/README.md
@@ -68,21 +68,21 @@ Your agent can clone, build, and configure Pinchtab using the [OpenClaw skill](s
# Build
go build -o pinchtab .
-# Headed mode (default) — Chrome window visible, human can watch and interact
+# Headless mode (default) — no window, pure automation (best for token-efficient API flows)
./pinchtab
-# Headless mode — no window, pure automation
-BRIDGE_HEADLESS=true ./pinchtab
+# Headed mode — visible window for operator-in-the-loop flows
+BRIDGE_HEADLESS=false ./pinchtab
```
### Run Modes
| Mode | Command | Notes |
|---|---|---|
-| Headed (default) | `./pinchtab` | Launches managed Chrome with visible window |
-| Headless | `BRIDGE_HEADLESS=true ./pinchtab` | Launches managed Chrome without UI |
+| Headless (default) | `./pinchtab` | Launches managed Chrome without UI |
+| Headed | `BRIDGE_HEADLESS=false ./pinchtab` | Launches managed Chrome with visible window |
+| Dashboard / orchestrator | `./pinchtab dashboard` | Runs control plane only (profiles + instances), no browser in dashboard process |
| Remote CDP | `CDP_URL=http://localhost:9222 ./pinchtab` | Connects to an existing Chrome instead of launching one |
-| Dashboard only | `./pinchtab dashboard` | Runs the dashboard/orchestrator entrypoint |
Common runtime options:
@@ -97,44 +97,73 @@ BRIDGE_PROFILE=/path/to/profile ./pinchtab
BRIDGE_TOKEN=your-secret-token ./pinchtab
```
-### Headless Mode (recommended)
+### Headless Mode
<img src="assets/pinchtab-headless.png" width="64" alt="Pinchtab" />
-The primary mode. Chrome runs invisibly in the background — no window, pure API. This is what Pinchtab is built and tested for. Best for servers, CI, Docker, and unattended automation.
+Chrome runs invisibly in the background — no window, pure API. Best for servers, CI, Docker, and unattended automation. Token savings come from using `/text` and filtered snapshot formats (`/snapshot?filter=interactive&format=compact`) rather than vision/screenshot-heavy flows.
```bash
-BRIDGE_HEADLESS=true ./pinchtab
+./pinchtab
```
-All 100+ tests run against headless. The full API surface is validated here.
+All core API flows are validated in headless mode.
-### Headed Mode (experimental)
+### Headed Mode (operator-in-the-loop)
<img src="assets/pinchtab-headed.png" width="128" alt="Pinchtab headed mode" />
-Chrome opens as a visible window. Useful for debugging, watching agents work, and manually logging into sites. Shows the Pinchtab mascot on the welcome page.
+Headed mode is for mixed human + agent workflows:
+
+- Human signs in, solves captchas/2FA, validates page state
+- Agent continues through HTTP API against the same profile
+- Team can watch automation behavior in real time
+
+You can run headed mode in two ways:
+
+1. Single local instance:
+```bash
+BRIDGE_HEADLESS=false ./pinchtab
+```
+
+2. Dashboard-managed profiles (recommended for headed ops):
+```bash
+./pinchtab dashboard
+```
+Open `http://localhost:9867/dashboard` and:
+- create/import profiles
+- launch headed instances per profile/port
+- stop profiles gracefully
+- open Live popup for a specific running profile
+- inspect Info (status, tabs, feed summary, logs)
+
+When a profile is launched, your agent targets that profile instance URL (for example `http://localhost:9868`), not the dashboard URL.
+
+Helper command to resolve a running profile URL from dashboard state:
```bash
-./pinchtab # headed is the default
+pinchtab connect <profile-name>
+# -> http://localhost:<profile-port>
```
-> **⚠️ Headed mode is not fully tested.** It works for basic use but expect rough edges:
->
-> - **Profile management is manual** — Pinchtab uses its own Chrome profile (`~/.pinchtab/chrome-profile/`), separate from your regular Chrome. To access sites that need login, you must either log in manually in the Pinchtab window, or copy your existing Chrome profile:
-> ```bash
-> # Copy your Chrome profile (while Chrome is closed)
-> cp -r ~/Library/Application\ Support/Google/Chrome/Default ~/.pinchtab/chrome-profile
-> # Or point to a custom location
-> BRIDGE_PROFILE=/path/to/profile ./pinchtab
-> ```
-> - **Two Chrome instances can't share a profile** — if your regular Chrome is open, you must use a copied profile, not the original
-> - **Some sites detect automation differently in headed mode** — stealth behaviour may vary
-> - **Window management is not handled** — Chrome opens wherever the OS puts it
+Recommended human + agent flow:
+
+```bash
+# human operator
+pinchtab dashboard
+# create/import profile, then launch it from the dashboard
+
+# agent process
+PINCHTAB_BASE_URL="$(pinchtab connect <profile-name>)"
+curl "$PINCHTAB_BASE_URL/health"
+```
### First-Time Login
-Pinchtab uses a persistent profile at `~/.pinchtab/chrome-profile/`. In headed mode, log into sites via the Chrome window that opens — cookies persist across restarts. In headless mode, either copy an existing profile or use the cookie API (`POST /cookies`) to inject session cookies programmatically.
+Pinchtab keeps persistent profiles. Default single-instance profile: `~/.pinchtab/chrome-profile/`.
+Dashboard-managed profiles: `~/.pinchtab/profiles/<profile-name>/`.
+
+In headed mode, log into sites in the visible Chrome window once; cookies and local storage persist across restarts. In headless mode, either copy an existing profile or inject cookies via `POST /cookies`.
## Features
@@ -198,13 +227,13 @@ Pinchtab uses a persistent profile at `~/.pinchtab/chrome-profile/`. In headed m
## Configuration
-All via environment variables:
+### Core runtime
| Variable | Default | Description |
|----------|---------|-------------|
| `BRIDGE_PORT` | `9867` | HTTP server port |
| `BRIDGE_TOKEN` | *(none)* | Bearer token for auth |
-| `BRIDGE_HEADLESS` | `false` | Run Chrome headless (no window) |
+| `BRIDGE_HEADLESS` | `true` | Run Chrome headless (no window) |
| `BRIDGE_PROFILE` | `~/.pinchtab/chrome-profile` | Chrome profile directory |
| `BRIDGE_STATE_DIR` | `~/.pinchtab` | State/session storage |
| `BRIDGE_NO_RESTORE` | `false` | Skip restoring tabs from previous session |
@@ -212,12 +241,25 @@ All via environment variables:
| `BRIDGE_BLOCK_IMAGES` | `false` | Block image loading |
| `BRIDGE_BLOCK_MEDIA` | `false` | Block all media (images + fonts + CSS + video) |
| `BRIDGE_NO_ANIMATIONS` | `false` | Disable CSS animations/transitions globally |
+| `BRIDGE_TIMEZONE` | *(none)* | Force browser timezone (IANA tz, e.g. `Europe/Rome`) |
+| `BRIDGE_CHROME_VERSION` | `144.0.7559.133` | Chrome version string used by fingerprint rotation profiles |
| `BRIDGE_TIMEOUT` | `15` | Action timeout (seconds) |
| `BRIDGE_NAV_TIMEOUT` | `30` | Navigation timeout (seconds) |
| `BRIDGE_CONFIG` | `~/.pinchtab/config.json` | Path to config JSON file |
| `CHROME_BINARY` | *(auto)* | Path to Chrome/Chromium binary |
| `CHROME_FLAGS` | *(none)* | Extra Chrome flags (space-separated) |
| `CDP_URL` | *(none)* | Connect to existing Chrome instead of launching |
+| `BRIDGE_NO_DASHBOARD` | `false` | Disable embedded dashboard/orchestrator endpoints on instance processes |
+
+### Dashboard mode (`./pinchtab dashboard`)
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `PINCHTAB_AUTO_LAUNCH` | `false` | Auto-launch a default profile instance at dashboard startup |
+| `PINCHTAB_DEFAULT_PROFILE` | `default` | Profile name used by auto-launch |
+| `PINCHTAB_DEFAULT_PORT` | `9867` | Port used by auto-launch |
+| `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` |
## Architecture
diff --git a/THIRD_PARTY_LICENSES.md b/THIRD_PARTY_LICENSES.md
index b1eac910..1f45984b 100644
--- a/THIRD_PARTY_LICENSES.md
+++ b/THIRD_PARTY_LICENSES.md
@@ -54,6 +54,24 @@ Pinchtab depends on the following open-source packages. All are compatible with
- **URL:** https://github.com/golang/sys
- **Purpose:** Go system call wrappers
+### github.com/ledongthuc/pdf
+- **License:** BSD 3-Clause
+- **Copyright:** (c) 2009 The Go Authors
+- **URL:** https://github.com/ledongthuc/pdf
+- **Purpose:** Transitive dependency in module graph (test tooling chain)
+
+### github.com/orisano/pixelmatch
+- **License:** MIT
+- **Copyright:** (c) 2022 orisano
+- **URL:** https://github.com/orisano/pixelmatch
+- **Purpose:** Transitive dependency in module graph (test tooling chain)
+
+### gopkg.in/check.v1
+- **License:** BSD-style
+- **Copyright:** (c) 2010-2013 Gustavo Niemeyer
+- **URL:** https://gopkg.in/check.v1
+- **Purpose:** Transitive dependency in module graph (test tooling chain)
+
### gopkg.in/yaml.v3
- **License:** Apache 2.0 / MIT
- **Copyright:** (c) 2006-2011 Kirill Simonov, (c) 2011-2019 Canonical Ltd
@@ -72,6 +90,9 @@ Pinchtab depends on the following open-source packages. All are compatible with
| gobwas/httphead | MIT | ✅ |
| gobwas/pool | MIT | ✅ |
| golang.org/x/sys | BSD 3-Clause | ✅ |
-| gopkg.in/yaml.v3 | Apache 2.0/MIT | ✅ |
+| github.com/ledongthuc/pdf | BSD 3-Clause | ✅ |
+| github.com/orisano/pixelmatch | MIT | ✅ |
+| gopkg.in/check.v1 | BSD-style | ✅ |
+| gopkg.in/yaml.v3 | Apache 2.0 / MIT | ✅ |
-All dependencies are MIT, BSD 3-Clause, or Apache 2.0 licensed, fully compatible with Pinchtab's MIT license.
+All dependencies are MIT, BSD-style, or Apache 2.0 licensed, compatible with Pinchtab's MIT license.
diff --git a/cmd_connect.go b/cmd_connect.go
new file mode 100644
index 00000000..87e49d6f
--- /dev/null
+++ b/cmd_connect.go
@@ -0,0 +1,104 @@
+package main
+
+import (
+ "encoding/json"
+ "fmt"
+ "io"
+ "net/http"
+ "net/url"
+ "os"
+)
+
+type profileInstanceStatus struct {
+ Name string `json:"name"`
+ Running bool `json:"running"`
+ Status string `json:"status"`
+ Port string `json:"port"`
+ ID string `json:"id"`
+ Error string `json:"error"`
+}
+
+func handleConnectCommand() {
+ profile := ""
+ dashboardURL := os.Getenv("PINCHTAB_DASHBOARD_URL")
+ jsonOut := false
+
+ args := os.Args[2:]
+ for i := 0; i < len(args); i++ {
+ arg := args[i]
+ switch arg {
+ case "--json":
+ jsonOut = true
+ case "--dashboard":
+ if i+1 >= len(args) {
+ fmt.Fprintln(os.Stderr, "missing value for --dashboard")
+ os.Exit(2)
+ }
+ i++
+ dashboardURL = args[i]
+ default:
+ if profile == "" {
+ profile = arg
+ }
+ }
+ }
+
+ if profile == "" {
+ fmt.Fprintln(os.Stderr, "Usage: pinchtab connect <profile> [--dashboard http://localhost:9867] [--json]")
+ os.Exit(2)
+ }
+ if dashboardURL == "" {
+ dashboardURL = "http://localhost:" + port
+ }
+
+ reqURL := stringsTrimRightSlash(dashboardURL) + "/profiles/" + url.PathEscape(profile) + "/instance"
+ res, err := http.Get(reqURL)
+ if err != nil {
+ fmt.Fprintf(os.Stderr, "connect failed: %v\n", err)
+ os.Exit(1)
+ }
+ defer res.Body.Close()
+
+ if res.StatusCode != http.StatusOK {
+ body, _ := io.ReadAll(io.LimitReader(res.Body, 8<<10))
+ fmt.Fprintf(os.Stderr, "connect failed: dashboard returned %d: %s\n", res.StatusCode, string(body))
+ os.Exit(1)
+ }
+
+ var st profileInstanceStatus
+ if err := json.NewDecoder(res.Body).Decode(&st); err != nil {
+ fmt.Fprintf(os.Stderr, "connect failed: invalid response: %v\n", err)
+ os.Exit(1)
+ }
+ if !st.Running || st.Port == "" {
+ errMsg := st.Error
+ if errMsg == "" {
+ errMsg = st.Status
+ }
+ fmt.Fprintf(os.Stderr, "profile %q not running (%s)\n", profile, errMsg)
+ os.Exit(1)
+ }
+
+ instanceURL := "http://localhost:" + st.Port
+ if jsonOut {
+ enc := json.NewEncoder(os.Stdout)
+ enc.SetIndent("", " ")
+ _ = enc.Encode(map[string]string{
+ "profile": st.Name,
+ "id": st.ID,
+ "status": st.Status,
+ "port": st.Port,
+ "url": instanceURL,
+ })
+ return
+ }
+
+ fmt.Println(instanceURL)
+}
+
+func stringsTrimRightSlash(s string) string {
+ for len(s) > 0 && s[len(s)-1] == '/' {
+ s = s[:len(s)-1]
+ }
+ return s
+}
diff --git a/config.go b/config.go
index cb947531..b3e345d0 100644
--- a/config.go
+++ b/config.go
@@ -7,6 +7,7 @@ import (
"log/slog"
"os"
"path/filepath"
+ "strings"
"time"
)
@@ -48,7 +49,7 @@ var (
cdpURL = os.Getenv("CDP_URL")
token = os.Getenv("BRIDGE_TOKEN")
stateDir = envOr("BRIDGE_STATE_DIR", filepath.Join(homeDir(), ".pinchtab"))
- headless = os.Getenv("BRIDGE_HEADLESS") == "true"
+ headless = envBoolOr("BRIDGE_HEADLESS", true)
noRestore = os.Getenv("BRIDGE_NO_RESTORE") == "true"
profileDir = envOr("BRIDGE_PROFILE", filepath.Join(homeDir(), ".pinchtab", "chrome-profile"))
chromeVersion = envOr("BRIDGE_CHROME_VERSION", "144.0.7559.133")
@@ -72,6 +73,21 @@ func envOr(key, fallback string) string {
return fallback
}
+func envBoolOr(key string, fallback bool) bool {
+ v, ok := os.LookupEnv(key)
+ if !ok {
+ return fallback
+ }
+ switch strings.ToLower(strings.TrimSpace(v)) {
+ case "1", "true", "yes", "on":
+ return true
+ case "0", "false", "no", "off":
+ return false
+ default:
+ return fallback
+ }
+}
+
func homeDir() string {
h, _ := os.UserHomeDir()
return h
diff --git a/config_test.go b/config_test.go
index 39c71ca4..e257a0b0 100644
--- a/config_test.go
+++ b/config_test.go
@@ -17,6 +17,35 @@ func TestEnvOr(t *testing.T) {
}
}
+func TestEnvBoolOr(t *testing.T) {
+ if got := envBoolOr("PINCHTAB_TEST_BOOL_UNSET", true); !got {
+ t.Error("expected fallback true for unset env")
+ }
+ if got := envBoolOr("PINCHTAB_TEST_BOOL_UNSET", false); got {
+ t.Error("expected fallback false for unset env")
+ }
+
+ t.Setenv("PINCHTAB_TEST_BOOL", "true")
+ if got := envBoolOr("PINCHTAB_TEST_BOOL", false); !got {
+ t.Error("expected true from env true")
+ }
+
+ t.Setenv("PINCHTAB_TEST_BOOL", "false")
+ if got := envBoolOr("PINCHTAB_TEST_BOOL", true); got {
+ t.Error("expected false from env false")
+ }
+
+ t.Setenv("PINCHTAB_TEST_BOOL", "1")
+ if got := envBoolOr("PINCHTAB_TEST_BOOL", false); !got {
+ t.Error("expected true from env 1")
+ }
+
+ t.Setenv("PINCHTAB_TEST_BOOL", "0")
+ if got := envBoolOr("PINCHTAB_TEST_BOOL", true); got {
+ t.Error("expected false from env 0")
+ }
+}
+
func TestHomeDir(t *testing.T) {
h := homeDir()
if h == "" {
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index bf3879cb..47bd779a 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -7,10 +7,10 @@ to give AI agents browser control via a simple REST API. It self-launches Chrome
manages tabs, and exposes the accessibility tree as flat JSON with stable refs.
```
-┌─────────────┐ HTTP ┌──────────────┐ CDP ┌─────────────┐
-│ AI Agent │ ────────────▶ │ Pinchtab │ ─────────────▶ │ Chrome │
-│ (any LLM) │ ◀──────────── │ (Go binary) │ ◀───────────── │ (headless) │
-└─────────────┘ JSON/text └──────────────┘ WebSocket └─────────────┘
+┌─────────────┐ HTTP ┌──────────────┐ CDP ┌──────────────┐
+│ AI Agent │ ────────────▶ │ Pinchtab │ ─────────────▶ │ Chrome │
+│ (any LLM) │ ◀──────────── │ (Go binary) │ ◀───────────── │ headed/headless │
+└─────────────┘ JSON/text └──────────────┘ WebSocket └──────────────┘
```
Agents never touch CDP directly. They send HTTP requests, get back JSON.
@@ -284,6 +284,34 @@ Agent Pinchtab Chrome
│◀──────────────────────────────│ │
```
+### Typical Agent Interaction in Headed mode
+
+In headed mode, the human sets up and validates profiles first, then the agent runs against those profiles.
+
+```
+Human Operator Dashboard (`pinchtab dashboard`) Profile Instance Agent
+ │ │ │ │
+ │ create/import profile │ │ │
+ │───────────────────────────▶│ │ │
+ │ launch profile on :9868 │ │ │
+ │───────────────────────────▶│ spawn `pinchtab` │ │
+ │ │─────────────────────────────▶│ headed Chrome │
+ │ manual login / 2FA │ │ │
+ │<──────────────────────────────────── visible browser ────────────────────────-│
+ │ validate state │ │ │
+ │ │ profile URL ready │ │
+ │ │─────────────┬───────────────-│ │
+ │ │ │ │
+ │ │ │ POST /navigate │
+ │ │ │◀──────────────────────────────────-│
+ │ │ │ GET /snapshot │
+ │ │ │◀──────────────────────────────────-│
+ │ │ │ POST /action │
+ │ │ │◀──────────────────────────────────-│
+```
+
+Key point: the dashboard coordinates profiles and lifecycle, but agents call the running profile instance (`http://localhost:<profile-port>`), not the dashboard proxy endpoint.
+
### Token Efficiency
| Method | ~Tokens | Use Case |
diff --git a/main.go b/main.go
index 2e2f3034..a9ffa690 100644
--- a/main.go
+++ b/main.go
@@ -42,6 +42,11 @@ func main() {
os.Exit(0)
}
+ if len(os.Args) > 1 && os.Args[1] == "connect" {
+ handleConnectCommand()
+ os.Exit(0)
+ }
+
if len(os.Args) > 1 && os.Args[1] == "dashboard" {
runDashboard()
return
diff --git a/skill/pinchtab/SKILL.md b/skill/pinchtab/SKILL.md
index dddd28a5..69512670 100644
--- a/skill/pinchtab/SKILL.md
+++ b/skill/pinchtab/SKILL.md
@@ -45,6 +45,12 @@ metadata:
- name: BRIDGE_NO_ANIMATIONS
optional: true
description: "Disable CSS animations/transitions globally (true/false)"
+ - name: BRIDGE_TIMEZONE
+ optional: true
+ description: "Force browser timezone (IANA tz, e.g. Europe/Rome)"
+ - name: BRIDGE_CHROME_VERSION
+ optional: true
+ description: "Chrome version string used by fingerprint rotation profiles"
- name: CHROME_BINARY
optional: true
description: "Path to Chrome/Chromium binary (auto-detected if not set)"
@@ -63,6 +69,24 @@ metadata:
- name: CDP_URL
optional: true
description: "Connect to existing Chrome DevTools instead of launching"
+ - name: BRIDGE_NO_DASHBOARD
+ optional: true
+ description: "Disable dashboard/orchestrator endpoints on instance processes"
+ - name: PINCHTAB_AUTO_LAUNCH
+ optional: true
+ description: "Dashboard mode: auto-launch default profile instance on startup"
+ - name: PINCHTAB_DEFAULT_PROFILE
+ optional: true
+ description: "Dashboard mode: default profile name for auto-launch"
+ - name: PINCHTAB_DEFAULT_PORT
+ optional: true
+ description: "Dashboard mode: default port for auto-launched profile"
+ - name: PINCHTAB_HEADED
+ optional: true
+ description: "Dashboard mode: when set, auto-launched profile runs headed"
+ - name: PINCHTAB_DASHBOARD_URL
+ optional: true
+ description: "Base dashboard URL used by `pinchtab connect` helper"
---
# Pinchtab
@@ -71,14 +95,17 @@ Fast, lightweight browser control for AI agents via HTTP + accessibility tree.
## Setup
-Ensure Pinchtab is running:
+Start Pinchtab in one of these modes:
```bash
-# Headless (default for automation)
-BRIDGE_HEADLESS=true pinchtab &
-
-# With UI (debugging)
+# Headless (default) — no UI, pure automation (lowest token cost when using /text and filtered snapshots)
pinchtab &
+
+# Headed — visible Chrome for human + agent workflows
+BRIDGE_HEADLESS=false pinchtab &
+
+# Dashboard/orchestrator — profile manager + launcher, no browser in dashboard process
+pinchtab dashboard &
```
Default port: `9867`. Override with `BRIDGE_PORT=9868`.
@@ -86,6 +113,36 @@ Auth: set `BRIDGE_TOKEN=<secret>` and pass `Authorization: Bearer <secret>`.
Base URL for all examples: `http://localhost:9867`
+Token savings come from the API shape (`/text`, `/snapshot?filter=interactive&format=compact`), not from headless vs headed alone.
+
+### Headed mode definition
+
+Headed mode means a real visible Chrome window managed by Pinchtab.
+
+- Human can open profile(s), log in, pass 2FA/captcha, and validate page state
+- Agent then calls Pinchtab HTTP APIs against that same running profile instance
+- Session state persists in the profile directory, so follow-up runs reuse cookies/storage
+
+In dashboard workflows, the dashboard process itself does not launch Chrome; it launches profile instances that run Chrome (headed or headless).
+
+To resolve a running profile endpoint from dashboard state:
+
+```bash
+pinchtab connect <profile-name>
+```
+
+Recommended human + agent flow:
+
+```bash
+# human
+pinchtab dashboard
+# setup profile + launch profile instance
+
+# agent
+PINCHTAB_BASE_URL="$(pinchtab connect <profile-name>)"
+curl "$PINCHTAB_BASE_URL/health"
+```
+
## Core Workflow
The typical agent loop:
@@ -334,10 +391,12 @@ curl http://localhost:9867/health
## Environment Variables
+### Core runtime
+
| Var | Default | Description |
|---|---|---|
| `BRIDGE_PORT` | `9867` | HTTP port |
-| `BRIDGE_HEADLESS` | `false` | Run Chrome headless |
+| `BRIDGE_HEADLESS` | `true` | Run Chrome headless |
| `BRIDGE_TOKEN` | (none) | Bearer auth token |
| `BRIDGE_PROFILE` | `~/.pinchtab/chrome-profile` | Chrome profile dir |
| `BRIDGE_STATE_DIR` | `~/.pinchtab` | State/session storage |
@@ -346,12 +405,25 @@ curl http://localhost:9867/health
| `BRIDGE_BLOCK_IMAGES` | `false` | Block image loading |
| `BRIDGE_BLOCK_MEDIA` | `false` | Block all media (images + fonts + CSS + video) |
| `BRIDGE_NO_ANIMATIONS` | `false` | Disable CSS animations/transitions |
+| `BRIDGE_TIMEZONE` | (none) | Force browser timezone (IANA tz) |
+| `BRIDGE_CHROME_VERSION` | `144.0.7559.133` | Chrome version string used by fingerprint rotation |
| `CHROME_BINARY` | (auto) | Path to Chrome/Chromium binary |
| `CHROME_FLAGS` | (none) | Extra Chrome flags (space-separated) |
| `BRIDGE_CONFIG` | `~/.pinchtab/config.json` | Path to config JSON file |
| `BRIDGE_TIMEOUT` | `15` | Action timeout (seconds) |
| `BRIDGE_NAV_TIMEOUT` | `30` | Navigation timeout (seconds) |
| `CDP_URL` | (none) | Connect to existing Chrome DevTools |
+| `BRIDGE_NO_DASHBOARD` | `false` | Disable dashboard/orchestrator endpoints on instance processes |
+
+### Dashboard mode (`pinchtab dashboard`)
+
+| Var | Default | Description |
+|---|---|---|
+| `PINCHTAB_AUTO_LAUNCH` | `false` | Auto-launch a default profile at dashboard startup |
+| `PINCHTAB_DEFAULT_PROFILE` | `default` | Profile name for auto-launch |
+| `PINCHTAB_DEFAULT_PORT` | `9867` | Port for auto-launched profile |
+| `PINCHTAB_HEADED` | (unset) | If set, auto-launched profile is headed; unset means headless |
+| `PINCHTAB_DASHBOARD_URL` | `http://localhost:$BRIDGE_PORT` | CLI helper base URL for `pinchtab connect` |
## Tips