Skip to content

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

feat: ARM64/Raspberry Pi optimization with architecture-aware Chrome detection (#107)

pinchtabdeva6774fe8b897
diff --git a/DEFINITION_OF_DONE.md b/DEFINITION_OF_DONE.md
index c61159cf..0b172eb2 100644
--- a/DEFINITION_OF_DONE.md
+++ b/DEFINITION_OF_DONE.md
@@ -12,7 +12,11 @@ These run automatically via `ci.yml`. If your PR fails them, fix and re-push.
- [ ] **Error handling explicit** — All errors wrapped with `%w`, no silent failures
- [ ] **No regressions** — Verify stealth, token efficiency, session persistence work (test locally if unsure)
- [ ] **SOLID principles** — Functions do one thing, testable, no unnecessary deps
-- [ ] **No redundant comments** — Don't restate what the code already says; comments should explain *why*, not *what*
+- [ ] **No redundant comments** — Comments explain *why* or *context*, not *what* the code does
+ - ❌ Bad: `// Loop through items` above `for _, item := range items`
+ - ❌ Bad: `// Return error` above `return err`
+ - ✅ Good: `// Prioritize chromium-browser on ARM64 (Raspberry Pi default)`
+ - ✅ Good: `// Chrome may not be installed in CI, so empty result is valid`
## Manual — Testing (Required)
- [ ] **New/changed functionality has tests** — Same-package unit tests preferred; use mockBridge for integration
@@ -24,7 +28,6 @@ These run automatically via `ci.yml`. If your PR fails them, fix and re-push.
## Manual — Documentation (Required)
- [ ] **README.md updated** — If user-facing changes (CLI, API, env vars, install)
-- [ ] **CHANGELOG.md entry added** — Under `## Unreleased` with PR link
- [ ] **/docs/ updated** — If API/architecture/perf changed (optional for small fixes)
## Manual — Review (Required)
@@ -34,7 +37,7 @@ These run automatically via `ci.yml`. If your PR fails them, fix and re-push.
## Conditional (Only if applicable)
- [ ] Headed-mode tested (if dashboard/UI changes)
-- [ ] CHANGELOG mentions breaking changes (if any)
+- [ ] Breaking changes documented in PR description (if any)
---
@@ -44,6 +47,7 @@ These run automatically via `ci.yml`. If your PR fails them, fix and re-push.
- [ ] Unit/integration tests added & passing
- [ ] Error handling explicit (wrapped with %w)
- [ ] No regressions in stealth/perf/persistence
-- [ ] README/CHANGELOG updated (if user-facing)
+- [ ] No redundant comments (explain why, not what)
+- [ ] README/docs updated (if user-facing)
- [ ] npm install works (if npm changes)
```
diff --git a/README.md b/README.md
index d3ceb944..9dd1509d 100644
--- a/README.md
+++ b/README.md
@@ -37,6 +37,7 @@ PinchTab is a **standalone HTTP server** that gives AI agents direct control ove
- **Multi-instance** — Run multiple parallel Chrome processes with isolated profiles
- **Self-contained** — 12MB binary, no external dependencies
- **Accessibility-first** — Stable element refs instead of fragile coordinates
+- **ARM64-optimized** — First-class Raspberry Pi support with automatic Chromium detection
---
diff --git a/docs/guides/raspberry-pi.md b/docs/guides/raspberry-pi.md
index 7bc70e24..9e3f3c17 100644
--- a/docs/guides/raspberry-pi.md
+++ b/docs/guides/raspberry-pi.md
@@ -27,6 +27,8 @@ which chromium-browser
# Should output: /usr/bin/chromium-browser
```
+> **ARM64 Optimization**: Pinchtab automatically detects ARM64/ARM architecture and prioritizes `chromium-browser` for optimal Raspberry Pi compatibility. No manual configuration needed!
+
### Step 2: Install Node.js
**Option A: Via nvm (recommended)**
diff --git a/internal/bridge/init.go b/internal/bridge/init.go
index 275f6bdf..16af4e82 100644
--- a/internal/bridge/init.go
+++ b/internal/bridge/init.go
@@ -6,6 +6,7 @@ import (
"log/slog"
"math/rand"
"os"
+ "runtime"
"strings"
"github.com/chromedp/chromedp"
@@ -37,29 +38,45 @@ func InitChrome(cfg *config.RuntimeConfig) (context.Context, context.CancelFunc,
}
// findChromeBinary searches for Chrome in common installation locations
+// On ARM64 (Raspberry Pi, etc.), prioritizes chromium-browser for optimal compatibility
func findChromeBinary() string {
- // Common Chrome/Chromium binary locations by OS
- candidates := []string{
- // macOS
- "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
- "/Applications/Chromium.app/Contents/MacOS/Chromium",
- // Linux
- "/usr/bin/google-chrome",
- "/usr/bin/google-chrome-stable",
- "/usr/bin/chromium",
- "/usr/bin/chromium-browser",
- // Windows (via WSL or MSYS)
- "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe",
- "C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe",
+ var candidates []string
+
+ // ARM64-specific optimization: Chromium is the standard on Raspberry Pi
+ if runtime.GOARCH == "arm64" || runtime.GOARCH == "arm" {
+ candidates = []string{
+ // ARM64/Raspberry Pi - prioritize chromium-browser
+ "/usr/bin/chromium-browser",
+ "/usr/bin/chromium",
+ "/usr/bin/google-chrome",
+ "/usr/bin/google-chrome-stable",
+ }
+ slog.Debug("detected ARM architecture, prioritizing chromium-browser", "arch", runtime.GOARCH)
+ } else {
+ // x86/x64 - standard order
+ candidates = []string{
+ // macOS
+ "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+ "/Applications/Chromium.app/Contents/MacOS/Chromium",
+ // Linux
+ "/usr/bin/google-chrome",
+ "/usr/bin/google-chrome-stable",
+ "/usr/bin/chromium",
+ "/usr/bin/chromium-browser",
+ // Windows (via WSL or MSYS)
+ "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe",
+ "C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe",
+ }
}
for _, path := range candidates {
if _, err := os.Stat(path); err == nil {
- slog.Debug("found chrome binary", "path", path)
+ slog.Debug("found chrome binary", "path", path, "arch", runtime.GOARCH)
return path
}
}
+ slog.Debug("no chrome binary found in common locations", "arch", runtime.GOARCH)
return ""
}
diff --git a/internal/bridge/init_test.go b/internal/bridge/init_test.go
new file mode 100644
index 00000000..357154df
--- /dev/null
+++ b/internal/bridge/init_test.go
@@ -0,0 +1,27 @@
+package bridge
+
+import (
+ "runtime"
+ "testing"
+)
+
+func TestFindChromeBinary_ARM64Prioritization(t *testing.T) {
+ // Verifies function doesn't panic across architectures (ARM64 vs x86_64)
+ // Chrome may not be installed in CI, so empty result is valid
+ result := findChromeBinary()
+
+ if result != "" {
+ t.Logf("Found Chrome binary: %s (arch: %s)", result, runtime.GOARCH)
+ } else {
+ t.Logf("No Chrome binary found (expected in CI, arch: %s)", runtime.GOARCH)
+ }
+}
+
+func TestFindChromeBinary_NoPathTraversal(t *testing.T) {
+ // Ensures only absolute paths are returned (security check)
+ result := findChromeBinary()
+
+ if result != "" && result[0] != '/' && result[1] != ':' {
+ t.Errorf("findChromeBinary returned non-absolute path: %s", result)
+ }
+}