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.

Commands

pinchtab config init

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

pinchtab config init

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 show

pinchtab config path

Prints the config file path PinchTab will read.

pinchtab config path

pinchtab config path

pinchtab config validate

Validates the current config file.

pinchtab config validate

pinchtab config validate

pinchtab config get

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

pinchtab config get server.portpinchtab config get instanceDefaults.modepinchtab config get attach.allowHosts

pinchtab config get server.portpinchtab config get instanceDefaults.modepinchtab config get attach.allowHosts

pinchtab config set

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

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

pinchtab config set server.port 8080pinchtab config set instanceDefaults.mode headedpinchtab 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}}'

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 currently supported operational env vars are:

• PINCHTAB_CONFIG
• PINCHTAB_BIND
• PINCHTAB_PORT
• PINCHTAB_TOKEN
• CHROME_BIN

Everything else should be configured in config.json.

Config File Location

Default location by OS:

• macOS: ~/Library/Application Support/pinchtab/config.json
• Linux: ~/.config/pinchtab/config.json or $XDG_CONFIG_HOME/pinchtab/config.json
• 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

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": "reject",
    "blockAds": false,
    "blockImages": false,
    "blockMedia": false,
    "noRestore": false,
    "noAnimations": false
  },
  "security": {
    "allowEvaluate": false,
    "allowMacro": false,
    "allowScreencast": false,
    "allowDownload": false,
    "allowUpload": false
  },
  "profiles": {
    "baseDir": "/path/to/profiles",
    "defaultProfile": "default"
  },
  "multiInstance": {
    "strategy": "simple",
    "allocationPolicy": "fcfs",
    "instancePortStart": 9868,
    "instancePortEnd": 9968
  },
  "attach": {
    "enabled": false,
    "allowHosts": ["127.0.0.1", "localhost", "::1"],
    "allowSchemes": ["ws", "wss"]
  },
  "timeouts": {
    "actionSec": 30,
    "navigateSec": 60,
    "shutdownSec": 10,
    "waitNavMs": 1000
  }
}

Sections

Common Examples

Headed Mode

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

Network Bind With Token

PINCHTAB_BIND=0.0.0.0 PINCHTAB_TOKEN=secret pinchtab

PINCHTAB_BIND=0.0.0.0 PINCHTAB_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

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

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 attach.allowSchemes
• multiInstance.instancePortStart <= multiInstance.instancePortEnd
• non-negative timeout values

Valid enum values:

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.