High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.
Migrate BRIDGE_* environment variables to PINCHTAB_* prefix
Roopeshffbbca47fcc8
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 857d8063..cc50fb8e 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -13,7 +13,7 @@ go build -o pinchtab ./cmd/pinchtab./pinchtab# Run headless-BRIDGE_HEADLESS=true ./pinchtab+PINCHTAB_HEADLESS=true ./pinchtab# Enable pre-commit hookgit config core.hooksPath .githooks@@ -33,6 +33,7 @@ Requires **Go 1.25+** and **Google Chrome**.### Creating a Pull Request**Important:** When creating a PR, please keep the **"Allow edits from maintainers"** checkbox **enabled** (it's on by default). This lets us:+- Apply small fixes directly- Resolve merge conflicts automatically- Rebase and update your branch without asking@@ -71,6 +72,7 @@ go test -tags integration ./tests/integration -v -short```**Tips for stable integration tests:**+- Run with `-p 1` to avoid Chrome resource contention- Set `CI=true` for longer timeouts in CI environments- Use `-timeout 5m` to allow for Chrome startupdiff --git a/Dockerfile.goreleaser b/Dockerfile.goreleaserindex f0f020a3..baa45eb3 100644--- a/Dockerfile.goreleaser+++ b/Dockerfile.goreleaser@@ -21,11 +21,11 @@ COPY pinchtab /usr/local/bin/pinchtabUSER pinchtabWORKDIR /data-ENV BRIDGE_BIND=0.0.0.0 \- BRIDGE_PORT=9867 \- BRIDGE_HEADLESS=true \- BRIDGE_STATE_DIR=/data \- BRIDGE_PROFILE=/data/chrome-profile \+ENV PINCHTAB_BIND=0.0.0.0 \+ PINCHTAB_PORT=9867 \+ PINCHTAB_HEADLESS=true \+ PINCHTAB_STATE_DIR=/data \+ PINCHTAB_PROFILE_DIR=/data/chrome-profile \CHROME_BINARY=/usr/bin/chromium-browser \CHROME_FLAGS="--no-sandbox --disable-gpu"diff --git a/cmd/pinchtab/main.go b/cmd/pinchtab/main.goindex 6b871fc5..d70c532d 100644--- a/cmd/pinchtab/main.go+++ b/cmd/pinchtab/main.go@@ -39,7 +39,7 @@ func main() {}// Check if running as bridge-only instance (spawned by orchestrator)- if os.Getenv("BRIDGE_ONLY") == "1" {+ if os.Getenv("PINCHTAB_ONLY") == "1" || os.Getenv("BRIDGE_ONLY") == "1" {runBridgeServer(cfg)return}diff --git a/docker-compose.yml b/docker-compose.ymlindex b146e011..5e0abe87 100644--- a/docker-compose.yml+++ b/docker-compose.yml@@ -7,21 +7,21 @@ services:volumes:- pinchtab-data:/dataenvironment:- - BRIDGE_BIND=0.0.0.0- - BRIDGE_PORT=9867- - BRIDGE_HEADLESS=true- - BRIDGE_TOKEN=${PINCHTAB_TOKEN:-}- - BRIDGE_STATE_DIR=/data- - BRIDGE_PROFILE=/data/chrome-profile+ - PINCHTAB_BIND=0.0.0.0+ - PINCHTAB_PORT=9867+ - PINCHTAB_HEADLESS=true+ - PINCHTAB_TOKEN=${PINCHTAB_TOKEN:-}+ - PINCHTAB_STATE_DIR=/data+ - PINCHTAB_PROFILE_DIR=/data/chrome-profilerestart: unless-stopped# Shared memory is critical for Chrome stability- shm_size: '2gb'+ shm_size: "2gb"# Required for Chrome to work in containersecurity_opt:- seccomp:unconfined# Limit resourcesmem_limit: 2g- cpus: '2.0'+ cpus: "2.0"volumes:- pinchtab-data:\ No newline at end of file+ pinchtab-data:diff --git a/internal/config/config.go b/internal/config/config.goindex 0124e989..765dd634 100644--- a/internal/config/config.go+++ b/internal/config/config.go@@ -3,6 +3,7 @@ package configimport ("encoding/json""fmt"+ "log/slog""os""path/filepath""strconv"@@ -92,6 +93,68 @@ func envBoolOr(key string, fallback bool) bool {}}+func envMigrate(newKey, oldKey string) string {+ if v := os.Getenv(newKey); v != "" {+ return v+ }+ if v := os.Getenv(oldKey); v != "" {+ slog.Warn("deprecated env var, use "+newKey+" instead", "var", oldKey)+ return v+ }+ return ""+}++func envOrMigrate(newKey, oldKey, fallback string) string {+ if v := envMigrate(newKey, oldKey); v != "" {+ return v+ }+ return fallback+}++func envIntOrMigrate(newKey, oldKey string, fallback int) int {+ v := envMigrate(newKey, oldKey)+ if v == "" {+ return fallback+ }+ n, err := strconv.Atoi(v)+ if err != nil || n < 0 {+ return fallback+ }+ return n+}++func envBoolOrMigrate(newKey, oldKey string, fallback bool) bool {+ if v, ok := os.LookupEnv(newKey); ok {+ switch strings.ToLower(strings.TrimSpace(v)) {+ case "1", "true", "yes", "on":+ return true+ case "0", "false", "no", "off":+ return false+ default:+ return fallback+ }+ }+ if v, ok := os.LookupEnv(oldKey); ok {+ slog.Warn("deprecated env var, use "+newKey+" instead", "var", oldKey)+ switch strings.ToLower(strings.TrimSpace(v)) {+ case "1", "true", "yes", "on":+ return true+ case "0", "false", "no", "off":+ return false+ default:+ return fallback+ }+ }+ return fallback+}++func envMigrateIsSet(newKey, oldKey string) bool {+ if os.Getenv(newKey) != "" {+ return true+ }+ return os.Getenv(oldKey) != ""+}+// homeDir returns the user's home directory, checking $HOME first for container compatibilityfunc homeDir() string {if home := os.Getenv("HOME"); home != "" {@@ -162,35 +225,35 @@ type FileConfig struct {func Load() *RuntimeConfig {cfg := &RuntimeConfig{- Bind: envOr("BRIDGE_BIND", "127.0.0.1"),- Port: envOr("BRIDGE_PORT", "9867"),+ Bind: envOrMigrate("PINCHTAB_BIND", "BRIDGE_BIND", "127.0.0.1"),+ Port: envOrMigrate("PINCHTAB_PORT", "BRIDGE_PORT", "9867"),InstancePortStart: envIntOr("INSTANCE_PORT_START", 9868),InstancePortEnd: envIntOr("INSTANCE_PORT_END", 9968),CdpURL: os.Getenv("CDP_URL"),- Token: os.Getenv("BRIDGE_TOKEN"),- StateDir: envOr("BRIDGE_STATE_DIR", userConfigDir()),- Headless: envBoolOr("BRIDGE_HEADLESS", true),- NoRestore: os.Getenv("BRIDGE_NO_RESTORE") == "true",- ProfileDir: envOr("BRIDGE_PROFILE", filepath.Join(userConfigDir(), "chrome-profile")),- ChromeVersion: envOr("BRIDGE_CHROME_VERSION", "144.0.7559.133"),- Timezone: os.Getenv("BRIDGE_TIMEZONE"),- BlockImages: os.Getenv("BRIDGE_BLOCK_IMAGES") == "true",- BlockMedia: os.Getenv("BRIDGE_BLOCK_MEDIA") == "true",- BlockAds: envBoolOr("BRIDGE_BLOCK_ADS", false),- MaxTabs: envIntOr("BRIDGE_MAX_TABS", 20),+ Token: envMigrate("PINCHTAB_TOKEN", "BRIDGE_TOKEN"),+ StateDir: envOrMigrate("PINCHTAB_STATE_DIR", "BRIDGE_STATE_DIR", userConfigDir()),+ Headless: envBoolOrMigrate("PINCHTAB_HEADLESS", "BRIDGE_HEADLESS", true),+ NoRestore: envBoolOrMigrate("PINCHTAB_NO_RESTORE", "BRIDGE_NO_RESTORE", false),+ ProfileDir: envOrMigrate("PINCHTAB_PROFILE_DIR", "BRIDGE_PROFILE", filepath.Join(userConfigDir(), "chrome-profile")),+ ChromeVersion: envOrMigrate("PINCHTAB_CHROME_VERSION", "BRIDGE_CHROME_VERSION", "144.0.7559.133"),+ Timezone: envMigrate("PINCHTAB_TIMEZONE", "BRIDGE_TIMEZONE"),+ BlockImages: envBoolOrMigrate("PINCHTAB_BLOCK_IMAGES", "BRIDGE_BLOCK_IMAGES", false),+ BlockMedia: envBoolOrMigrate("PINCHTAB_BLOCK_MEDIA", "BRIDGE_BLOCK_MEDIA", false),+ BlockAds: envBoolOrMigrate("PINCHTAB_BLOCK_ADS", "BRIDGE_BLOCK_ADS", false),+ MaxTabs: envIntOrMigrate("PINCHTAB_MAX_TABS", "BRIDGE_MAX_TABS", 20),ChromeBinary: envOr("CHROME_BIN", os.Getenv("CHROME_BINARY")),ChromeExtraFlags: os.Getenv("CHROME_FLAGS"),ExtensionPaths: splitCommaPaths(os.Getenv("CHROME_EXTENSION_PATHS")),- UserAgent: os.Getenv("BRIDGE_USER_AGENT"),- NoAnimations: os.Getenv("BRIDGE_NO_ANIMATIONS") == "true",- StealthLevel: envOr("BRIDGE_STEALTH", "light"),+ UserAgent: envMigrate("PINCHTAB_USER_AGENT", "BRIDGE_USER_AGENT"),+ NoAnimations: envBoolOrMigrate("PINCHTAB_NO_ANIMATIONS", "BRIDGE_NO_ANIMATIONS", false),+ StealthLevel: envOrMigrate("PINCHTAB_STEALTH", "BRIDGE_STEALTH", "light"),ActionTimeout: 30 * time.Second,NavigateTimeout: 60 * time.Second,ShutdownTimeout: 10 * time.Second,WaitNavDelay: 1 * time.Second,}- configPath := envOr("BRIDGE_CONFIG", filepath.Join(userConfigDir(), "config.json"))+ configPath := envOrMigrate("PINCHTAB_CONFIG", "BRIDGE_CONFIG", filepath.Join(userConfigDir(), "config.json"))data, err := os.ReadFile(configPath)if err != nil {@@ -202,7 +265,7 @@ func Load() *RuntimeConfig {return cfg}- if fc.Port != "" && os.Getenv("BRIDGE_PORT") == "" {+ if fc.Port != "" && !envMigrateIsSet("PINCHTAB_PORT", "BRIDGE_PORT") {cfg.Port = fc.Port}if fc.InstancePortStart != nil && os.Getenv("INSTANCE_PORT_START") == "" {@@ -214,28 +277,28 @@ func Load() *RuntimeConfig {if fc.CdpURL != "" && os.Getenv("CDP_URL") == "" {cfg.CdpURL = fc.CdpURL}- if fc.Token != "" && os.Getenv("BRIDGE_TOKEN") == "" {+ if fc.Token != "" && !envMigrateIsSet("PINCHTAB_TOKEN", "BRIDGE_TOKEN") {cfg.Token = fc.Token}- if fc.StateDir != "" && os.Getenv("BRIDGE_STATE_DIR") == "" {+ if fc.StateDir != "" && !envMigrateIsSet("PINCHTAB_STATE_DIR", "BRIDGE_STATE_DIR") {cfg.StateDir = fc.StateDir}- if fc.ProfileDir != "" && os.Getenv("BRIDGE_PROFILE") == "" {+ if fc.ProfileDir != "" && !envMigrateIsSet("PINCHTAB_PROFILE_DIR", "BRIDGE_PROFILE") {cfg.ProfileDir = fc.ProfileDir}- if fc.Headless != nil && os.Getenv("BRIDGE_HEADLESS") == "" {+ if fc.Headless != nil && !envMigrateIsSet("PINCHTAB_HEADLESS", "BRIDGE_HEADLESS") {cfg.Headless = *fc.Headless}- if fc.NoRestore && os.Getenv("BRIDGE_NO_RESTORE") == "" {+ if fc.NoRestore && !envMigrateIsSet("PINCHTAB_NO_RESTORE", "BRIDGE_NO_RESTORE") {cfg.NoRestore = true}- if fc.MaxTabs != nil && os.Getenv("BRIDGE_MAX_TABS") == "" {+ if fc.MaxTabs != nil && !envMigrateIsSet("PINCHTAB_MAX_TABS", "BRIDGE_MAX_TABS") {cfg.MaxTabs = *fc.MaxTabs}- if fc.TimeoutSec > 0 && os.Getenv("BRIDGE_TIMEOUT") == "" {+ if fc.TimeoutSec > 0 && !envMigrateIsSet("PINCHTAB_TIMEOUT", "BRIDGE_TIMEOUT") {cfg.ActionTimeout = time.Duration(fc.TimeoutSec) * time.Second}- if fc.NavigateSec > 0 && os.Getenv("BRIDGE_NAV_TIMEOUT") == "" {+ if fc.NavigateSec > 0 && !envMigrateIsSet("PINCHTAB_NAV_TIMEOUT", "BRIDGE_NAV_TIMEOUT") {cfg.NavigateTimeout = time.Duration(fc.NavigateSec) * time.Second}diff --git a/internal/config/config_test.go b/internal/config/config_test.goindex 062ca14e..619f146e 100644--- a/internal/config/config_test.go+++ b/internal/config/config_test.go@@ -88,10 +88,12 @@ func TestMaskToken(t *testing.T) {}func TestLoadConfigDefaults(t *testing.T) {- // Clear relevant env vars+ _ = os.Unsetenv("PINCHTAB_PORT")+ _ = os.Unsetenv("PINCHTAB_BIND")_ = os.Unsetenv("BRIDGE_PORT")_ = os.Unsetenv("BRIDGE_BIND")_ = os.Unsetenv("CDP_URL")+ _ = os.Unsetenv("PINCHTAB_TOKEN")_ = os.Unsetenv("BRIDGE_TOKEN")cfg := Load()@@ -104,8 +106,8 @@ func TestLoadConfigDefaults(t *testing.T) {}func TestLoadConfigEnvOverrides(t *testing.T) {- _ = os.Setenv("BRIDGE_PORT", "1234")- defer func() { _ = os.Unsetenv("BRIDGE_PORT") }()+ _ = os.Setenv("PINCHTAB_PORT", "1234")+ defer func() { _ = os.Unsetenv("PINCHTAB_PORT") }()cfg := Load()if cfg.Port != "1234" {@@ -113,6 +115,31 @@ func TestLoadConfigEnvOverrides(t *testing.T) {}}+func TestLegacyBridgeEnvFallback(t *testing.T) {+ _ = os.Unsetenv("PINCHTAB_PORT")+ _ = os.Setenv("BRIDGE_PORT", "5555")+ defer func() { _ = os.Unsetenv("BRIDGE_PORT") }()++ cfg := Load()+ if cfg.Port != "5555" {+ t.Errorf("legacy fallback Port = %v, want 5555", cfg.Port)+ }+}++func TestPinchtabEnvTakesPrecedence(t *testing.T) {+ _ = os.Setenv("PINCHTAB_PORT", "7777")+ _ = os.Setenv("BRIDGE_PORT", "8888")+ defer func() {+ _ = os.Unsetenv("PINCHTAB_PORT")+ _ = os.Unsetenv("BRIDGE_PORT")+ }()++ cfg := Load()+ if cfg.Port != "7777" {+ t.Errorf("precedence Port = %v, want 7777 (PINCHTAB_ should win)", cfg.Port)+ }+}+func TestDefaultFileConfig(t *testing.T) {fc := DefaultFileConfig()if fc.Port != "9867" {@@ -126,8 +153,8 @@ func TestDefaultFileConfig(t *testing.T) {func TestLoadConfigFile(t *testing.T) {tmpDir := t.TempDir()configPath := filepath.Join(tmpDir, "config.json")- _ = os.Setenv("BRIDGE_CONFIG", configPath)- defer func() { _ = os.Unsetenv("BRIDGE_CONFIG") }()+ _ = os.Setenv("PINCHTAB_CONFIG", configPath)+ defer func() { _ = os.Unsetenv("PINCHTAB_CONFIG") }()// Create a dummy config fileconfigData := `{diff --git a/internal/dashboard/dashboard.go b/internal/dashboard/dashboard.goindex 605b4378..f3be9cfc 100644--- a/internal/dashboard/dashboard.go+++ b/internal/dashboard/dashboard.go@@ -14,6 +14,13 @@ import ("github.com/pinchtab/pinchtab/internal/bridge")+func envWithFallback(newKey, oldKey string) string {+ if v := os.Getenv(newKey); v != "" {+ return v+ }+ return os.Getenv(oldKey)+}+type DashboardConfig struct {IdleTimeout time.DurationDisconnectTimeout time.Duration@@ -108,7 +115,7 @@ func NewDashboard(cfg *DashboardConfig) *Dashboard {sseConns: make(map[chan AgentEvent]struct{}),sysConns: make(map[chan SystemEvent]struct{}),cancel: cancel,- childAuthToken: os.Getenv("BRIDGE_TOKEN"),+ childAuthToken: envWithFallback("PINCHTAB_TOKEN", "BRIDGE_TOKEN"),}return d}diff --git a/internal/orchestrator/orchestrator.go b/internal/orchestrator/orchestrator.goindex f8616f4a..cd2a983f 100644--- a/internal/orchestrator/orchestrator.go+++ b/internal/orchestrator/orchestrator.go@@ -20,6 +20,13 @@ import ("github.com/pinchtab/pinchtab/internal/profiles")+func envWithFallback(newKey, oldKey string) string {+ if v := os.Getenv(newKey); v != "" {+ return v+ }+ return os.Getenv(oldKey)+}+// InstanceEvent is emitted when instance state changes.type InstanceEvent struct {Type string `json:"type"` // "instance.started", "instance.stopped", "instance.error"@@ -114,7 +121,7 @@ func NewOrchestratorWithRunner(baseDir string, runner HostRunner) *Orchestrator// - Short timeout (<5s) would break first-request scenarios// See: internal/orchestrator/health.go (monitor), internal/bridge/init.go (InitChrome)client: &http.Client{Timeout: 60 * time.Second},- childAuthToken: os.Getenv("BRIDGE_TOKEN"),+ childAuthToken: envWithFallback("PINCHTAB_TOKEN", "BRIDGE_TOKEN"),portAllocator: NewPortAllocator(9868, 9968),idMgr: idutil.NewManager(),}@@ -208,12 +215,12 @@ func (o *Orchestrator) Launch(name, port string, headless bool, extensionPaths [}envOverrides := map[string]string{- "BRIDGE_PORT": port,- "BRIDGE_PROFILE": profilePath,- "BRIDGE_STATE_DIR": instanceStateDir,- "BRIDGE_HEADLESS": headlessStr,- "BRIDGE_NO_RESTORE": "true",- "BRIDGE_ONLY": "1",+ "PINCHTAB_PORT": port,+ "PINCHTAB_PROFILE_DIR": profilePath,+ "PINCHTAB_STATE_DIR": instanceStateDir,+ "PINCHTAB_HEADLESS": headlessStr,+ "PINCHTAB_NO_RESTORE": "true",+ "PINCHTAB_ONLY": "1",}if len(extensionPaths) > 0 {envOverrides["CHROME_EXTENSION_PATHS"] = strings.Join(extensionPaths, ",")diff --git a/scripts/launchd/com.pinchtab.bridge.plist b/scripts/launchd/com.pinchtab.bridge.plistindex dd9cc465..4342d925 100644--- a/scripts/launchd/com.pinchtab.bridge.plist+++ b/scripts/launchd/com.pinchtab.bridge.plist@@ -12,11 +12,11 @@<key>EnvironmentVariables</key><dict>- <key>BRIDGE_PORT</key>+ <key>PINCHTAB_PORT</key><string>9867</string>- <key>BRIDGE_HEADLESS</key>+ <key>PINCHTAB_HEADLESS</key><string>true</string>- <key>BRIDGE_PROFILE</key>+ <key>PINCHTAB_PROFILE_DIR</key><string>~/.pinchtab/chrome-profile</string></dict>diff --git a/scripts/systemd/pinchtab.service b/scripts/systemd/pinchtab.serviceindex 25a61e99..f4ff366e 100644--- a/scripts/systemd/pinchtab.service+++ b/scripts/systemd/pinchtab.service@@ -11,9 +11,9 @@ Restart=alwaysRestartSec=5# Environment-Environment="BRIDGE_PORT=9867"-Environment="BRIDGE_HEADLESS=true"-Environment="BRIDGE_PROFILE=%h/.pinchtab/chrome-profile"+Environment="PINCHTAB_PORT=9867"+Environment="PINCHTAB_HEADLESS=true"+Environment="PINCHTAB_PROFILE_DIR=%h/.pinchtab/chrome-profile"Environment="DISPLAY=:0"# Logging