Skip to content

High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.

7.0 KB
Raw Blame

Data Storage Guide

PinchTab stores configuration, profiles, session state, and usage logs on local disk. This guide describes what is stored, where it lives by default, and which paths you can change.

What PinchTab Stores

Path Purpose How To Change It
config.json Main PinchTab configuration PINCHTAB_CONFIG selects the file
profiles/<profile>/ Chrome user data for each profile profiles.baseDir
sessions.json Saved tab/session state for a bridge instance server.stateDir
activity/events-YYYY-MM-DD.jsonl Primary daily request/activity log for /api/activity, CLI activity, and dashboard activity views server.stateDir, observability.activity.retentionDays
activity/events-<source>-YYYY-MM-DD.jsonl Source-specific daily activity log for named sources such as dashboard or orchestrator server.stateDir, observability.activity.retentionDays
<profile>/.pinchtab-state/config.json Child instance config written by the orchestrator generated automatically for managed instances
server.log Output of a server started with pinchtab server --background server.stateDir
heapsnapshots/<id>.heapsnapshot V8 heap snapshots from POST /memory/snapshot server.stateDir
logs/daemon.out.log, logs/daemon.err.log Output of the background service (pinchtab daemon), always under ~/.pinchtab/logs/ not configurable

CLI State

The command line keeps its own per-user scratch state outside the server's stateDir: the current-tab file per server (current-tab-<host>-<port>), the ref-vocabulary cache (vocab-<host>-<port>), the active recording marker (current-recording), and the once-per-run advisory markers (advisories/). It lives in:

  • $XDG_STATE_HOME/pinchtab/, if XDG_STATE_HOME is set
  • otherwise ~/.local/state/pinchtab/

Deleting it only resets CLI conveniences; it holds no browser data.

Default Storage Location

PinchTab keeps config and server state under one base directory. server.stateDir defaults to that directory, and profiles.baseDir defaults to <server.stateDir>/profiles:

OS Default Base Directory
Linux ~/.pinchtab/
macOS ~/.pinchtab/
Windows %APPDATA%\pinchtab\

Typical layout:

pinchtab/
├── config.json
├── activity/
│   └── events-2026-03-16.jsonl
├── sessions.json
└── profiles/
    └── default/

Platform Defaults

On macOS and Linux, ~/.pinchtab/ is the default base directory.

On Windows, PinchTab uses the OS-native config directory under %APPDATA%\pinchtab\.

Profiles

Profiles are the durable browser state PinchTab reuses across launches. A profile directory can contain:

  • cookies and login sessions
  • local storage and IndexedDB
  • cache and history
  • Chrome preferences and session files

Configure the profile root with:

{
  "profiles": {
    "baseDir": "/path/to/profiles",
    "defaultProfile": "default"
  }
}

profiles.defaultProfile controls the default profile name used by single-instance flows. In orchestrator mode, managed instances can still launch with other profile names.

Config File

The main config file is read from:

  • the path in PINCHTAB_CONFIG, if set
  • otherwise <user-config-dir>/config.json

Example:

{
  "server": {
    "port": "9867",
    "stateDir": "/var/lib/pinchtab/state"
  },
  "profiles": {
    "baseDir": "/var/lib/pinchtab/profiles",
    "defaultProfile": "default"
  }
}

Session State

Bridge session restore data is stored as:

<server.stateDir>/sessions.json

This file is used for tab/session restoration when restore behavior is enabled (instanceDefaults.tabPolicy.restore, default false).

Activity Logs

Request activity is stored as one JSONL file per UTC day:

<server.stateDir>/activity/events-YYYY-MM-DD.jsonl

Named sources also get their own daily files:

<server.stateDir>/activity/events-<source>-YYYY-MM-DD.jsonl

By default PinchTab keeps 30 days of activity data and prunes older daily files when new activity is recorded. You can change that with:

{
  "observability": {
    "activity": {
      "retentionDays": 30,
      "sessionIdleSec": 1800,
      "events": {
        "dashboard": false,
        "server": false,
        "bridge": false,
        "orchestrator": false,
        "scheduler": false,
        "mcp": false,
        "other": false
      }
    }
  }
}

retentionDays controls on-disk retention for activity logs. sessionIdleSec controls session grouping only. events controls which non-client sources are recorded. Client events are always recorded.

Requests that carry X-Agent-Id are stored with that value as agentId in the activity event. This is what powers agent-scoped queries such as GET /api/activity?agentId=<id> and the dashboard Agents view.

Unfiltered GET /api/activity reads the primary feed. Source-specific logs remain queryable by passing source=<name>.

In orchestrator mode, child instances get their own state directory under the profile:

<profile>/.pinchtab-state/

PinchTab writes a child config.json there so the launched instance can inherit the correct profile path, state directory, and port.

Managed child bridges disable their local activity recorder. Dashboard-visible activity comes from the parent server handling client traffic, so orchestrator-managed child state directories should not accumulate their own activity/events-*.jsonl files for new runs.

Profile logs and analytics endpoints are derived from the activity store rather than a separate analytics file.

Customizing Storage

Choose A Different Config File

export PINCHTAB_CONFIG=/etc/pinchtab/config.json
pinchtab server

Choose Different Profile And State Paths

{
  "server": {
    "stateDir": "/srv/pinchtab/state"
  },
  "profiles": {
    "baseDir": "/srv/pinchtab/profiles",
    "defaultProfile": "default"
  }
}

Container Use

For Docker or other containers, persist both config and profile data with a mounted volume and point PINCHTAB_CONFIG at a file inside that volume. A config selected through PINCHTAB_CONFIG must carry server.token (or the container must set PINCHTAB_TOKEN); PinchTab will not generate one into an operator-supplied file.

Example layout inside the volume:

/data/
├── config.json
├── state/
└── profiles/

Then set:

{
  "server": {
    "stateDir": "/data/state"
  },
  "profiles": {
    "baseDir": "/data/profiles"
  }
}

Security Notes

Profile directories often contain sensitive browser state:

  • cookies
  • session tokens
  • cached content
  • site data

Recommended practice:

  • keep profile directories out of version control
  • restrict permissions on config and profile directories
  • use separate profiles for separate security contexts

Cleanup

Removing the PinchTab data directory deletes:

  • saved profiles
  • session restore data
  • local configuration

Back up the profile directories first if you need to preserve logged-in browser sessions.