pinchtab

---

What is PinchTab?

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

For day-to-day local use, the server is typically installed as a user-level daemon, allowing agent tools to reuse the same browser control plane running in the background.

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

This installs the control-plane server and starts a default headless Chrome instance, ready to accept requests from agents or manual API calls.

PinchTab is designed first for local, single-user control on a machine you manage. Remote and distributed layouts are supported, but they are advanced operator-managed deployments. If you bind beyond loopback, publish ports, or attach remote bridges, you are responsible for tokens, network boundaries, TLS or reverse proxying, and which endpoint families you expose.

If you run PinchTab on a different machine, do it only when you understand the security model. Keep it on a private or otherwise closed network, avoid exposing it directly to the public internet, and keep high-risk endpoint families disabled unless you explicitly need them. If you do enable them, lock them down so only the systems that need them can reach them.

[!WARNING] The dashboard, HTTP API, MCP server, and remote CLI integrations are privileged operator control surfaces. They are not designed for untrusted users, multi-tenant exposure, or direct public-internet access. If you are unsure how to secure a non-local deployment, review docs/guides/security.md and use the private security contact path in SECURITY.md before exposing the service.

If you prefer not to run a daemon, or if you're on Windows, you can instead run:

pinchtab server — runs the control-plane server directly pinchtab bridge — runs a single browser instance as a lightweight runtime

Running bare pinchtab runs the security setup on first use, then prints server status, the security posture, and suggested next steps:

pinchtab

Security

PinchTab defaults to a local-first security posture:

• server.bind = 127.0.0.1
• dashboard session cookies are Secure only when the dashboard is actually served over HTTPS
• sensitive endpoint families are disabled by default
• attach is disabled by default
• IDPI is enabled with a local-only website allowlist

If you intentionally access the dashboard over plain HTTP on a non-loopback address, PinchTab now warns in the UI that the session is running without transport encryption. Prefer HTTPS or localhost when possible. If you force server.cookieSecure = true, dashboard login requires HTTPS and will fail explicitly on plain HTTP instead of looping silently.

[!CAUTION] By default, IDPI restricts browsing to locally hosted websites only. This prevents agents from navigating the public internet until you explicitly allow it. The restriction exists to make the security implications of browser automation clear before enabling wider access.

Expanding browsing to non-local or non-trusted websites is a security-reducing choice. Hostile pages can still increase browser attack surface and interact badly with enabled automation features even when PinchTab's content defenses are on.

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

Remote, container, and distributed setups are possible, but PinchTab is not positioned as a turnkey internet-facing browser service. Treat any non-local deployment as an advanced setup that you must secure explicitly.

What can you use it for

Headless navigation

With the daemon installed and an agent skill configured, an agent can execute tasks like:

"What are the main news about aliens on news.com?"

PinchTab exposes browser tools that allow agents to navigate pages, extract structured content, and interact with the DOM without wasting tokens on raw HTML or images.

Headed navigation

In addition to headless automation, PinchTab supports headed Chrome profiles.

You can create profiles configured with authentication, cookies, extensions, or specific environments. Each profile can have a name and description.

For example, an agent request like:

"Log into my work profile and download the weekly report"

can automatically select the appropriate profile and perform the action.

Site audits and visual comparison

PinchTab can audit whole sites at the browser level — screenshots, console errors, broken assets, accessibility score, Core Web Vitals, and security findings — and compare two site versions visually before a release:

pinchtab audit https://example.com --output-dir ./audit          # report.json + screenshots/
pinchtab audit https://example.com/sitemap.xml --sitemap --sample-size 2 --output-dir ./audit
pinchtab compare https://example.com https://staging.example.com --fail-on-diff   # CI gate

See docs/audit.md for the full command reference, report anatomy, and CI examples.

Local container isolation

If you prefer stronger isolation, PinchTab can run inside Docker.

This allows agents to control browsers in a sandboxed environment, reducing risk when running automation tasks locally.

Distributed automation

PinchTab can manage multiple Chrome instances (headless or headed) across containers or remote machines.

Typical use cases include:

• QA automation
• testing environments
• distributed browsing tasks
• development tooling

You can connect to multiple PinchTab servers, or attach to Chrome instances running in remote debug mode.

Process Model

PinchTab is server-first:

1. install the daemon or run pinchtab server for the full control plane
2. let the server manage profiles and instances
3. let each managed instance run behind a lightweight pinchtab bridge runtime

In practice:

• Server — the main product entry point and control plane
• Bridge — the runtime that manages a single browser instance
• Attach — an advanced mode for registering externally managed Chrome instances

Primary Usage

The primary user journey is:

1. install Pinchtab
2. install and start the daemon with pinchtab daemon install
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, and only need bare pinchtab for first-run setup or a status overview.

Agent plugins (binary still installed separately):

# Grok Build, after listing in the official xAI marketplace
grok plugin install pinchtab --trust

# OpenClaw
openclaw plugins install @pinchtab/pinchtab

Grok users can install from the PinchTab repository marketplace or directly from GitHub. See the Grok plugin install and usage guide.

Key Features

• 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 — single ~30MB binary; drives a locally installed Chrome or Chromium
• Accessibility-first — Element refs that denote a DOM node, not a row: the same e5 survives a change of filter, selector or depth (filtered views are sparse), and expires only on navigation to a new document
• ARM64-optimized — First-class Raspberry Pi support with automatic Chromium detection
• CloakBrowser support — Optional drop-in provider for sites that fingerprint stock Chromium. PinchTab launches a user-supplied CloakBrowser binary; no CloakBrowser is bundled in released artifacts. See docs/guides/cloakbrowser.md.

---

Quick Start

Installation

macOS / Linux:

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

Homebrew (macOS / Linux):

brew install pinchtab/tap/pinchtab

npm:

npm install -g pinchtab

Agent skill

The npm package ships the pinchtab agent skill and copies it into every agent home it detects (~/.claude/skills, ~/.cursor/skills, ~/.windsurf/skills, ~/.codex/skills, OpenClaw) on install and upgrade, printing what it wrote. The shipped copy carries the release version and a content hash in its frontmatter, so a stale or hand-edited copy is detectable without a source checkout:

pinchtab skill status           # each detected copy vs the bundled skill; exit 1 if any is stale
pinchtab skill update           # install or refresh; an edited copy is kept and reported
pinchtab skill update --force   # replace an edited copy

Inside a checkout, scripts/install-skills.sh symlinks the repo skills instead so edits are live; the sync never writes through a symlink.

Platform Support

PinchTab's primary tested operator workflow is local macOS and Linux.

Windows binaries are published, but Windows support is currently limited and best-effort because the project does not have the same level of automated and manual coverage there. On Windows, prefer running pinchtab server or pinchtab bridge directly instead of relying on the daemon workflow.

On macOS, prefer a dedicated automation browser (Google Chrome for Testing or Chromium) over your daily Google Chrome. Driving your primary Chrome headless can prevent it from opening a normal window while PinchTab is running. PinchTab now prefers a dedicated browser automatically, and pinchtab doctor browsers warns if automation would fall back to your primary Chrome — install Chrome for Testing or set browser.binary to a separate build. See docs/reference/config.md.

Shell Completion

Generate and install shell completions after pinchtab is on your PATH:

# 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

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: