High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.
fix: documentation and small changes
Luigi Agosti3ef76b51d24b
diff --git a/README.md b/README.mdindex 920703a7..a99149f7 100644--- a/README.md+++ b/README.md@@ -72,7 +72,7 @@ See the full guide: [docs/guides/security.md](docs/guides/security.md)With the daemon installed and an agent skill configured, an agent can execute tasks like:```-"What are the main news about trump on news.com?"+"What are the main news about aliens on news.com?"```PinchTab exposes browser tools that allow agents to navigate pages, extract structured content, and interact with the DOM without wasting tokens on raw HTML or images.@@ -160,6 +160,21 @@ curl -fsSL https://pinchtab.com/install.sh | bashnpm install -g pinchtab```+### Shell Completion++Generate and install shell completions after `pinchtab` is on your `PATH`:++```bash+# Generate and install zsh completions+pinchtab completion zsh > "${fpath[1]}/_pinchtab"++# Generate bash completions+pinchtab completion bash > /etc/bash_completion.d/pinchtab++# Generate fish completions+pinchtab completion fish > ~/.config/fish/completions/pinchtab.fish+```+**Docker:**```bashdocker run -d \@@ -315,6 +330,8 @@ curl -s -X POST http://localhost:9867/instances/start \curl http://localhost:9867/instances```+See [chrome-files.md](chrome-files.md) for technical details on how PinchTab manages Chrome user data directories and ensures isolation between parallel instances.+---## Developmentdiff --git a/docs/get-started.md b/docs/get-started.mdindex ec609fe3..12379f76 100644--- a/docs/get-started.md+++ b/docs/get-started.md@@ -52,6 +52,21 @@ go build -o pinchtab ./cmd/pinchtab**[Full build guide ->](architecture/building.md)**+## Shell Completion++After installation, you can generate shell completions from the CLI:++```bash+# Generate and install zsh completions+pinchtab completion zsh > "${fpath[1]}/_pinchtab"++# Generate bash completions+pinchtab completion bash > /etc/bash_completion.d/pinchtab++# Generate fish completions+pinchtab completion fish > ~/.config/fish/completions/pinchtab.fish+```+---## Quick startdiff --git a/docs/implementations/chrome-files.md b/docs/implementations/chrome-files.mdnew file mode 100644index 00000000..4df09ba0--- /dev/null+++ b/docs/implementations/chrome-files.md@@ -0,0 +1,52 @@+# Chrome User Data Directories & Profiles++PinchTab manages Chrome instances using dedicated **User Data Directories** (profiles). This document explains how these directories are resolved, how locks are managed, and how to handle parallel browser instances.++## Profile Resolution++PinchTab determines the Chrome `--user-data-dir` (profile) using the following precedence:++1. **Explicit `ProfileDir`**: If a specific path is provided in the configuration or as a flag, PinchTab uses that exact directory.+2. **Named Profile**: If a profile name is provided (e.g., via the dashboard or CLI), PinchTab resolves it to a subdirectory within the `ProfilesBaseDir`.+3. **Default Profile**: If no profile is specified, it defaults to `~/.config/pinchtab/profiles/default` (on Linux/macOS).++## The Singleton Model++Chrome enforces a **Singleton** model per User Data Directory. This means:+* Only **one** Chrome process can use a specific profile directory at any given time.+* If a second process attempts to use the same directory, Chrome will either fail to start or (in some configurations) attempt to open a new window in the existing process.++PinchTab adds an additional layer of protection using a `pinchtab.pid` file within the profile directory to ensure that only one PinchTab instance manages a specific profile.++## New Headless & Parallel Instances++With the introduction of **New Headless mode** (`--headless=new`), Chrome's profile sharing behavior has become stricter:+* **No Sharing**: You cannot reuse the same `--user-data-dir` across multiple concurrent instances.+* **Separate Directories Required**: Parallel browsers **must** use separate directories to avoid random startup errors and lock conflicts.++### Headless Auto-Fallback+To support parallel automation tasks, PinchTab implements an **automatic fallback for headless instances**:+1. If a headless instance tries to start using a profile that is already locked by another PinchTab process, it will **automatically create a unique temporary directory** (e.g., `/tmp/pinchtab-profile-*`).+2. This allows you to run multiple headless tasks in parallel without manually managing profile paths.++### Manual Parallelism (Headed Mode)+In **headed mode**, PinchTab does *not* automatically fall back to a temporary directory (to avoid losing user session data unexpectedly). If you need to run multiple headed browsers in parallel, you must:+* Use different named profiles.+* Explicitly provide a unique `--user-data-dir` for each instance.++## Best Practices for AI Agents++When building agents that use PinchTab, follow these guidelines:++* **Persistence**: Use named profiles (e.g., `agent-alpha`, `agent-beta`) if you need the browser to remember logins, cookies, or history across sessions.+* **Isolation**: For one-off tasks or high-concurrency scraping, rely on the default headless mode which handles directory isolation automatically if conflicts occur.+* **Cleanup**: If you manually create temporary directories, ensure they are cleaned up after the task is complete to avoid filling up disk space.++## Troubleshooting++If you see the error `"The profile appears to be in use by another Chromium process"`:+1. **Check for active instances**: Ensure you don't have another PinchTab or Chrome process already using that profile.+2. **Stale Locks**: If no process is active, PinchTab will attempt to automatically clear stale `SingletonLock` files on the next startup.+3. **Manual Fix**: In rare cases, you may need to manually remove the `SingletonLock` file from the profile directory.++For more details on how PinchTab recovers from crashes, see [Chrome Profile Lock Recovery](docs/implementations/chrome-profile-lock-recovery.md).diff --git a/docs/reference/cli.md b/docs/reference/cli.mdindex c9a5c29f..f0853e70 100644--- a/docs/reference/cli.md+++ b/docs/reference/cli.md@@ -76,9 +76,25 @@ These are the main local-control commands surfaced in the menu:| `pinchtab daemon` | Show daemon status and manage the background service || `pinchtab config` | Open the interactive config overview/editor || `pinchtab security` | Review or change the current security posture |+| `pinchtab completion <shell>` | Generate shell completion scripts for `bash`, `zsh`, `fish`, or `powershell` || `pinchtab bridge` | Start the single-instance bridge runtime || `pinchtab mcp` | Start the stdio MCP server |+## Shell Completion++Use the built-in completion command to generate shell-specific scripts:++```bash+# Generate and install zsh completions+pinchtab completion zsh > "${fpath[1]}/_pinchtab"++# Generate bash completions+pinchtab completion bash > /etc/bash_completion.d/pinchtab++# Generate fish completions+pinchtab completion fish > ~/.config/fish/completions/pinchtab.fish+```+## Browser ShortcutsThe most common browser control shortcuts are top-level commands:diff --git a/internal/cli/report/security.go b/internal/cli/report/security.goindex 66d6aad6..37f75c86 100644--- a/internal/cli/report/security.go+++ b/internal/cli/report/security.go@@ -52,12 +52,6 @@ func AssessSecurityPosture(cfg *config.RuntimeConfig) SecurityPosture {Passed: len(cfg.EnabledSensitiveEndpoints()) == 0,Detail: formatEndpointStatus(cfg.EnabledSensitiveEndpoints()),},- {- ID: "attach_disabled",- Label: "attach endpoint",- Passed: !cfg.AttachEnabled,- Detail: map[bool]string{true: "disabled", false: "enabled"}[!cfg.AttachEnabled],- },{ID: "attach_local_only",Label: "attach host scope",@@ -196,19 +190,12 @@ func AssessSecurityWarnings(cfg *config.RuntimeConfig) []SecurityWarning {}}- if cfg.AttachEnabled {+ if attachAllowsNonLocalHosts(cfg.AttachAllowHosts) {warnings = append(warnings, SecurityWarning{- ID: "attach_enabled",- Message: "attach endpoint enabled",- Attrs: []any{"hint", "only attach to Chrome instances you trust"},+ ID: "attach_external_hosts",+ Message: "attach allowHosts includes non-local hosts",+ Attrs: []any{"allowHosts", cfg.AttachAllowHosts, "hint", "keep security.attach.allowHosts limited to local addresses unless external Chrome instances are intentional"},})- if attachAllowsNonLocalHosts(cfg.AttachAllowHosts) {- warnings = append(warnings, SecurityWarning{- ID: "attach_external_hosts",- Message: "attach allowHosts includes non-local hosts",- Attrs: []any{"allowHosts", cfg.AttachAllowHosts, "hint", "keep security.attach.allowHosts limited to local addresses unless external Chrome instances are intentional"},- })- }}return warnings@@ -264,9 +251,9 @@ func securityPostureLevel(passed, total int) string {switch {case passed == total:return "LOCKED"- case passed >= total-2:+ case passed >= total-1:return "GUARDED"- case passed >= total/2:+ case passed >= 3:return "ELEVATED"default:return "EXPOSED"diff --git a/internal/cli/report/security_test.go b/internal/cli/report/security_test.goindex 8132617c..e22f5e31 100644--- a/internal/cli/report/security_test.go+++ b/internal/cli/report/security_test.go@@ -57,7 +57,6 @@ func TestAssessSecurityWarnings(t *testing.T) {"idpi_whitelist_not_set","idpi_warn_mode","idpi_content_protection_disabled",- "attach_enabled","attach_external_hosts",} {if !ids[expected] {@@ -147,8 +146,8 @@ func TestAssessSecurityPosture(t *testing.T) {}posture := assessSecurityPosture(cfg)- if posture.Passed >= posture.Total/2 {- t.Fatalf("expected exposed posture below half-score, got %d/%d", posture.Passed, posture.Total)+ if posture.Passed >= 3 {+ t.Fatalf("expected exposed posture below 3 passed checks, got %d/%d", posture.Passed, posture.Total)}if posture.Level != "EXPOSED" {t.Fatalf("expected EXPOSED posture, got %q", posture.Level)diff --git a/internal/cli/report/startup.go b/internal/cli/report/startup.goindex b704e824..f9857f2a 100644--- a/internal/cli/report/startup.go+++ b/internal/cli/report/startup.go@@ -162,7 +162,7 @@ func SecurityLevelColor(level string) string {case "GUARDED":return string(colorWarning)case "ELEVATED":- return string(colorDanger)+ return string(colorWarning)default:return string(colorDanger)}diff --git a/internal/cli/report/startup_test.go b/internal/cli/report/startup_test.goindex 1e30561b..a941c749 100644--- a/internal/cli/report/startup_test.go+++ b/internal/cli/report/startup_test.go@@ -11,7 +11,7 @@ func TestSecurityLevelColor(t *testing.T) {}{{level: "LOCKED", want: string(colorSuccess)},{level: "GUARDED", want: string(colorWarning)},- {level: "ELEVATED", want: string(colorDanger)},+ {level: "ELEVATED", want: string(colorWarning)},{level: "EXPOSED", want: string(colorDanger)},{level: "UNKNOWN", want: string(colorDanger)},}diff --git a/internal/config/config_file.go b/internal/config/config_file.goindex f54b957b..5d0b56ac 100644--- a/internal/config/config_file.go+++ b/internal/config/config_file.go@@ -25,6 +25,7 @@ func DefaultFileConfig() FileConfig {allowDownload := falseallowUpload := falsemaxRedirects := -1+ attachEnabled := truereturn FileConfig{ConfigVersion: CurrentConfigVersion,Server: ServerConfig{@@ -49,6 +50,7 @@ func DefaultFileConfig() FileConfig {AllowUpload: &allowUpload,MaxRedirects: &maxRedirects,Attach: AttachConfig{+ Enabled: &attachEnabled,AllowHosts: []string{"127.0.0.1", "localhost", "::1"},AllowSchemes: []string{"ws", "wss"},},diff --git a/internal/config/config_load.go b/internal/config/config_load.goindex bf0d8412..7ea7ac3d 100644--- a/internal/config/config_load.go+++ b/internal/config/config_load.go@@ -64,7 +64,7 @@ func Load() *RuntimeConfig {RestartStableAfter: 5 * time.Minute,// Attach defaults- AttachEnabled: false,+ AttachEnabled: true,AttachAllowHosts: []string{"127.0.0.1", "localhost", "::1"},AttachAllowSchemes: []string{"ws", "wss"},diff --git a/internal/config/config_load_test.go b/internal/config/config_load_test.goindex f8c71611..fabbb035 100644--- a/internal/config/config_load_test.go+++ b/internal/config/config_load_test.go@@ -68,8 +68,8 @@ func TestLoadConfigDefaults(t *testing.T) {if cfg.TabEvictionPolicy != "close_lru" {t.Errorf("default TabEvictionPolicy = %v, want close_lru", cfg.TabEvictionPolicy)}- if cfg.AttachEnabled {- t.Errorf("default AttachEnabled = %v, want false", cfg.AttachEnabled)+ if !cfg.AttachEnabled {+ t.Errorf("default AttachEnabled = %v, want true", cfg.AttachEnabled)}if len(cfg.AttachAllowSchemes) != 2 || cfg.AttachAllowSchemes[0] != "ws" || cfg.AttachAllowSchemes[1] != "wss" {t.Errorf("default AttachAllowSchemes = %v, want [ws wss]", cfg.AttachAllowSchemes)diff --git a/npm/README.md b/npm/README.mdindex 9b8bbd4e..485a5daf 100644--- a/npm/README.md+++ b/npm/README.md@@ -127,6 +127,21 @@ pinchtab --versionpinchtab --help```+### Shell Completion++After installing the CLI globally, you can generate shell completions:++```bash+# Generate and install zsh completions+pinchtab completion zsh > "${fpath[1]}/_pinchtab"++# Generate bash completions+pinchtab completion bash > /etc/bash_completion.d/pinchtab++# Generate fish completions+pinchtab completion fish > ~/.config/fish/completions/pinchtab.fish+```+### Using a Custom BinaryFor Docker, development, or other custom setups: