High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.
docs: cosmetic updates - simplify titles, streamline building guide, add configuration reference, remove docker from guides
Mario44ff1506efcc
diff --git a/docs/architecture/building.md b/docs/architecture/building.mdindex 3ce0b5c7..f0471607 100644--- a/docs/architecture/building.md+++ b/docs/architecture/building.md@@ -1,6 +1,6 @@-# Building Pinchtab from Source+# Contributing-Complete guide to clone, build, and run Pinchtab from source code.+Guide to build PinchTab from source and contribute to the project.## System Requirements@@ -43,28 +43,21 @@ sudo yum install -y golang gitgo version```-**Manual (any OS):**-Download from https://golang.org/dl/ and follow instructions.-### Install Chrome/Chromium**macOS (Homebrew):**```bashbrew install chromium-# Or use system Chrome-which chromium # /usr/local/bin/chromium```**Linux (Ubuntu/Debian):**```bashsudo apt install -y chromium-browser-which chromium-browser```**Linux (RHEL/CentOS):**```bashsudo yum install -y chromium-which chromium```### Verify Installations@@ -75,75 +68,25 @@ git --version # git version 2.39.0chromium --version # Chromium 120.0.6099.xx```------## Part 2: Clone the Repository+### Install Dependencies-### Clone from GitHub+Clone the repository and download Go modules:```bashgit clone https://github.com/pinchtab/pinchtab.gitcd pinchtab-```--### Verify You're on Main Branch--```bash-git branch-# * main-# feat/...-# other-branches-```--### Check Project Structure--```bash-ls -la-# cmd/ # Go entry points-# docs/ # Documentation-# internal/ # Core packages-# scripts/ # Build and utility scripts-# go.mod # Go module file-# go.sum # Go module checksums-# Dockerfile # Container build-# README.md # Project overview-```-------## Part 3: Install Dependencies--### Download Go Modules--```bash-cd ~/dev/pinchtab # or your pinchtab directorygo mod download```-**What it does:**-- Downloads all Go dependencies from `go.mod`-- Verifies checksums against `go.sum`-- Caches modules locally--**Output:**-```-go: downloading github.com/chromedp/chromedp v0.14.2-go: downloading github.com/chromedp/cdproto v0.0.0-...-...-```--### Verify Dependencies-+Verify:```bash-go mod verify-# go: all module checksums verified (or error if corrupted)--go list -m all # List all dependencies+go mod verify # Verifies all checksums+go list -m all # List all dependencies```----## Part 4: Build the Project+## Part 2: Build the Project### Simple Build@@ -156,52 +99,17 @@ go build -o pinchtab ./cmd/pinchtab- Produces binary: `./pinchtab`- Takes ~30-60 seconds-**Output:**-```-# (no output = success)-ls -la pinchtab-# -rwxr-xr-x pinchtab 12MB (approximate size)-```--### Optimized Build (for production)--```bash-go build -ldflags="-s -w" -o pinchtab ./cmd/pinchtab-```--**Flags explained:**-- `-ldflags="-s -w"` — Strip debug info, smaller binary (~8MB)-- `-o pinchtab` — Output filename-- `./cmd/pinchtab` — Build source directory--### Build with Version Info--```bash-VERSION=$(git describe --tags --always)-go build \- -ldflags="-s -w -X main.version=$VERSION" \- -o pinchtab \- ./cmd/pinchtab--./pinchtab --version-# pinchtab 0.7.6 (or current version)-```--### Verify Build-+**Verify:**```bash+ls -la pinchtab./pinchtab --version-# pinchtab dev--./pinchtab help-# Shows help text```----## Part 5: Run the Server+## Part 3: Run the Server-### Start Pinchtab (Headless Mode)+### Start (Headless)```bash./pinchtab@@ -209,377 +117,115 @@ go build \**Expected output:**```-🦀 PINCH! PINCH! port=9867 cdp= stealth=light+🦀 PINCH! PINCH! port=9867auth disabled (set BRIDGE_TOKEN to enable)-startup configuration bind=127.0.0.1 port=9867 headless=true stealth=light ...-tabs restored count=0```-The server is now running on `http://127.0.0.1:9867`.--### Start with Visible Window (Headed Mode)+### Start (Headed Mode)```bashBRIDGE_HEADLESS=false ./pinchtab```-Opens Chrome in the foreground so you can see what's happening.--### Start in Background+Opens Chrome in the foreground.-```bash-./pinchtab &-# [1] 12345-```+### Background-Or with nohup (survives terminal close):```bashnohup ./pinchtab > pinchtab.log 2>&1 &tail -f pinchtab.log # Watch logs```-### Configuration--Common environment variables:--```bash-# Port-BRIDGE_PORT=9868 ./pinchtab--# Custom Chrome binary-CHROME_BINARY=/usr/bin/google-chrome ./pinchtab--# Custom profile directory-BRIDGE_PROFILE=~/.pinchtab/profile1 ./pinchtab--# Stealth mode-BRIDGE_STEALTH=full ./pinchtab--# Block ads-BRIDGE_BLOCK_ADS=true ./pinchtab--# API authentication-BRIDGE_TOKEN=secret-token ./pinchtab--# Multiple settings-BRIDGE_PORT=9868 BRIDGE_STEALTH=full BRIDGE_BLOCK_ADS=true ./pinchtab-```-----## Part 6: Verify Installation+## Part 4: Quick Test### Health Check-In another terminal:```bashcurl http://localhost:9867/health```-**Response:**-```json-{- "status": "ok",- "version": "dev",- "uptime": 123-}-```--### Try a Command+### Try CLI```bash-# Navigate-curl -X POST http://localhost:9867/tab \- -H "Content-Type: application/json" \- -d '{"action":"new","url":"https://example.com"}'--# Extract text-curl http://localhost:9867/text-```--### Test with pinchtab CLI--```bash-./pinchtab help # Show help-./pinchtab quick https://example.com # Quick workflow-./pinchtab nav https://github.com # Navigate-./pinchtab snap # Get snapshot+./pinchtab quick https://example.com+./pinchtab nav https://github.com+./pinchtab snap```----## Part 7: Development Setup+## Development### Run Tests```bash-go test ./...-```--**Output:**-```-ok github.com/pinchtab/pinchtab/cmd/pinchtab 1.234s-ok github.com/pinchtab/pinchtab/internal/bridge 2.567s-... more packages-```--### Run Tests with Coverage--```bash+go test ./... -vgo test ./... -v -coverprofile=coverage.out-go tool cover -html=coverage.out # Open in browser-```--### Format Code--```bash-gofmt -w .-```--### Lint Code--```bash-golangci-lint run ./...-```--(Install first if needed):-```bash-curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s -- -b ~/bin v2.9.0-```--### Run Pre-Push Checks--```bash-./scripts/check.sh-```--**Runs:**-- gofmt check-- go vet-- Build-- Tests with coverage-- Lint (if installed)-------## Part 8: Docker Build--### Build Docker Image--```bash-docker build -t pinchtab:latest .-```--**Build stages:**-1. Builder stage — Compiles Go binary-2. Runtime stage — Minimal Alpine with Chrome--### Run Docker Container--```bash-docker run -d -p 9867:9867 pinchtab:latest-```--### Verify Docker--```bash-curl http://localhost:9867/health-```--### Docker with Custom Configuration--```bash-docker run -d \- -p 9868:9867 \- -e BRIDGE_PORT=9867 \- -e BRIDGE_STEALTH=full \- -e BRIDGE_BLOCK_ADS=true \- pinchtab:latest-```-------## Common Build Issues--### Issue 1: "go: command not found"--**Problem:** Go not installed or not in PATH--**Solution:**-```bash-which go # Should show path-go version # Should show version--# If not found, install Go (see Prerequisites)-export PATH=$PATH:/usr/local/go/bin # Add to PATH if needed-```--### Issue 2: "chromium-browser: command not found"--**Problem:** Chrome/Chromium not installed--**Solution:**-```bash-# macOS-brew install chromium--# Linux Ubuntu/Debian-sudo apt install chromium-browser--# Linux RHEL/CentOS-sudo yum install chromium-```--### Issue 3: Build Fails with "undefined reference"--**Problem:** Missing Go modules--**Solution:**-```bash-go mod download-go mod tidy-go build -o pinchtab ./cmd/pinchtab-```--### Issue 4: "permission denied" when running binary--**Problem:** Binary not executable--**Solution:**-```bash-chmod +x pinchtab-./pinchtab --version-```--### Issue 5: Port 9867 already in use--**Problem:** Another service using the port--**Solution:**-```bash-# Use different port-BRIDGE_PORT=9868 ./pinchtab--# Or find and kill the process-lsof -i :9867-kill -9 <PID>-```--### Issue 6: Chrome crashes on startup--**Problem:** Missing libraries or wrong flags--**Solution:**-```bash-# Try with debug flags-CHROME_FLAGS="--no-sandbox --disable-dev-shm-usage --disable-gpu" ./pinchtab--# Or use custom Chrome binary-CHROME_BINARY=/usr/bin/google-chrome ./pinchtab+go tool cover -html=coverage.out # View coverage```------## Build Variations+### Code Quality-### Build for Different OS--**macOS (from any OS):**```bash-GOOS=darwin GOARCH=amd64 go build -o pinchtab-darwin-amd64 ./cmd/pinchtab+gofmt -w . # Format code+golangci-lint run ./... # Lint (install if needed)+./scripts/check.sh # Run all checks```-**Linux (from any OS):**-```bash-GOOS=linux GOARCH=amd64 go build -o pinchtab-linux-amd64 ./cmd/pinchtab-```--**Windows (from any OS):**-```bash-GOOS=windows GOARCH=amd64 go build -o pinchtab-windows-amd64.exe ./cmd/pinchtab-```--### Static Build+### Pre-Commit Hook```bash-CGO_ENABLED=0 GOOS=linux go build -o pinchtab-static ./cmd/pinchtab+./scripts/setup-hooks.sh```-Creates a fully static binary with no external dependencies.+Automatically runs checks before committing.------## Development Workflow--### 1. Create Feature Branch+### Development Workflow```bash+# 1. Create feature branchgit checkout -b feat/my-feature-```-### 2. Make Changes+# 2. Make changes+# ... edit files ...-Edit Go files in `cmd/pinchtab/` or `internal/`--### 3. Run Tests--```bash+# 3. Testgo test ./... -v-```-### 4. Run Checks--```bash-./scripts/check.sh-```--### 5. Commit Changes+# 4. Format & lint+gofmt -w .+golangci-lint run ./...-```bash+# 5. Commitgit add .-git commit -m "feat: description of change"-```--### 6. Push Branch+git commit -m "feat: description"-```bash+# 6. Pushgit push origin feat/my-feature-```-### 7. Create Pull Request--On GitHub, create PR from your branch to `main`.+# 7. Create PR on GitHub+```---## Continuous Integration-### Pre-Commit Hook--Automatically runs checks before committing:--```bash-./scripts/setup-hooks.sh-```--Now `git commit` will run checks automatically.--### GitHub Actions--On push, GitHub Actions runs:-- Format check (gofmt)-- Vet check (go vet)-- Build-- Tests with coverage-- Lint check (golangci-lint)+GitHub Actions automatically runs on push:+- Format checks (gofmt)+- Vet checks (go vet)+- Build verification+- Full test suite with coverage+- Linting (golangci-lint)-See `.github/workflows/go-verify.yml` for details.+See `.github/workflows/` for details.---## Installation as CLI-### Install Globally (from source)+### From Source```bashgo build -o ~/go/bin/pinchtab ./cmd/pinchtab@@ -591,7 +237,7 @@ pinchtab helppinchtab --version```-### Install via npm (published releases)+### Via npm (released builds)```bashnpm install -g pinchtab@@ -600,84 +246,6 @@ pinchtab --version----## Next Steps--1. **Run the server:** `./pinchtab`-2. **Try the CLI:** `./pinchtab quick https://example.com`-3. **Read the API:** See `docs/curl-commands.md`-4. **Check workflows:** See `docs/getting-started-api-workflows.md`-5. **Contribute:** Create a feature branch and submit a PR-------## Troubleshooting--### Check Version--```bash-./pinchtab --version-```--### Check Configuration--```bash-./pinchtab help-```--### View Logs--```bash-./pinchtab &-# Watch output directly-```--Or save to file:-```bash-./pinchtab > pinchtab.log 2>&1 &-tail -f pinchtab.log-```--### Debug Mode--```bash-# Set verbose logging (if supported)-./pinchtab -v-./pinchtab --debug-```--### Test Health--```bash-curl http://localhost:9867/health | jq .-```-------## Quick Start Script--Save as `build-and-run.sh`:--```bash-#!/bin/bash-set -e--echo "🔨 Building Pinchtab..."-go build -o pinchtab ./cmd/pinchtab--echo "✅ Build complete!"-echo ""-echo "🚀 Starting Pinchtab server..."-./pinchtab-```--Then run:-```bash-chmod +x build-and-run.sh-./build-and-run.sh-```------## Resources- **GitHub Repository:** https://github.com/pinchtab/pinchtab@@ -689,10 +257,10 @@ chmod +x build-and-run.sh## Support-Having issues? Check:-1. System requirements met?-2. All dependencies installed?+Issues? Check:+1. All dependencies installed?+2. Go and Chrome versions correct?3. Port 9867 available?-4. Chrome/Chromium working?+4. Check logs: `tail -f pinchtab.log`-See `docs/` for more guides and examples.+See `docs/` for guides and examples.diff --git a/docs/architecture/pinchtab-architecture.md b/docs/architecture/pinchtab-architecture.mdindex 1a26378a..d2686cbf 100644--- a/docs/architecture/pinchtab-architecture.md+++ b/docs/architecture/pinchtab-architecture.md@@ -1,9 +1,9 @@-# Pinchtab Architecture+# Architecture## OverviewPinchtab is an HTTP server (Go binary, ~12MB) that wraps Chrome DevTools Protocol (CDP)-to give AI agents browser control via a simple REST API.+to give AI agents browser control via a simple REST API.**Self-hosted mode (default):** Pinchtab launches and manages its own Chrome instance.diff --git a/docs/get-started.md b/docs/get-started.mdindex 7f22f733..7622b500 100644--- a/docs/get-started.md+++ b/docs/get-started.md@@ -1,4 +1,4 @@-# Getting Started with PinchTab+# Getting StartedGet PinchTab running in 5 minutes, from zero to browser automation.diff --git a/docs/guides/identifying-instances.md b/docs/guides/identifying-instances.mdindex c9a1a2fa..d0efdd64 100644--- a/docs/guides/identifying-instances.md+++ b/docs/guides/identifying-instances.md@@ -1,4 +1,4 @@-# Identifying Pinchtab Chrome Instances+# Chrome InstancesRunning multiple Chrome instances? Here's how to tell Pinchtab's apart from your regular browser.diff --git a/docs/index.json b/docs/index.jsonindex a13faf67..35eaea6b 100644--- a/docs/index.json+++ b/docs/index.json@@ -9,6 +9,7 @@],"references": ["references/endpoints.md",+ "references/configuration.md","references/cli-commands.md","references/curl-commands.md"],@@ -20,7 +21,6 @@],"guides": ["guides/cdp-url-shared-chrome.md",- "guides/docker.md","guides/headed-mode-guide.md","guides/identifying-instances.md"]diff --git a/docs/references/configuration.md b/docs/references/configuration.mdnew file mode 100644index 00000000..2d163e01--- /dev/null+++ b/docs/references/configuration.md@@ -0,0 +1,330 @@+# Configuration++Complete reference for all PinchTab environment variables and configuration options.++## Environment Variables++### Port & Network++| Variable | Default | Description |+|---|---|---|+| `BRIDGE_PORT` | `9867` | HTTP server port |+| `BRIDGE_BIND` | `127.0.0.1` | Bind address (127.0.0.1 = localhost only, 0.0.0.0 = all interfaces) |++### Browser & Chrome++| Variable | Default | Description |+|---|---|---|+| `CHROME_BINARY` | Auto-detect | Path to Chrome/Chromium binary |+| `BRIDGE_HEADLESS` | `true` | Run Chrome headless (no visible window) |+| `BRIDGE_PROFILE` | Default profile | Chrome profile name (stored in `~/.pinchtab/profiles/{name}`) |++### Stealth & Detection++| Variable | Default | Description |+|---|---|---|+| `BRIDGE_STEALTH` | `light` | Stealth level: `light`, `medium`, `full` (higher = more bot detection bypass, slower) |++### Content Filtering++| Variable | Default | Description |+|---|---|---|+| `BRIDGE_BLOCK_ADS` | `false` | Block ad domains (speeds up loading) |+| `BRIDGE_BLOCK_IMAGES` | `false` | Block image loading |+| `BRIDGE_BLOCK_MEDIA` | `false` | Block video/audio resources |++### Security & Authentication++| Variable | Default | Description |+|---|---|---|+| `BRIDGE_TOKEN` | Disabled | API authentication token (if set, all requests must include `Authorization: Bearer {token}`) |++### Debugging & Logging++| Variable | Default | Description |+|---|---|---|+| `BRIDGE_DEBUG` | `false` | Enable debug logging (verbose output) |+| `BRIDGE_LOG_LEVEL` | `info` | Log level: `debug`, `info`, `warn`, `error` |++### Dashboard++| Variable | Default | Description |+|---|---|---|+| `BRIDGE_DASHBOARD_PORT` | Same as `BRIDGE_PORT` | Dashboard HTTP port (usually same as API server) |+| `BRIDGE_NO_DASHBOARD` | `false` | Disable dashboard (API-only mode) |++---++## Usage Examples++### Basic Setup++```bash+# Default (headless, localhost:9867)+./pinchtab+```++### Custom Port++```bash+BRIDGE_PORT=9868 ./pinchtab+```++### Network Access (External)++```bash+# Allow connections from other machines+BRIDGE_BIND=0.0.0.0 BRIDGE_PORT=9867 ./pinchtab+```++**⚠️ Security Warning:** Only use `0.0.0.0` on trusted networks. Consider using `BRIDGE_TOKEN` for authentication.++### Headed Mode with Profile++```bash+BRIDGE_HEADLESS=false BRIDGE_PROFILE=work ./pinchtab+```++Opens visible Chrome window with "work" profile.++### Stealth Mode (Bypass Bot Detection)++```bash+BRIDGE_STEALTH=full ./pinchtab+```++Options:+- `light` — Basic patches (default, minimal overhead)+- `medium` — More aggressive patches (some overhead)+- `full` — Maximum stealth (significant overhead, slowest)++### Ad Blocking++```bash+BRIDGE_BLOCK_ADS=true ./pinchtab+```++Speeds up page loading by blocking ad domains.++### API Authentication++```bash+BRIDGE_TOKEN=my-secret-token ./pinchtab+```++Then all API requests must include:+```bash+curl -H "Authorization: Bearer my-secret-token" http://localhost:9867/health+```++### Multiple Settings++```bash+BRIDGE_PORT=9868 \+BRIDGE_HEADLESS=false \+BRIDGE_STEALTH=full \+BRIDGE_BLOCK_ADS=true \+BRIDGE_PROFILE=dev \+BRIDGE_TOKEN=secret \+./pinchtab+```++### Debug Mode++```bash+BRIDGE_DEBUG=true BRIDGE_LOG_LEVEL=debug ./pinchtab+```++Produces verbose logs for troubleshooting.++---++## Configuration Priority++If multiple sources set the same value:++1. **Command-line flags** (highest priority)+2. **Environment variables**+3. **Config file** (if supported)+4. **Built-in defaults** (lowest priority)++Example:+```bash+# BRIDGE_PORT=9868 from env, but --port flag overrides it+./pinchtab --port 9870 # Uses 9870+```++---++## Chrome Profile Directory Structure++Profiles are stored in `~/.pinchtab/profiles/{name}/`:++```text+~/.pinchtab/profiles/+├── work/+│ ├── Default/+│ │ ├── Preferences+│ │ ├── Cookies+│ │ ├── History+│ │ └── ... (other Chrome data)+│ └── ...+├── personal/+│ ├── Default/+│ │ └── ... (Chrome data)+│ └── ...+└── default/+ └── ... (default profile)+```++Each profile maintains its own:+- Cookies and session data+- Browsing history+- Saved passwords+- Local storage+- Cache++---++## Performance Tuning++### For Speed (Reduce Overhead)++```bash+# Minimal stealth, block ads+BRIDGE_STEALTH=light \+BRIDGE_BLOCK_ADS=true \+./pinchtab+```++### For Security (Detect Bypass)++```bash+# Maximum stealth+BRIDGE_STEALTH=full ./pinchtab+```++Note: Maximum stealth increases latency by 2-3x.++### For Bandwidth (Block Resources)++```bash+# Block ads, images, and media+BRIDGE_BLOCK_ADS=true \+BRIDGE_BLOCK_IMAGES=true \+BRIDGE_BLOCK_MEDIA=true \+./pinchtab+```++---++## Network Configuration++### Localhost Only (Default - Secure)++```bash+BRIDGE_BIND=127.0.0.1 ./pinchtab+```++Only accessible from the same machine.++### All Interfaces (Network Accessible)++```bash+BRIDGE_BIND=0.0.0.0 ./pinchtab+```++Accessible from any machine on the network. **Requires authentication:**++```bash+BRIDGE_BIND=0.0.0.0 BRIDGE_TOKEN=secret ./pinchtab+```++### Specific Interface++```bash+BRIDGE_BIND=192.168.1.100 ./pinchtab+```++Only accessible from that IP address.++---++## Troubleshooting++### Port Already in Use++```bash+# Find what's using the port+lsof -i :9867++# Use different port+BRIDGE_PORT=9868 ./pinchtab+```++### Chrome Not Found++```bash+# Specify custom binary path+CHROME_BINARY=/usr/bin/google-chrome ./pinchtab+```++### High Latency with Stealth Mode++```bash+# Reduce stealth level+BRIDGE_STEALTH=light ./pinchtab+```++Maximum stealth (`full`) adds significant overhead.++### Authentication Errors++```bash+# Check token format+BRIDGE_TOKEN=my-token ./pinchtab++# Request must include the token+curl -H "Authorization: Bearer my-token" http://localhost:9867/health+```++---++## Security Best Practices++1. **Use `BRIDGE_TOKEN` when exposing to network:**+ ```bash+ BRIDGE_BIND=0.0.0.0 BRIDGE_TOKEN=$(openssl rand -hex 32) ./pinchtab+ ```++2. **Use localhost by default:**+ ```bash+ # Good: only accessible locally+ BRIDGE_BIND=127.0.0.1 ./pinchtab+ ```++3. **Use SSH tunneling for remote access:**+ ```bash+ # Remote: start without binding to all interfaces+ ssh user@remote "BRIDGE_BIND=127.0.0.1 pinchtab"++ # Local: tunnel through SSH+ ssh -L 9867:127.0.0.1:9867 user@remote++ # Then use locally+ curl http://localhost:9867/health+ ```++4. **Use firewall rules if exposing to network:**+ ```bash+ # Only allow from specific IPs+ ufw allow from 192.168.1.0/24 to any port 9867+ ```++---++## Related Documentation++- [API Reference](endpoints.md) — HTTP endpoints+- [Getting Started](../get-started.md) — Quick setup+- [Core Concepts](../core-concepts.md) — Instances, profiles, tabsdiff --git a/docs/showcase.md b/docs/showcase.mdindex d41ecf43..d439f13d 100644--- a/docs/showcase.md+++ b/docs/showcase.md@@ -1,4 +1,4 @@-# PinchTab API Workflows: Getting Started+# API WorkflowsLearn the correct way to use PinchTab's API through practical, step-by-step examples.