Skip to content

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.md
index 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 hook
git 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 startup
diff --git a/Dockerfile.goreleaser b/Dockerfile.goreleaser
index f0f020a3..baa45eb3 100644
--- a/Dockerfile.goreleaser
+++ b/Dockerfile.goreleaser
@@ -21,11 +21,11 @@ COPY pinchtab /usr/local/bin/pinchtab
USER pinchtab
WORKDIR /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.go
index 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.yml
index b146e011..5e0abe87 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -7,21 +7,21 @@ services:
volumes:
- pinchtab-data:/data
environment:
- - 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-profile
restart: unless-stopped
# Shared memory is critical for Chrome stability
- shm_size: '2gb'
+ shm_size: "2gb"
# Required for Chrome to work in container
security_opt:
- seccomp:unconfined
# Limit resources
mem_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.go
index 0124e989..765dd634 100644
--- a/internal/config/config.go
+++ b/internal/config/config.go
@@ -3,6 +3,7 @@ package config
import (
"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 compatibility
func 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.go
index 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 file
configData := `{
diff --git a/internal/dashboard/dashboard.go b/internal/dashboard/dashboard.go
index 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.Duration
DisconnectTimeout 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.go
index 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.plist
index 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.service
index 25a61e99..f4ff366e 100644
--- a/scripts/systemd/pinchtab.service
+++ b/scripts/systemd/pinchtab.service
@@ -11,9 +11,9 @@ Restart=always
RestartSec=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