Skip to content

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

4.6 KB
Raw Blame

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.json as 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:

  1. start the server
  2. start an instance
  3. navigate
  4. 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

Getting help