Configuration

Complete reference for all PinchTab environment variables and configuration options.

Environment Variables

Port & Network

Browser & Chrome

Stealth & Detection

Content Filtering

Security & Authentication

Debugging & Logging

Dashboard

Usage Examples

Basic Setup

# Default (headless, localhost:9867)./pinchtab

Custom Port

BRIDGE_PORT=9868 ./pinchtab

Network Access (External)

# Allow connections from other machinesBRIDGE_BIND=0.0.0.0 BRIDGE_PORT=9867 ./pinchtab

⚠️ Security Warning: Only use 0.0.0.0 on trusted networks. Consider using BRIDGE_TOKEN for authentication.

Headed Mode with Profile

BRIDGE_HEADLESS=false BRIDGE_PROFILE=work ./pinchtab

Opens visible Chrome window with “work” profile.

Stealth Mode (Bypass Bot Detection)

BRIDGE_STEALTH=full ./pinchtab

Options:

• light — Basic patches (default, minimal overhead)
• medium — More aggressive patches (some overhead)
• full — Maximum stealth (significant overhead, slowest)

Ad Blocking

BRIDGE_BLOCK_ADS=true ./pinchtab

Speeds up page loading by blocking ad domains.

API Authentication

BRIDGE_TOKEN=my-secret-token ./pinchtab

Then all API requests must include:

curl -H "Authorization: Bearer my-secret-token" http://localhost:9867/health

Multiple Settings

BRIDGE_PORT=9868 \BRIDGE_HEADLESS=false \BRIDGE_STEALTH=full \BRIDGE_BLOCK_ADS=true \BRIDGE_PROFILE=dev \BRIDGE_TOKEN=secret \./pinchtab

Debug Mode

BRIDGE_DEBUG=true BRIDGE_LOG_LEVEL=debug ./pinchtab

Produces verbose logs for troubleshooting.

Configuration Priority

If multiple sources set the same value:

1. Command-line flags (highest priority)
2. Environment variables
3. Config file (if supported)
4. Built-in defaults (lowest priority)

Example:

# BRIDGE_PORT=9868 from env, but --port flag overrides it./pinchtab --port 9870  # Uses 9870

Chrome Profile Directory Structure

Profiles are stored in ~/.pinchtab/profiles/{id}/:

~/.pinchtab/profiles/├── prof_9f86d081/│   ├── Default/│   │   ├── Preferences│   │   ├── Cookies│   │   ├── History│   │   └── ... (other Chrome data)│   └── ...├── prof_dc34vewr/│   ├── Default/│   │   └── ... (Chrome data)│   └── ...└── prof_34ff6ks9/    └── ... (default profile)

Each profile maintains its own:

• Cookies and session data
• Browsing history
• Saved passwords
• Local storage
• Cache

Performance Tuning

For Speed (Reduce Overhead)

# Minimal stealth, block adsBRIDGE_STEALTH=light \BRIDGE_BLOCK_ADS=true \./pinchtab

For Security (Detect Bypass)

# Maximum stealthBRIDGE_STEALTH=full ./pinchtab

Note: Maximum stealth increases latency by 2-3x.

For Bandwidth (Block Resources)

# Block ads, images, and mediaBRIDGE_BLOCK_ADS=true \BRIDGE_BLOCK_IMAGES=true \BRIDGE_BLOCK_MEDIA=true \./pinchtab

Network Configuration

Localhost Only (Default - Secure)

BRIDGE_BIND=127.0.0.1 ./pinchtab

Only accessible from the same machine.

All Interfaces (Network Accessible)

BRIDGE_BIND=0.0.0.0 ./pinchtab

Accessible from any machine on the network. Requires authentication:

BRIDGE_BIND=0.0.0.0 BRIDGE_TOKEN=secret ./pinchtab

Specific Interface

BRIDGE_BIND=192.168.1.100 ./pinchtab

Only accessible from that IP address.

Troubleshooting

Port Already in Use

# Find what's using the portlsof -i :9867# Use different portBRIDGE_PORT=9868 ./pinchtab

Chrome Not Found

# Specify custom binary pathCHROME_BINARY=/usr/bin/google-chrome ./pinchtab

High Latency with Stealth Mode

# Reduce stealth levelBRIDGE_STEALTH=light ./pinchtab

Maximum stealth (full) adds significant overhead.

Authentication Errors

# Check token formatBRIDGE_TOKEN=my-token ./pinchtab# Request must include the tokencurl -H "Authorization: Bearer my-token" http://localhost:9867/health

Security Best Practices

1. Use BRIDGE_TOKEN when exposing to network:

   bash terminal

   BRIDGE_BIND=0.0.0.0 BRIDGE_TOKEN=$(openssl rand -hex 32) ./pinchtab

2. Use localhost by default:

   bash terminal

   # Good: only accessible locallyBRIDGE_BIND=127.0.0.1 ./pinchtab

3. Use SSH tunneling for remote access:

   bash terminal

   # Remote: start without binding to all interfacesssh user@remote "BRIDGE_BIND=127.0.0.1 pinchtab"# Local: tunnel through SSHssh -L 9867:127.0.0.1:9867 user@remote# Then use locallycurl http://localhost:9867/health

4. Use firewall rules if exposing to network:

   bash terminal

   # Only allow from specific IPsufw allow from 192.168.1.0/24 to any port 9867

Related Documentation

• API Reference — HTTP endpoints
• Getting Started — Quick setup
• Core Concepts — Instances, profiles, tabs