Skip to content
Get packs

Guide · Open source

How to use PinchTab: install, run and control Chrome

Updated · written with AI from the project's own documentation and checked against our catalogue data

PinchTab is a standalone HTTP server that gives AI agents direct control over Chrome. It is aimed at developers, testers and hobbyists who want one local browser control point that agent tools can share. This guide shows you how to install it, start the daemon, point a tool at it and know which setups to avoid.

PinchTabpinchtab/pinchtab · ★ 10.5k · MIT

Quick start

  1. 1Check prerequisites. Make sure Chrome or Chromium is installed locally on the machine you will use.
  2. 2Install the server. Run the macOS/Linux installer script from the README to install the control-plane server.
  3. 3Start the daemon. Run pinchtab daemon install to install and start the daemon with a default headless Chrome instance.
  4. 4Check status. Run bare pinchtab to complete first-run security setup and see server status and suggested next steps.
  5. 5Point your tool at the server. Send requests to http://localhost:9867 from your agent or from curl.
  6. 6Review security settings. Before any non-local use, read the security guide and keep dashboard, API and MCP access restricted.

Check the prerequisites

PinchTab drives a Chrome or Chromium browser that is already installed on your machine, so install one first. The source describes PinchTab as a small Go binary that is typically run as a background daemon on a machine you manage.

  • A locally installed Chrome or Chromium
  • A machine you control, ideally one used by a single user
  • On Windows, the source suggests using `pinchtab server` or `pinchtab bridge` instead of the daemon

Install PinchTab on macOS or Linux

The README gives an installer script for macOS and Linux. It installs the control-plane server. Run it in a terminal:

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

Install and start the daemon

For day-to-day local use, install the server as a user-level daemon. This also starts a default headless Chrome instance that is ready to accept requests from agents or manual API calls.

  • Run `pinchtab daemon install`
  • The primary endpoint in the README is http://localhost:9867
pinchtab daemon install

Run the first-time setup and check status

Running bare `pinchtab` on first use runs the security setup, then prints server status, the security posture and suggested next steps. Use it as your overview check.

pinchtab

Other ways to run it

If you would rather not run a daemon, or you are on Windows, you can run the server directly or run a single browser instance. The README describes `pinchtab bridge` as the runtime that manages a single browser instance, and most users do not need to use it directly.

  • `pinchtab server` runs the control-plane server directly
  • `pinchtab bridge` runs a single browser instance as a lightweight runtime
  • `pinchtab attach` is an advanced mode for registering externally managed Chrome instances

Keep it local and secure

PinchTab defaults to a local-first security posture. It binds to 127.0.0.1, keeps sensitive endpoint families disabled, and restricts browsing to locally hosted websites by default. The README is clear that the dashboard, HTTP API and MCP server are privileged control surfaces, not designed for untrusted users or direct public exposure.

If you run it on another machine, keep it on a private or closed network, avoid exposing it to the public internet, and read docs/guides/security.md first.

  • Default bind address: 127.0.0.1
  • IDPI is enabled with a local-only website allowlist by default
  • Expanding browsing to public websites is a security-reducing choice

Use it for audits and comparisons

The README also documents site audit and visual comparison commands. They report on screenshots, console errors, broken assets, accessibility score, Core Web Vitals and security findings. The full command reference is in docs/audit.md.

  • `pinchtab audit` writes a report.json and screenshots to an output folder
  • `pinchtab compare` can fail a CI run when two site versions differ
pinchtab compare https://example.com https://staging.example.com --fail-on-diff

What people use it for

  • Letting an AI agent navigate a page and extract its text content with fewer tokens than screenshots
  • Running a headed Chrome profile that holds your own logins and cookies for a task you approve
  • Running several isolated Chrome instances for QA or testing work
  • Auditing a site's screenshots, console errors and Core Web Vitals from the command line
  • Running a local browser service on a Raspberry Pi or other ARM64 machine

Frequently asked questions

Is PinchTab free and open source?

Yes. The repository is licensed under the MIT licence, and the source is written in Go. Check the LICENSE file in the repository for the full terms.

What do I need before installing PinchTab?

You need a locally installed Chrome or Chromium. The README says PinchTab drives that browser rather than bundling one, and it is a small Go binary.

Can I run PinchTab on Windows?

The source says that if you prefer not to run a daemon or are on Windows, you can run pinchtab server or pinchtab bridge directly. The documented install script is for macOS and Linux.

Can I use PinchTab as a hosted browser service?

No. The README says PinchTab is not positioned as a turnkey internet-facing browser service, and the dashboard and API are privileged control surfaces not meant for public exposure.

How is PinchTab different from Playwright or Puppeteer?

PinchTab runs as a standalone HTTP server that agents call, while Playwright and Puppeteer are script libraries you call from your own code. Browserless is a hosted-style alternative. Compare them by whether you need a running server or a library.

Does PinchTab work on a Raspberry Pi?

The README lists ARM64 support, with first-class Raspberry Pi support and automatic Chromium detection. It is listed as a good fit for those machines.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

PinchTab suits developers building AI agents, and testers running several isolated Chrome instances, on a machine they control. It is not the right choice if you need a public, multi-tenant or hosted browser service, or if you only want a script library instead of a running server.

Install options & downloads