High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.
Getting Started
Get PinchTab running in a few minutes, from zero to browser automation.
This guide covers the default local setup. If you plan to publish ports beyond localhost, bind to non-loopback interfaces, or run a remote or distributed topology, treat that as an advanced deployment and read the Security guide first.
Installation
Option 1: one-liner
macOS / Linux
curl -fsSL https://pinchtab.com/install.sh | bash
Then verify:
pinchtab --version
Option 2: npm
Requires: Node.js 18+
npm install -g pinchtab
pinchtab --version
Option 3: Docker
Requires: Docker
docker run -d --name pinchtab -p 127.0.0.1:9867:9867 pinchtab/pinchtab
docker exec pinchtab pinchtab health
Option 4: build from source
Requires: Go 1.26+, Git, Chrome/Chromium
git clone https://github.com/pinchtab/pinchtab.git
cd pinchtab
./dev doctor
go build -o pinchtab ./cmd/pinchtab
./pinchtab --version
Full build & contribution guide ->
macOS upgrade note: current PinchTab uses
~/.pinchtab/config.jsonas the default config path. If you still have an older config at~/Library/Application Support/pinchtab/config.json, move or merge it into~/.pinchtab/config.json.
Platform Support
PinchTab's primary tested workflow is local macOS and Linux.
Windows binaries are available, but Windows support is currently limited and best-effort because the project does not have the same level of test coverage there. On Windows, prefer direct runs with pinchtab server instead of expecting the full daemon workflow.
Shell Completion
After installation, you can generate shell completions from the CLI:
# Generate and install zsh completions
pinchtab completion zsh > "${fpath[1]}/_pinchtab"
# Generate bash completions
pinchtab completion bash > /etc/bash_completion.d/pinchtab
# Generate fish completions
pinchtab completion fish > ~/.config/fish/completions/pinchtab.fish
Quick start
The normal flow is:
- start the server
- start an instance
- navigate
- inspect or act
Step 1: start the server
pinchtab server
# Response (log lines)
time=... level=INFO msg=orchestration strategy=always-on allocation=fcfs
time=... level=INFO msg="dashboard started" port=9867
The server runs on http://127.0.0.1:9867.
You can open the dashboard at http://127.0.0.1:9867 or http://127.0.0.1:9867/dashboard.
The HTTP API requires the server token (server.token, generated on first run). Export it once for the curl examples below:
export PINCHTAB_TOKEN=$(pinchtab config token --stdout)
Step 2: start your first instance
curl -s -X POST http://127.0.0.1:9867/instances/start \
-H "Authorization: Bearer $PINCHTAB_TOKEN" \
-H "Content-Type: application/json" \
-d '{"mode":"headless"}' | jq .
# CLI Alternative
pinchtab instance start
# Response
{
"id": "inst_0a89a5bb",
"profileId": "prof_278be873",
"profileName": "instance-1741400000000000000-9f3c2a1b",
"port": "9868",
"mode": "headless",
"headless": true,
"status": "starting"
}
Step 3: navigate
curl -s -X POST http://127.0.0.1:9867/navigate \
-H "Authorization: Bearer $PINCHTAB_TOKEN" \
-H "Content-Type: application/json" \
-d '{"url":"https://github.com/pinchtab/pinchtab"}' | jq .
# CLI Alternative
pinchtab nav https://github.com/pinchtab/pinchtab
# Response
{
"tabId": "CDP_TARGET_ID",
"title": "GitHub - pinchtab/pinchtab",
"url": "https://github.com/pinchtab/pinchtab"
}
Step 4: inspect the page
curl -s -H "Authorization: Bearer $PINCHTAB_TOKEN" "http://127.0.0.1:9867/snapshot?filter=interactive" | jq .
# CLI Alternative
pinchtab snap -i -c
# Response
{
"nodes": [
{ "ref": "e0", "role": "link", "name": "Skip to content" },
{ "ref": "e14", "role": "button", "name": "Search or jump to…" }
]
}
You now have a working PinchTab server, a running browser instance, and a navigated tab.
Troubleshooting
Connection refused
pinchtab health
If that fails, start the server:
pinchtab server
Port already in use
pinchtab config set server.port 9868
pinchtab server
Chrome not found
# macOS
brew install chromium
# Linux (Ubuntu/Debian)
sudo apt install chromium-browser
# Custom Chrome binary (set in config)
pinchtab config set browser.binary /path/to/chrome