docs/reference/config.md

Config

pinchtab config is the CLI entry point for creating, inspecting, validating, and editing PinchTab's config file.

Use this page as the command and schema reference. Broader deployment patterns can move to a separate guide later.

For security posture, token usage, sensitive endpoint policy, and IDPI guidance, see Security.

Commands

pinchtab config

Opens the interactive config overview/editor.

It currently exposes these high-signal settings directly:

• multiInstance.strategy
• multiInstance.allocationPolicy
• instanceDefaults.stealthLevel
• instanceDefaults.tabEvictionPolicy

It also shows:

• the active config file path
• the dashboard URL when the server is running
• the masked server token
• a Copy token action for clipboard/manual copy

pinchtab config

pinchtab config init

Creates a default config file at the standard user config location.

pinchtab config init

Current behavior note:

• config init writes to the default config path
• it does not currently switch to a custom PINCHTAB_CONFIG target path

pinchtab config show

Shows the effective runtime configuration after applying:

env vars -> config file -> built-in defaults

pinchtab config show

pinchtab config path

Prints the config file path PinchTab will read.

pinchtab config path

pinchtab config validate

Validates the current config file.

pinchtab config validate

pinchtab config get

Reads a single dotted-path value from the config file.

pinchtab config get server.port
pinchtab config get instanceDefaults.mode
pinchtab config get security.attach.allowHosts

pinchtab config set

Sets a single dotted-path value in the config file.

pinchtab config set server.port 8080
pinchtab config set instanceDefaults.mode headed
pinchtab config set multiInstance.strategy explicit

pinchtab config patch

Applies a JSON patch object to the config file.

pinchtab config patch '{"server":{"port":"8080"}}'
pinchtab config patch '{"instanceDefaults":{"mode":"headed","maxTabs":50}}'

Config Priority

PinchTab loads configuration in this order:

1. environment variables
2. config file
3. built-in defaults

The supported env vars are:

• PINCHTAB_CONFIG — path to config file
• PINCHTAB_TOKEN — auth token (overrides config file)

Everything else is configured in config.json. For CLI targeting a remote server, use the --server flag.

For the common local workflow, prefer the interactive pinchtab config screen for everyday changes and use get, set, or patch when you need an exact scripted edit.

Config File Location

Default location by OS:

• macOS: ~/Library/Application Support/pinchtab/config.json
• Linux: ~/.config/pinchtab/config.json (respects $XDG_CONFIG_HOME if set)
• Windows: %APPDATA%\pinchtab\config.json

Legacy fallback:

• if ~/.pinchtab/config.json exists and the newer location does not, PinchTab still uses the legacy location

Override the read path with:

export PINCHTAB_CONFIG=/path/to/config.json

Config Shape

Current nested config shape:

{
  "server": {
    "port": "9867",
    "bind": "127.0.0.1",
    "token": "your-secret-token",
    "stateDir": "/path/to/state"
  },
  "browser": {
    "version": "144.0.7559.133",
    "binary": "/path/to/chrome",
    "extraFlags": "",
    "extensionPaths": []
  },
  "instanceDefaults": {
    "mode": "headless",
    "maxTabs": 20,
    "maxParallelTabs": 0,
    "stealthLevel": "light",
    "tabEvictionPolicy": "close_lru",
    "blockAds": false,
    "blockImages": false,
    "blockMedia": false,
    "noRestore": false,
    "noAnimations": false
  },
  "security": {
    "allowEvaluate": false,
    "allowMacro": false,
    "allowScreencast": false,
    "allowDownload": false,
    "allowUpload": false,
    "attach": {
      "enabled": false,
      "allowHosts": ["127.0.0.1", "localhost", "::1"],
      "allowSchemes": ["ws", "wss"]
    },
    "idpi": {
      "enabled": true,
      "allowedDomains": ["127.0.0.1", "localhost", "::1"],
      "strictMode": true,
      "scanContent": true,
      "wrapContent": true,
      "customPatterns": []
    }
  },
  "profiles": {
    "baseDir": "/path/to/profiles",
    "defaultProfile": "default"
  },
  "multiInstance": {
    "strategy": "always-on",
    "allocationPolicy": "fcfs",
    "instancePortStart": 9868,
    "instancePortEnd": 9968,
    "restart": {
      "maxRestarts": 20,
      "initBackoffSec": 2,
      "maxBackoffSec": 60,
      "stableAfterSec": 300
    }
  },
  "timeouts": {
    "actionSec": 30,
    "navigateSec": 60,
    "shutdownSec": 10,
    "waitNavMs": 1000
  },
  "scheduler": {
    "enabled": false,
    "strategy": "fair-fifo",
    "maxQueueSize": 1000,
    "maxPerAgent": 100,
    "maxInflight": 20,
    "maxPerAgentInflight": 10,
    "resultTTLSec": 300,
    "workerCount": 4
  }
}

Sections

Section	Purpose
server	HTTP server settings
browser	Chrome executable and launch wiring
instanceDefaults	Default behavior for managed instances
security	Sensitive feature gates, attach policy, and IDPI
profiles	Profile storage defaults
multiInstance	Strategy, allocation, instance port range, and restart policy
timeouts	Runtime timeouts
scheduler	Optional task queue (see Scheduler)

Common Examples

Headed Mode

{
  "instanceDefaults": {
    "mode": "headed"
  }
}

Network Bind With Token

pinchtab config set server.bind 0.0.0.0
pinchtab config set server.token secret
pinchtab

Custom Instance Port Range

{
  "server": {
    "port": "8080"
  },
  "multiInstance": {
    "instancePortStart": 8100,
    "instancePortEnd": 8200
  }
}

Tab Eviction Policy

{
  "instanceDefaults": {
    "maxTabs": 10,
    "tabEvictionPolicy": "close_lru"
  }
}

Attach Policy

{
  "security": {
    "attach": {
      "enabled": true,
      "allowHosts": ["127.0.0.1", "localhost", "chrome.internal"],
      "allowSchemes": ["ws", "wss"]
    }
  }
}

IDPI Policy

{
  "security": {
    "idpi": {
      "enabled": true,
      "allowedDomains": ["example.com", "*.example.com"],
      "strictMode": true,
      "scanContent": true,
      "wrapContent": true,
      "customPatterns": []
    }
  }
}

This is policy only. The actual cdpUrl is provided in the attach request, not in global config.

Legacy Flat Format

Older flat config is still accepted for backward compatibility:

{
  "port": "9867",
  "headless": true,
  "maxTabs": 20,
  "allowEvaluate": false,
  "timeoutSec": 30,
  "navigateSec": 60
}

Use pinchtab config init to create a nested config file.

Validation

pinchtab config validate currently checks, among other things:

• valid server port values
• valid instanceDefaults.mode
• valid instanceDefaults.stealthLevel
• valid instanceDefaults.tabEvictionPolicy
• instanceDefaults.maxTabs >= 1
• instanceDefaults.maxParallelTabs >= 0
• valid multiInstance.strategy
• valid multiInstance.allocationPolicy
• valid multiInstance.restart.* values
• valid security.attach.allowSchemes
• multiInstance.instancePortStart <= multiInstance.instancePortEnd
• multiInstance.restart.initBackoffSec <= multiInstance.restart.maxBackoffSec
• non-negative timeout values

Valid enum values:

Field	Values
instanceDefaults.mode	headless, headed
instanceDefaults.stealthLevel	light, full
instanceDefaults.tabEvictionPolicy	reject, close_oldest, close_lru (default)
multiInstance.strategy	simple, explicit, simple-autorestart, always-on (default)
multiInstance.allocationPolicy	fcfs, round_robin, random
security.attach.allowSchemes	ws, wss, http, https

Notes

• config show reports effective runtime values, not just raw file contents.
• config get, set, and patch operate on the file config model, not on transient env overrides.
• Most operational behavior now belongs in config.json, not in startup env vars.