Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/pinchtab/pinchtab/llms.txt

Use this file to discover all available pages before exploring further.

​
Server Command

The default pinchtab command starts the dashboard server, which manages browser instances and provides the HTTP/WebSocket API.

​
Start Server

pinchtab
Output: 
time=2024-03-15T10:30:00.000Z level=INFO msg="🦀 PinchTab" port=9867
time=2024-03-15T10:30:00.500Z level=INFO msg="dashboard ready" url=http://localhost:9867
The server:
  • Listens on http://127.0.0.1:9867 by default
  • Serves the dashboard UI at /dashboard
  • Exposes HTTP and WebSocket APIs
  • Manages browser instance lifecycle
  • Orchestrates profile-based instances

​
Server Modes

​
Dashboard Mode (Default)

Runs the orchestrator/dashboard without launching Chrome: 
pinchtab
Features:
  • Web dashboard at http://localhost:9867/dashboard
  • Instance management
  • Profile management
  • API endpoints for CLI commands
  • No Chrome process until instance is launched

​
Bridge-Only Mode

Bridge-only mode is used internally by the orchestrator. You typically don’t run this manually.
Launches a Chrome instance with bridge API: 
export BRIDGE_ONLY=1
pinchtab
This mode:
  • Launches Chrome immediately
  • Provides direct browser control
  • No dashboard UI
  • Used for managed instances

​
Configuration Options

​
Port Configuration

# Change server port
export BRIDGE_PORT=9868
pinchtab

# Listen on all interfaces (not just localhost)
export BRIDGE_BIND=0.0.0.0
pinchtab

​
Headless vs Headed

# Headless (default)
export BRIDGE_HEADLESS=true
pinchtab

# Headed (show browser window)
export BRIDGE_HEADLESS=false
pinchtab

​
Authentication

# Require authentication token
export BRIDGE_TOKEN=sk_your_secret_token
pinchtab
Clients must then provide the token: 
export PINCHTAB_TOKEN=sk_your_secret_token
pinchtab nav https://example.com

​
State Directory

# Custom state directory
export BRIDGE_STATE_DIR=/var/lib/pinchtab
pinchtab
The state directory contains:
  • profiles/ - Browser profiles (user data)
  • chrome-profile/ - Default Chrome user data
  • config.json - Configuration file

​
Auto-Launch Instances

​
PINCHTAB_AUTO_LAUNCH
boolean
default:"false"
Automatically launch a browser instance on startup.
export PINCHTAB_AUTO_LAUNCH=true
pinchtab
​
PINCHTAB_DEFAULT_PROFILE
string
default:"default"
Profile to auto-launch.
export PINCHTAB_AUTO_LAUNCH=true
export PINCHTAB_DEFAULT_PROFILE=my-profile
pinchtab
​
PINCHTAB_DEFAULT_PORT
string
Port for auto-launched instance.
export PINCHTAB_AUTO_LAUNCH=true
export PINCHTAB_DEFAULT_PORT=9868
pinchtab
​
PINCHTAB_HEADED
string
Launch headed instance (show browser window).
export PINCHTAB_AUTO_LAUNCH=true
export PINCHTAB_HEADED=1
pinchtab
Example with auto-launch: 
export PINCHTAB_AUTO_LAUNCH=true
export PINCHTAB_HEADED=1
pinchtab
Output: 
time=2024-03-15T10:30:00.000Z level=INFO msg="🦀 PinchTab" port=9867
time=2024-03-15T10:30:00.500Z level=INFO msg="dashboard ready" url=http://localhost:9867
time=2024-03-15T10:30:01.000Z level=INFO msg="auto-launched instance" profile=default id=inst_abc123 port=9868 headless=false

​
Background vs Foreground

pinchtab
Logs appear in terminal. Press Ctrl+C to stop.

​
Background

pinchtab &
echo $! > /tmp/pinchtab.pid
Stop the server: 
kill $(cat /tmp/pinchtab.pid)
Or use nohup: 
nohup pinchtab > /var/log/pinchtab.log 2>&1 &

​
Using systemd (Linux)

Create /etc/systemd/system/pinchtab.service: 
[Unit]
Description=PinchTab Browser Automation
After=network.target

[Service]
Type=simple
User=pinchtab
WorkingDirectory=/home/pinchtab
ExecStart=/usr/local/bin/pinchtab
Restart=on-failure
RestartSec=5s

Environment="BRIDGE_PORT=9867"
Environment="BRIDGE_STATE_DIR=/var/lib/pinchtab"
Environment="BRIDGE_TOKEN=sk_your_secret_token"
Environment="BRIDGE_HEADLESS=true"

[Install]
WantedBy=multi-user.target
Enable and start: 
sudo systemctl enable pinchtab
sudo systemctl start pinchtab
sudo systemctl status pinchtab
View logs: 
sudo journalctl -u pinchtab -f

​
Health Check

pinchtab health
Output: 
{
  "status": "ok",
  "mode": "dashboard"
}
Or use curl: 
curl http://localhost:9867/health

{
  "status": "ok",
  "mode": "dashboard"
}

​
Shutdown Server

​
Graceful Shutdown

Press Ctrl+C in the terminal running the server: 
^C
time=2024-03-15T10:35:00.000Z level=INFO msg="shutting down dashboard..."
Or via API: 
curl -X POST http://localhost:9867/shutdown

​
Force Shutdown

Press Ctrl+C twice to force shutdown: 
^C
time=2024-03-15T10:35:00.000Z level=INFO msg="shutting down dashboard..."
^C
time=2024-03-15T10:35:01.000Z level=WARN msg="force shutdown requested"

​
Monitoring

The server logs health information every 30 seconds: 
time=2024-03-15T10:30:30.000Z level=INFO msg="health check" instances=2 headed=1 headless=1 total_tabs=5

​
Metrics Endpoint

curl http://localhost:9867/metrics

{
  "metrics": {
    "snapshots": 42,
    "navigations": 15,
    "actions": 128
  }
}

​
Common Issues

​
Port Already in Use

listen tcp 127.0.0.1:9867: bind: address already in use
Solution: 
# Find process using port
lsof -i :9867

# Kill it
kill -9 <PID>

# Or use different port
export BRIDGE_PORT=9868
pinchtab

​
Chrome Not Found

chrome binary not found
Solution: 
# Specify Chrome path
export CHROME_BIN=/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome
pinchtab

# Or let PinchTab download Chrome
# (downloads to ~/.pinchtab/chrome-<version>)
pinchtab

​
Permission Denied (State Directory)

cannot create profiles dir: permission denied
Solution: 
# Create directory with correct permissions
mkdir -p ~/.pinchtab
chmod 755 ~/.pinchtab

# Or use custom directory
export BRIDGE_STATE_DIR=/tmp/pinchtab
pinchtab

​
Production Deployment

In production, always:
  • Set BRIDGE_TOKEN for authentication
  • Use BRIDGE_HEADLESS=true
  • Configure proper state directory
  • Set up process monitoring (systemd/supervisor)
  • Enable firewall rules
Example production configuration: 
export BRIDGE_PORT=9867
export BRIDGE_BIND=0.0.0.0
export BRIDGE_TOKEN=sk_prod_$(openssl rand -hex 32)
export BRIDGE_HEADLESS=true
export BRIDGE_STATE_DIR=/var/lib/pinchtab
export BRIDGE_MAX_TABS=50
export BRIDGE_BLOCK_ADS=true
export PINCHTAB_AUTO_LAUNCH=true

pinchtab

​
Next Steps

Instance Management

Launch and control browser instances

Profile Management

Manage browser profiles

Navigation

Navigate to URLs

Configuration

Environment variables and config files