docs/guides/data-storage.md

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
action_logs.json	Profile activity log used by profile analytics	not currently configurable
sessions.json	Saved tab/session state for a bridge instance	server.stateDir
<profile>/.pinchtab-state/config.json	Child instance config written by the orchestrator	generated automatically for managed instances

Default Storage Location

PinchTab uses the OS config directory:

OS	Default Base Directory
Linux	~/.config/pinchtab/ or $XDG_CONFIG_HOME/pinchtab/
macOS	~/Library/Application Support/pinchtab/
Windows	%APPDATA%\\pinchtab\\

Typical layout:

pinchtab/
├── config.json
├── action_logs.json
├── sessions.json
└── profiles/
    └── default/

Legacy Fallback

For backward compatibility, PinchTab still uses ~/.pinchtab/ if:

• that legacy directory already exists
• and the newer OS-native location does not exist yet

That fallback applies to both config lookup and the default base storage directory.

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.

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.

Action Logs

PinchTab stores profile activity in:

<user-config-dir>/action_logs.json

This powers profile analytics endpoints. It is separate from the per-instance session restore state.

Customizing Storage

Choose A Different Config File

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

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.

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
• action logs
• local configuration

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