Skip to content

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

bridge: --cdp-attach flag to drive an externally-managed Chrome

Edouard Gouilliard07fa3352a5ed
diff --git a/cmd/pinchtab/cmd_bridge.go b/cmd/pinchtab/cmd_bridge.go
index 1899a6d2..6561be03 100644
--- a/cmd/pinchtab/cmd_bridge.go
+++ b/cmd/pinchtab/cmd_bridge.go
@@ -8,7 +8,12 @@ import (
"github.com/spf13/cobra"
)
-var bridgeEngine string
+var (
+ bridgeEngine string
+ bridgeCDPAttach string
+ bridgeBind string
+ bridgePort string
+)
var bridgeCmd = &cobra.Command{
Use: "bridge",
@@ -20,6 +25,15 @@ var bridgeCmd = &cobra.Command{
return err
}
cfg.Engine = engineMode
+ if v := strings.TrimSpace(bridgeCDPAttach); v != "" {
+ cfg.CDPAttachURL = v
+ }
+ if v := strings.TrimSpace(bridgeBind); v != "" {
+ cfg.Bind = v
+ }
+ if v := strings.TrimSpace(bridgePort); v != "" {
+ cfg.Port = v
+ }
server.RunBridgeServer(cfg, version)
return nil
},
@@ -42,5 +56,8 @@ func resolveBridgeEngine(flagValue, configValue string) (string, error) {
func init() {
bridgeCmd.GroupID = "primary"
bridgeCmd.Flags().StringVar(&bridgeEngine, "engine", "", "Bridge engine: chrome, lite, or auto (overrides config)")
+ bridgeCmd.Flags().StringVar(&bridgeCDPAttach, "cdp-attach", "", "Attach to an existing Chrome via its browser-level CDP URL (e.g. ws://127.0.0.1:9222/devtools/browser/abc). Skips launching Chrome; the external Chrome is left alive on shutdown.")
+ bridgeCmd.Flags().StringVar(&bridgeBind, "bind", "", "Bind address for the bridge HTTP server (overrides config server.bind)")
+ bridgeCmd.Flags().StringVar(&bridgePort, "port", "", "Port for the bridge HTTP server (overrides config server.port)")
rootCmd.AddCommand(bridgeCmd)
}
diff --git a/internal/bridge/runtime/init.go b/internal/bridge/runtime/init.go
index 2ca68567..d2f0a6e3 100644
--- a/internal/bridge/runtime/init.go
+++ b/internal/bridge/runtime/init.go
@@ -38,7 +38,16 @@ type Hooks struct {
}
// InitChrome initializes a Chrome browser for a Bridge instance.
+//
+// When cfg.CDPAttachURL is set, this skips launching a Chrome process and
+// connects to the externally-managed Chrome at that browser-level CDP
+// WebSocket URL. The returned cancel funcs only release the chromedp
+// allocator + browser context; the external Chrome process is left alive.
func InitChrome(cfg *config.RuntimeConfig, bundle *stealth.Bundle, hooks Hooks) (context.Context, context.CancelFunc, context.Context, context.CancelFunc, stealth.LaunchMode, error) {
+ if cfg != nil && strings.TrimSpace(cfg.CDPAttachURL) != "" {
+ return initChromeFromExistingCDP(cfg, bundle)
+ }
+
slog.Info("starting chrome initialization", "headless", cfg.Headless, "profile", cfg.ProfileDir, "binary", cfg.ChromeBinary)
bundle = ensureStealthBundle(cfg, bundle)
@@ -54,6 +63,37 @@ func InitChrome(cfg *config.RuntimeConfig, bundle *stealth.Bundle, hooks Hooks)
return allocCtx, allocCancel, browserCtx, browserCancel, launchMode, nil
}
+// initChromeFromExistingCDP attaches the bridge to a Chrome that is already
+// running outside pinchtab (e.g. the user's everyday browser launched with
+// --remote-debugging-port=NNNN). No process is spawned and no profile lock
+// is taken. The allocator is a chromedp remote allocator; the returned
+// cancel funcs release only the chromedp side, never the external Chrome.
+func initChromeFromExistingCDP(cfg *config.RuntimeConfig, bundle *stealth.Bundle) (context.Context, context.CancelFunc, context.Context, context.CancelFunc, stealth.LaunchMode, error) {
+ wsURL := strings.TrimSpace(cfg.CDPAttachURL)
+ slog.Info("attaching to existing Chrome via CDP", "cdpUrl", wsURL)
+
+ bundle = ensureStealthBundle(cfg, bundle)
+
+ remoteAllocCtx, remoteAllocCancel := chromedp.NewRemoteAllocator(context.Background(), wsURL)
+ browserCtx, browserCancel := chromedp.NewContext(remoteAllocCtx)
+
+ // Touch the browser so we fail fast if the CDP URL is unreachable. We
+ // intentionally do NOT inject the stealth/UA script here — the user's
+ // Chrome is theirs, and rewriting its launch contract would be both
+ // surprising and likely break extensions, profile features, and
+ // already-open tabs.
+ if err := chromedp.Run(browserCtx, chromedp.ActionFunc(func(ctx context.Context) error {
+ return nil
+ })); err != nil {
+ browserCancel()
+ remoteAllocCancel()
+ return nil, nil, nil, nil, stealth.LaunchModeUninitialized, fmt.Errorf("failed to attach to CDP at %s: %w", wsURL, err)
+ }
+
+ slog.Info("attached to existing Chrome via CDP", "cdpUrl", wsURL)
+ return remoteAllocCtx, remoteAllocCancel, browserCtx, browserCancel, stealth.LaunchModeAttached, nil
+}
+
func findChromeBinary() string {
var candidates []string
switch goruntime.GOOS {
diff --git a/internal/config/config_types.go b/internal/config/config_types.go
index 7864fcca..d18ebd85 100644
--- a/internal/config/config_types.go
+++ b/internal/config/config_types.go
@@ -62,6 +62,14 @@ type RuntimeConfig struct {
ChromeBinary string
ChromeDebugPort int
ChromeExtraFlags string
+ // CDPAttachURL: when set, the bridge skips launching its own Chrome and
+ // connects to an already-running Chrome whose browser-level CDP
+ // WebSocket URL is provided here (e.g.
+ // "ws://127.0.0.1:9222/devtools/browser/abc"). Useful when you want the
+ // agent to drive the user's actual Chrome (extensions, profile, signed-in
+ // state) rather than a fresh isolated profile. Cleanup never kills the
+ // external Chrome — pinchtab only owns the CDP connection.
+ CDPAttachURL string
ExtensionPaths []string
UserAgent string
NoAnimations bool