PinchTab
Browser control for AI agents
12MB Go binary • HTTP API • Token-efficient

PinchTab is a standalone HTTP server that gives AI agents direct control over Chrome.

It has two runtime roles:

• pinchtab or pinchtab server — the full control-plane server
• pinchtab bridge — a single-instance bridge runtime

Most users only need the full server. It manages profiles, instances, routing, and the web dashboard. The bridge mode is the thin per-instance runtime used behind the scenes for managed child instances.

PinchTab is server-first:

• start pinchtab for the full control plane
• let the server manage profiles and instances
• let each managed instance run behind a lightweight pinchtab bridge runtime

In practice:

• Server is the public product entrypoint
• Bridge is the per-instance runtime for one browser
• Attach is the advanced path for registering an externally managed Chrome

The primary user journey is:

1. install Pinchtab
2. run pinchtab
3. point your agent or tool at http://localhost:9867
4. let Pinchtab act as your local browser service

That is the default “replace the browser runtime” scenario. Most users should not need to think about pinchtab bridge directly.

• CLI or Curl — Control via command-line or HTTP API
• Token-efficient — 800 tokens/page with text extraction (5-13x cheaper than screenshots)
• Headless or Headed — Run without a window or with visible Chrome
• 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

macOS / Linux:

curl -fsSL https://pinchtab.com/install.sh | bash

npm:

npm install -g pinchtab

Docker:

docker run -d \
  --name pinchtab \
  -p 127.0.0.1:9867:9867 \
  -v pinchtab-data:/data \
  --shm-size=2g \
  pinchtab/pinchtab

The bundled container persists its managed config at /data/.config/pinchtab/config.json. If you want to supply your own config file instead, mount it and point PINCHTAB_CONFIG at it:

docker run -d \
  --name pinchtab \
  -p 127.0.0.1:9867:9867 \
  -e PINCHTAB_CONFIG=/config/config.json \
  -v "$PWD/config.json:/config/config.json:ro" \
  -v pinchtab-data:/data \
  --shm-size=2g \
  pinchtab/pinchtab

Terminal 1 — Start the server:

pinchtab

Terminal 2 — Control the browser:

# Navigate
pinchtab nav https://pinchtab.com

# Get page structure
pinchtab snap -i -c

# Click an element
pinchtab click e5

# Extract text
pinchtab text

Or use the HTTP API directly:

# Create an instance (returns instance id)
INST=$(curl -s -X POST http://localhost:9867/instances/launch \
  -H "Content-Type: application/json" \
  -d '{"name":"work","mode":"headless"}' | jq -r '.id')

# Open a tab in that instance
TAB=$(curl -s -X POST http://localhost:9867/instances/$INST/tabs/open \
  -H "Content-Type: application/json" \
  -d '{"url":"https://pinchtab.com"}' | jq -r '.tabId')

# Get snapshot
curl "http://localhost:9867/tabs/$TAB/snapshot?filter=interactive"

# Click element
curl -X POST "http://localhost:9867/tabs/$TAB/action" \
  -H "Content-Type: application/json" \
  -d '{"kind":"click","ref":"e5"}'

Server — The main PinchTab process. It manages profiles, instances, routing, and the dashboard.

Instance — A running Chrome process. Each instance can have one profile.

Profile — Browser state (cookies, history, local storage). Log in once, stay logged in across restarts.

Tab — A single webpage. Each instance can have multiple tabs.

Bridge — The single-instance runtime behind a managed instance. Usually spawned by the server, not started manually.

Read more in the Core Concepts guide.

PinchTab defaults to a local-first posture:

• server.bind = 127.0.0.1
• sensitive endpoint families are off by default
• attach is off by default
• IDPI is enabled by default with a local-only website allowlist

Two controls are independent and both matter:

• the API token controls who can use the server
• the security feature gates control what the server is allowed to do

IDPI adds a browser-content defense layer by restricting allowed domains and protecting extracted content from indirect prompt injection.

See the full guide: docs/guides/security.md

Full docs at pinchtab.com/docs

An SMCP plugin in this repo lets AI agents control PinchTab via the Model Context Protocol (SMCP). One plugin exposes 15 tools (e.g. pinchtab__navigate, pinchtab__snapshot, pinchtab__action). No extra runtime deps (stdlib only). See plugins/README.md for setup (env vars and paths).

# Your AI agent can:
pinchtab nav https://pinchtab.com
pinchtab snap -i  # Get clickable elements
pinchtab click e5 # Click by ref
pinchtab fill e3 "user@pinchtab.com"  # Fill input
pinchtab press e7 Enter              # Submit form

# Extract text (token-efficient)
pinchtab nav https://pinchtab.com/article
pinchtab text  # ~800 tokens instead of 10,000

# Run multiple instances in parallel
curl -s -X POST http://localhost:9867/instances/start \
  -H "Content-Type: application/json" \
  -d '{"profileId":"alice","mode":"headless"}'

curl -s -X POST http://localhost:9867/instances/start \
  -H "Content-Type: application/json" \
  -d '{"profileId":"bob","mode":"headless"}'

# Each instance is isolated
curl http://localhost:9867/instances

Want to contribute? See DEVELOPMENT.md for setup instructions.

Quick start:

git clone https://github.com/pinchtab/pinchtab.git
cd pinchtab
./doctor.sh                 # Verifies environment, installs hooks/deps
go build ./cmd/pinchtab     # Build pinchtab binary

See CONTRIBUTING.md for contribution guidelines.

MIT — Free and open source.

Get started: pinchtab.com/docs