Configuration

Configure PinchTab CLI with environment variables and config files

CLI Configuration

PinchTab can be configured using environment variables or a JSON configuration file.

Environment Variables

Server Connection

PINCHTAB_URL · string · default: "http://127.0.0.1:9867"

Server URL for CLI commands. Override to connect to a remote server.

export PINCHTAB_URL=http://192.168.1.100:9867
pinchtab snap

BRIDGE_PORT · string · default: "9867"

Server port. Used when starting the server and for CLI connections.

export BRIDGE_PORT=9868
pinchtab  # Starts on port 9868

BRIDGE_BIND · string · default: "127.0.0.1"

Bind address for the server.

export BRIDGE_BIND=0.0.0.0  # Listen on all interfaces
pinchtab

Authentication

PINCHTAB_TOKEN · string

Authentication token for CLI commands. Sent as Authorization: Bearer header.

export PINCHTAB_TOKEN=sk_your_secret_token
pinchtab snap

BRIDGE_TOKEN · string

Server-side authentication token. Clients must provide this token to access the API.

export BRIDGE_TOKEN=sk_server_secret
pinchtab  # Server requires this token from clients

Browser Configuration

BRIDGE_HEADLESS · boolean · default: "true"

Run Chrome in headless mode. Set to false or 0 to show the browser window.

export BRIDGE_HEADLESS=false
pinchtab

Accepted values: true, false, 1, 0, yes, no, on, off

CHROME_BIN · string

Path to Chrome/Chromium binary. Auto-detected if not set.

export CHROME_BIN=/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome
pinchtab

CHROME_FLAGS · string

Additional Chrome launch flags.

export CHROME_FLAGS="--disable-gpu --no-sandbox"
pinchtab

BRIDGE_CHROME_VERSION · string · default: "144.0.7559.133"

Chrome version to download if not found locally.

export BRIDGE_CHROME_VERSION=130.0.6723.58
pinchtab

State and Profiles

BRIDGE_STATE_DIR · string · default: "~/.pinchtab"

Directory for storing PinchTab state, profiles, and browser data.

export BRIDGE_STATE_DIR=/var/lib/pinchtab
pinchtab

BRIDGE_PROFILE · string · default: "~/.pinchtab/chrome-profile"

Chrome user data directory (profile).

export BRIDGE_PROFILE=/tmp/chrome-profile
pinchtab

BRIDGE_NO_RESTORE · boolean · default: "false"

Don’t restore tabs from previous session.

export BRIDGE_NO_RESTORE=true
pinchtab

Instance Management

INSTANCE_PORT_START · integer · default: "9868"

Starting port for managed instances.

export INSTANCE_PORT_START=10000
pinchtab

INSTANCE_PORT_END · integer · default: "9968"

Ending port for managed instances.

export INSTANCE_PORT_END=10100
pinchtab

Performance and Limits

BRIDGE_MAX_TABS · integer · default: "20"

Maximum number of tabs per instance.

export BRIDGE_MAX_TABS=50
pinchtab

BRIDGE_BLOCK_IMAGES · boolean · default: "false"

Block image loading by default (improves performance).

export BRIDGE_BLOCK_IMAGES=true
pinchtab

BRIDGE_BLOCK_MEDIA · boolean · default: "false"

Block video and audio loading.

export BRIDGE_BLOCK_MEDIA=true
pinchtab

BRIDGE_BLOCK_ADS · boolean · default: "false"

Block known ad domains.

export BRIDGE_BLOCK_ADS=true
pinchtab

BRIDGE_NO_ANIMATIONS · boolean · default: "false"

Disable CSS animations and transitions.

export BRIDGE_NO_ANIMATIONS=true
pinchtab

Stealth and Fingerprinting

BRIDGE_STEALTH · string · default: "light"

Stealth level for bot detection evasion. Options: light, medium, aggressive.

export BRIDGE_STEALTH=aggressive
pinchtab

BRIDGE_USER_AGENT · string

Custom user agent string.

export BRIDGE_USER_AGENT="Mozilla/5.0 (Windows NT 10.0; Win64; x64) Chrome/120.0.0.0"
pinchtab

BRIDGE_TIMEZONE · string

Override timezone for the browser.

export BRIDGE_TIMEZONE="America/New_York"
pinchtab

CDP Connection

CDP_URL · string

Connect to an existing Chrome DevTools Protocol endpoint instead of launching Chrome.

export CDP_URL=ws://localhost:9222/devtools/browser/abc123
pinchtab

BRIDGE_ONLY · string

Internal flag used by orchestrator to spawn bridge-only instances.

# DO NOT set manually - used internally
export BRIDGE_ONLY=1

Configuration File

Create a JSON configuration file at ~/.pinchtab/config.json:

Initialize Config

pinchtab config init

This creates ~/.pinchtab/config.json with defaults:

{
  "port": "9867",
  "instancePortStart": 9868,
  "instancePortEnd": 9968,
  "stateDir": "/home/user/.pinchtab",
  "profileDir": "/home/user/.pinchtab/chrome-profile",
  "headless": true,
  "noRestore": false,
  "timeoutSec": 15,
  "navigateSec": 30
}

Show Current Config

pinchtab config show

Output:

Current configuration:
  Port:       9867
  CDP URL:    
  Token:      (none)
  State Dir:  /home/user/.pinchtab
  Profile:    /home/user/.pinchtab/chrome-profile
  Headless:   true
  Max Tabs:   20
  No Restore: false
  Timeouts:   action=30s navigate=1m0s

Configuration File Schema

port · string · default: "9867"

Server port (overridden by BRIDGE_PORT)

instancePortStart · integer · default: "9868"

Starting port for instances (overridden by INSTANCE_PORT_START)

instancePortEnd · integer · default: "9968"

Ending port for instances (overridden by INSTANCE_PORT_END)

cdpUrl · string

Chrome DevTools Protocol endpoint (overridden by CDP_URL)

token · string

Authentication token (overridden by BRIDGE_TOKEN)

stateDir · string

State directory path (overridden by BRIDGE_STATE_DIR)

profileDir · string

Chrome profile directory (overridden by BRIDGE_PROFILE)

headless · boolean · default: "true"

Run headless (overridden by BRIDGE_HEADLESS)

noRestore · boolean · default: "false"

Don’t restore tabs (overridden by BRIDGE_NO_RESTORE)

maxTabs · integer · default: "20"

Maximum tabs per instance (overridden by BRIDGE_MAX_TABS)

timeoutSec · integer · default: "15"

Action timeout in seconds

navigateSec · integer · default: "30"

Navigation timeout in seconds

Configuration Priority

Settings are applied in this order (later overrides earlier):

1. Built-in defaults
2. Configuration file (~/.pinchtab/config.json)
3. Environment variables
4. Command-line flags (where applicable)

Example: Production Setup with Auth

~/.pinchtab/config.json

{
  "port": "9867",
  "token": "sk_prod_your_secret_token_here",
  "headless": true,
  "stateDir": "/var/lib/pinchtab",
  "profileDir": "/var/lib/pinchtab/chrome-profile",
  "maxTabs": 50,
  "timeoutSec": 30,
  "navigateSec": 60
}

Start the server:

pinchtab

CLI usage:

export PINCHTAB_TOKEN=sk_prod_your_secret_token_here
pinchtab snap

Example: Development Setup

# .env file
export BRIDGE_PORT=9867
export BRIDGE_HEADLESS=false
export BRIDGE_BLOCK_ADS=true
export BRIDGE_MAX_TABS=10

# Source and run
source .env
pinchtab

Custom Config Location

Override config file location:

export BRIDGE_CONFIG=/etc/pinchtab/config.json
pinchtab

Security Best Practices

Never commit tokens or secrets to version control. Use environment variables or secure config files with restricted permissions.

# Restrict config file permissions
chmod 600 ~/.pinchtab/config.json

# Use environment variables for tokens
export BRIDGE_TOKEN=$(cat /run/secrets/pinchtab-token)
pinchtab

Next Steps

Server Commands

Start and manage the PinchTab server

Instance Management

Launch and control browser instances