Skip to content

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.md
index 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 git
go version
```
-**Manual (any OS):**
-Download from https://golang.org/dl/ and follow instructions.
-
### Install Chrome/Chromium
**macOS (Homebrew):**
```bash
brew install chromium
-# Or use system Chrome
-which chromium # /usr/local/bin/chromium
```
**Linux (Ubuntu/Debian):**
```bash
sudo apt install -y chromium-browser
-which chromium-browser
```
**Linux (RHEL/CentOS):**
```bash
sudo yum install -y chromium
-which chromium
```
### Verify Installations
@@ -75,75 +68,25 @@ git --version # git version 2.39.0
chromium --version # Chromium 120.0.6099.xx
```
----
-
-## Part 2: Clone the Repository
+### Install Dependencies
-### Clone from GitHub
+Clone the repository and download Go modules:
```bash
git clone https://github.com/pinchtab/pinchtab.git
cd 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 directory
go 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=9867
auth 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)
```bash
BRIDGE_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):
```bash
nohup ./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:
```bash
curl 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 ./... -v
go 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 branch
git 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. Test
go test ./... -v
-```
-### 4. Run Checks
-
-```bash
-./scripts/check.sh
-```
-
-### 5. Commit Changes
+# 4. Format & lint
+gofmt -w .
+golangci-lint run ./...
-```bash
+# 5. Commit
git add .
-git commit -m "feat: description of change"
-```
-
-### 6. Push Branch
+git commit -m "feat: description"
-```bash
+# 6. Push
git 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
```bash
go build -o ~/go/bin/pinchtab ./cmd/pinchtab
@@ -591,7 +237,7 @@ pinchtab help
pinchtab --version
```
-### Install via npm (published releases)
+### Via npm (released builds)
```bash
npm 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.md
index 1a26378a..d2686cbf 100644
--- a/docs/architecture/pinchtab-architecture.md
+++ b/docs/architecture/pinchtab-architecture.md
@@ -1,9 +1,9 @@
-# Pinchtab Architecture
+# Architecture
## Overview
Pinchtab 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.md
index 7f22f733..7622b500 100644
--- a/docs/get-started.md
+++ b/docs/get-started.md
@@ -1,4 +1,4 @@
-# Getting Started with PinchTab
+# Getting Started
Get PinchTab running in 5 minutes, from zero to browser automation.
diff --git a/docs/guides/identifying-instances.md b/docs/guides/identifying-instances.md
index c9a1a2fa..d0efdd64 100644
--- a/docs/guides/identifying-instances.md
+++ b/docs/guides/identifying-instances.md
@@ -1,4 +1,4 @@
-# Identifying Pinchtab Chrome Instances
+# Chrome Instances
Running multiple Chrome instances? Here's how to tell Pinchtab's apart from your regular browser.
diff --git a/docs/index.json b/docs/index.json
index 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.md
new file mode 100644
index 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, tabs
diff --git a/docs/showcase.md b/docs/showcase.md
index d41ecf43..d439f13d 100644
--- a/docs/showcase.md
+++ b/docs/showcase.md
@@ -1,4 +1,4 @@
-# PinchTab API Workflows: Getting Started
+# API Workflows
Learn the correct way to use PinchTab's API through practical, step-by-step examples.