File size: 4,338 Bytes
6a7089a | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 | # 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:
```text
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:
```json
{
"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:
```json
{
"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:
```text
<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:
```text
<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:
```text
<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
```bash
export PINCHTAB_CONFIG=/etc/pinchtab/config.json
pinchtab
```
### Choose Different Profile And State Paths
```json
{
"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:
```text
/data/
├── config.json
├── state/
└── profiles/
```
Then set:
```json
{
"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.
|