Skip to content

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

fix: improve Chrome detection and add Raspberry Pi guide (#105)

pinchtabdev3e147255e7f0
diff --git a/docs/guides/raspberry-pi.md b/docs/guides/raspberry-pi.md
new file mode 100644
index 00000000..7bc70e24
--- /dev/null
+++ b/docs/guides/raspberry-pi.md
@@ -0,0 +1,418 @@
+# Raspberry Pi Setup Guide
+
+Pinchtab works great on Raspberry Pi (3, 4, 5, Zero 2 W) for browser automation, web scraping, testing, and headless browsing. This guide covers installation, optimization, and common issues.
+
+## Requirements
+
+- **Raspberry Pi**: Pi 3, 4, 5, or Zero 2 W (ARM64/aarch64)
+- **OS**: Raspberry Pi OS (64-bit recommended) or Ubuntu
+- **RAM**: 2GB+ recommended (1GB works for headless with low tab counts)
+- **Node.js**: 18+ (install via [nvm](https://github.com/nvm-sh/nvm) recommended)
+- **Chrome/Chromium**: Required (not bundled with pinchtab)
+
+## Installation
+
+### Step 1: Install Chrome/Chromium
+
+Pinchtab requires Chrome or Chromium. Install it first:
+
+```bash
+sudo apt update
+sudo apt install -y chromium-browser
+```
+
+Verify installation:
+```bash
+which chromium-browser
+# Should output: /usr/bin/chromium-browser
+```
+
+### Step 2: Install Node.js
+
+**Option A: Via nvm (recommended)**
+```bash
+curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash
+source ~/.bashrc # or ~/.zshrc
+nvm install 22
+nvm use 22
+```
+
+**Option B: Via apt** (usually outdated, not recommended)
+```bash
+sudo apt install -y nodejs npm
+```
+
+Verify:
+```bash
+node -v # Should be 18+
+npm -v
+```
+
+### Step 3: Install Pinchtab
+
+```bash
+curl -fsSL https://pinchtab.com/install.sh | bash
+```
+
+Or manually via npm:
+```bash
+npm install -g pinchtab
+```
+
+### Step 4: Start Pinchtab
+
+```bash
+pinchtab
+```
+
+First startup takes ~5-10 seconds as Chrome initializes. You should see:
+```
+INFO starting chrome initialization headless=true
+INFO chrome initialized successfully
+INFO Bridge server listening addr=127.0.0.1:9867
+```
+
+Test it:
+```bash
+curl http://localhost:9867/health
+```
+
+## Configuration for Raspberry Pi
+
+### Headless Mode (Default)
+
+By default, pinchtab runs Chrome in headless mode (no GUI), which is perfect for Pi:
+
+```bash
+pinchtab # Headless by default
+```
+
+### Headed Mode (with Desktop)
+
+If you're running Raspberry Pi OS with desktop and want to see the browser:
+
+```bash
+BRIDGE_HEADLESS=false pinchtab
+```
+
+### Memory Optimization
+
+Raspberry Pi has limited RAM. Optimize pinchtab for lower memory usage:
+
+**Limit max tabs:**
+```bash
+BRIDGE_MAX_TABS=5 pinchtab
+```
+
+**Disable images (saves bandwidth + memory):**
+```bash
+BRIDGE_BLOCK_IMAGES=true pinchtab
+```
+
+**Block ads (saves bandwidth):**
+```bash
+BRIDGE_BLOCK_ADS=true pinchtab
+```
+
+**Combined example:**
+```bash
+BRIDGE_MAX_TABS=5 BRIDGE_BLOCK_IMAGES=true BRIDGE_BLOCK_ADS=true pinchtab
+```
+
+### Storage Location
+
+On Pi, you might want to use a USB drive or external storage for the Chrome profile:
+
+```bash
+BRIDGE_PROFILE=/mnt/usb/pinchtab-profile pinchtab
+```
+
+Or create a persistent config:
+```bash
+mkdir -p ~/.config/pinchtab
+cat > ~/.config/pinchtab/config.json <<EOF
+{
+ "port": "9867",
+ "headless": true,
+ "maxTabs": 5,
+ "profileDir": "/mnt/usb/pinchtab-profile"
+}
+EOF
+```
+
+## Performance Tips
+
+### 1. Use Headless Mode
+
+Headless mode uses significantly less RAM than headed:
+```bash
+# Default is headless=true, but you can be explicit:
+BRIDGE_HEADLESS=true pinchtab
+```
+
+### 2. Reduce Chrome Flags
+
+Add lighter-weight Chrome flags:
+```bash
+CHROME_FLAGS="--disable-gpu --disable-software-rasterizer --disable-dev-shm-usage" pinchtab
+```
+
+### 3. Swap Space (for 1GB Pi models)
+
+If you have only 1GB RAM, increase swap:
+```bash
+sudo dphys-swapfile swapoff
+sudo nano /etc/dphys-swapfile
+# Change CONF_SWAPSIZE=100 to CONF_SWAPSIZE=1024
+sudo dphys-swapfile setup
+sudo dphys-swapfile swapon
+```
+
+### 4. Overclock (Carefully)
+
+For Pi 4/5, mild overclocking can improve performance:
+```bash
+sudo raspi-config
+# Performance Options → Overclock → Moderate
+```
+
+⚠️ **Ensure adequate cooling** — use a heatsink or fan.
+
+### 5. Use Lightweight OS
+
+Consider **Raspberry Pi OS Lite** (no desktop) for dedicated automation:
+```bash
+# Install minimal OS, then:
+sudo apt install -y chromium-browser nodejs npm
+npm install -g pinchtab
+```
+
+## Running as a Service
+
+Run pinchtab automatically on boot using systemd:
+
+### Create service file:
+```bash
+sudo nano /etc/systemd/system/pinchtab.service
+```
+
+**Content:**
+```ini
+[Unit]
+Description=Pinchtab Browser Automation
+After=network.target
+
+[Service]
+Type=simple
+User=pi
+WorkingDirectory=/home/pi
+ExecStart=/home/pi/.nvm/versions/node/v22.13.0/bin/pinchtab
+Restart=always
+RestartSec=10
+Environment="BRIDGE_HEADLESS=true"
+Environment="BRIDGE_MAX_TABS=5"
+Environment="BRIDGE_BLOCK_IMAGES=true"
+
+[Install]
+WantedBy=multi-user.target
+```
+
+**Note:** Adjust `ExecStart` path to match your Node.js installation:
+```bash
+which pinchtab # Use this path in ExecStart
+```
+
+### Enable and start:
+```bash
+sudo systemctl daemon-reload
+sudo systemctl enable pinchtab
+sudo systemctl start pinchtab
+```
+
+### Check status:
+```bash
+sudo systemctl status pinchtab
+```
+
+### View logs:
+```bash
+sudo journalctl -u pinchtab -f
+```
+
+## Common Issues
+
+### Issue: "Chrome binary not found"
+
+**Cause:** Chromium not installed.
+
+**Solution:**
+```bash
+sudo apt install -y chromium-browser
+```
+
+If chromium is installed but pinchtab can't find it:
+```bash
+export CHROME_BIN=/usr/bin/chromium-browser
+pinchtab
+```
+
+Make it permanent:
+```bash
+echo 'export CHROME_BIN=/usr/bin/chromium-browser' >> ~/.bashrc
+source ~/.bashrc
+```
+
+### Issue: Chrome crashes or hangs
+
+**Cause:** Out of memory.
+
+**Solutions:**
+1. Reduce max tabs: `BRIDGE_MAX_TABS=3 pinchtab`
+2. Block images: `BRIDGE_BLOCK_IMAGES=true pinchtab`
+3. Increase swap (see Performance Tips)
+4. Close other applications
+
+### Issue: "Address already in use"
+
+**Cause:** Port 9867 is occupied.
+
+**Solution:** Use a different port:
+```bash
+BRIDGE_PORT=9868 pinchtab
+```
+
+### Issue: Slow page loads
+
+**Cause:** Limited bandwidth or CPU.
+
+**Solutions:**
+1. Block images/ads: `BRIDGE_BLOCK_IMAGES=true BRIDGE_BLOCK_ADS=true pinchtab`
+2. Increase navigation timeout:
+ ```json
+ {
+ "navigateSec": 90
+ }
+ ```
+3. Use wired Ethernet instead of Wi-Fi
+
+### Issue: npm install fails with EACCES
+
+**Cause:** Permission error.
+
+**Solution:** Use nvm (recommended) or fix npm permissions:
+```bash
+# Option 1: Use nvm (best)
+curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash
+nvm install 22
+npm install -g pinchtab
+
+# Option 2: Fix npm permissions
+mkdir ~/.npm-global
+npm config set prefix '~/.npm-global'
+echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
+source ~/.bashrc
+npm install -g pinchtab
+```
+
+## Example Use Cases
+
+### Web Scraping Cron Job
+
+```bash
+#!/bin/bash
+# scrape-daily.sh
+
+curl -X POST http://localhost:9867/tabs \
+ -H "Content-Type: application/json" \
+ -d '{
+ "url": "https://example.com",
+ "actions": [
+ {"kind": "wait", "selector": ".content"}
+ ]
+ }' | jq -r '.snapshot' > /home/pi/data/snapshot-$(date +%Y%m%d).json
+```
+
+Schedule with cron:
+```bash
+crontab -e
+# Add:
+0 2 * * * /home/pi/scrape-daily.sh
+```
+
+### Home Automation Dashboard
+
+Render a web dashboard on an HDMI screen:
+```bash
+BRIDGE_HEADLESS=false pinchtab
+curl -X POST http://localhost:9867/tabs \
+ -H "Content-Type: application/json" \
+ -d '{
+ "url": "http://homeassistant.local:8123",
+ "kiosk": true
+ }'
+```
+
+### Automated Testing
+
+Run Playwright/Puppeteer tests against pinchtab:
+```javascript
+// test.js
+const { chromium } = require('playwright');
+
+(async () => {
+ const browser = await chromium.connectOverCDP('http://localhost:9867');
+ const page = await browser.newPage();
+ await page.goto('https://example.com');
+ console.log(await page.title());
+ await browser.close();
+})();
+```
+
+## Monitoring
+
+Check pinchtab health and resource usage:
+
+```bash
+# Health check
+curl http://localhost:9867/health
+
+# Metrics (if enabled)
+curl http://localhost:9867/metrics
+
+# System resources
+htop # Install: sudo apt install htop
+```
+
+## Upgrading
+
+```bash
+npm update -g pinchtab
+pinchtab --version
+```
+
+## Uninstallation
+
+```bash
+# Remove pinchtab
+npm uninstall -g pinchtab
+
+# Remove Chrome profile data
+rm -rf ~/.config/pinchtab
+```
+
+## Further Reading
+
+- [Data Storage Guide](data-storage.md) — Where pinchtab stores files
+- [Configuration Reference](../references/configuration.md) — All config options
+- [API Reference](../references/api-reference.json) — REST API documentation
+- [Memory Monitoring](memory-monitoring.md) — Track memory usage
+
+## Community
+
+- **GitHub**: https://github.com/pinchtab/pinchtab
+- **Issues**: https://github.com/pinchtab/pinchtab/issues
+- **Discussions**: https://github.com/pinchtab/pinchtab/discussions
+
+---
+
+**Have a cool Raspberry Pi + Pinchtab project?** Share it in GitHub Discussions!
diff --git a/docs/index.json b/docs/index.json
index c00d370f..5c02d728 100644
--- a/docs/index.json
+++ b/docs/index.json
@@ -27,7 +27,8 @@
"guides/identifying-instances.md",
"guides/agent-optimization.md",
"guides/memory-monitoring.md",
- "guides/data-storage.md"
+ "guides/data-storage.md",
+ "guides/raspberry-pi.md"
],
"proposals": [
"proposals/default-instance.md",
diff --git a/install.sh b/install.sh
index df428d9e..66663705 100755
--- a/install.sh
+++ b/install.sh
@@ -106,6 +106,63 @@ check_npm() {
ui_success "npm $(npm -v) found"
}
+check_chrome() {
+ local chrome_found=false
+ local chrome_path=""
+
+ # Check common Chrome/Chromium locations
+ local candidates=(
+ "google-chrome"
+ "google-chrome-stable"
+ "chromium"
+ "chromium-browser"
+ "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
+ "/Applications/Chromium.app/Contents/MacOS/Chromium"
+ "/usr/bin/google-chrome"
+ "/usr/bin/google-chrome-stable"
+ "/usr/bin/chromium"
+ "/usr/bin/chromium-browser"
+ )
+
+ for candidate in "${candidates[@]}"; do
+ if command -v "$candidate" &> /dev/null || [[ -f "$candidate" ]]; then
+ chrome_found=true
+ chrome_path="$candidate"
+ break
+ fi
+ done
+
+ if [[ "$chrome_found" == true ]]; then
+ ui_success "Chrome/Chromium found: $chrome_path"
+ else
+ ui_error "Chrome or Chromium not found"
+ echo ""
+ echo "Pinchtab requires Chrome or Chromium to be installed."
+ echo ""
+ if [[ "$OS" == "macos" ]]; then
+ echo "Install Chrome or Chromium:"
+ echo " • Chrome: https://www.google.com/chrome/"
+ echo " • Chromium (via Homebrew): brew install chromium"
+ else
+ echo "Install Chrome or Chromium:"
+ echo ""
+ echo " Debian/Ubuntu/Raspberry Pi:"
+ echo " sudo apt update && sudo apt install -y chromium-browser"
+ echo ""
+ echo " Fedora/RHEL:"
+ echo " sudo dnf install -y chromium"
+ echo ""
+ echo " Arch Linux:"
+ echo " sudo pacman -S chromium"
+ echo ""
+ echo " Or download Chrome: https://www.google.com/chrome/"
+ fi
+ echo ""
+ echo "After installing Chrome/Chromium, run this installer again."
+ exit 1
+ fi
+}
+
install_pinchtab() {
ui_section "Installing Pinchtab"
@@ -180,6 +237,7 @@ main() {
detect_os
check_node
check_npm
+ check_chrome
install_pinchtab
verify_installation
show_next_steps
diff --git a/internal/bridge/init.go b/internal/bridge/init.go
index 4f02a55b..275f6bdf 100644
--- a/internal/bridge/init.go
+++ b/internal/bridge/init.go
@@ -6,6 +6,7 @@ import (
"log/slog"
"math/rand"
"os"
+ "strings"
"github.com/chromedp/chromedp"
"github.com/pinchtab/pinchtab/internal/assets"
@@ -160,7 +161,31 @@ func startChrome(allocCtx context.Context, cfg *config.RuntimeConfig, opts []chr
})); err != nil {
cancel()
allocCancel()
- slog.Error("failed to connect to chrome browser", "error", err.Error())
+
+ // Provide helpful error message if Chrome binary is not found
+ errMsg := err.Error()
+ if strings.Contains(errMsg, "executable file not found") ||
+ strings.Contains(errMsg, "no such file or directory") {
+ slog.Error("chrome binary not found", "error", errMsg)
+
+ // Suggest installation instructions
+ if cfg.ChromeBinary != "" {
+ slog.Error("chrome not found at specified path", "path", cfg.ChromeBinary)
+ } else {
+ slog.Error("chrome not found in common locations")
+ }
+
+ slog.Info("install chrome or chromium:")
+ slog.Info(" debian/ubuntu/raspberry pi: sudo apt install -y chromium-browser")
+ slog.Info(" fedora/rhel: sudo dnf install -y chromium")
+ slog.Info(" arch: sudo pacman -S chromium")
+ slog.Info(" macos: brew install chromium")
+ slog.Info(" or set CHROME_BIN environment variable to chrome binary path")
+
+ return nil, nil, fmt.Errorf("chrome/chromium not found: please install chrome or chromium, or set CHROME_BIN environment variable")
+ }
+
+ slog.Error("failed to connect to chrome browser", "error", errMsg)
return nil, nil, fmt.Errorf("failed to connect to chrome: %w", err)
}
slog.Debug("chrome browser connected successfully")