File size: 3,737 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 | # Chrome User Data Directories & Profiles
PinchTab manages Chrome instances using dedicated **User Data Directories** (profiles). This document explains how these directories are resolved, how locks are managed, and how to handle parallel browser instances.
## Profile Resolution
PinchTab determines the Chrome `--user-data-dir` (profile) using the following precedence:
1. **Explicit `ProfileDir`**: If a specific path is provided in the configuration or as a flag, PinchTab uses that exact directory.
2. **Named Profile**: If a profile name is provided (e.g., via the dashboard or CLI), PinchTab resolves it to a subdirectory within the `ProfilesBaseDir`.
3. **Default Profile**: If no profile is specified, it defaults to `~/.config/pinchtab/profiles/default` (on Linux/macOS).
## The Singleton Model
Chrome enforces a **Singleton** model per User Data Directory. This means:
* Only **one** Chrome process can use a specific profile directory at any given time.
* If a second process attempts to use the same directory, Chrome will either fail to start or (in some configurations) attempt to open a new window in the existing process.
PinchTab adds an additional layer of protection using a `pinchtab.pid` file within the profile directory to ensure that only one PinchTab instance manages a specific profile.
## New Headless & Parallel Instances
With the introduction of **New Headless mode** (`--headless=new`), Chrome's profile sharing behavior has become stricter:
* **No Sharing**: You cannot reuse the same `--user-data-dir` across multiple concurrent instances.
* **Separate Directories Required**: Parallel browsers **must** use separate directories to avoid random startup errors and lock conflicts.
### Headless Auto-Fallback
To support parallel automation tasks, PinchTab implements an **automatic fallback for headless instances**:
1. If a headless instance tries to start using a profile that is already locked by another PinchTab process, it will **automatically create a unique temporary directory** (e.g., `/tmp/pinchtab-profile-*`).
2. This allows you to run multiple headless tasks in parallel without manually managing profile paths.
### Manual Parallelism (Headed Mode)
In **headed mode**, PinchTab does *not* automatically fall back to a temporary directory (to avoid losing user session data unexpectedly). If you need to run multiple headed browsers in parallel, you must:
* Use different named profiles.
* Explicitly provide a unique `--user-data-dir` for each instance.
## Best Practices for AI Agents
When building agents that use PinchTab, follow these guidelines:
* **Persistence**: Use named profiles (e.g., `agent-alpha`, `agent-beta`) if you need the browser to remember logins, cookies, or history across sessions.
* **Isolation**: For one-off tasks or high-concurrency scraping, rely on the default headless mode which handles directory isolation automatically if conflicts occur.
* **Cleanup**: If you manually create temporary directories, ensure they are cleaned up after the task is complete to avoid filling up disk space.
## Troubleshooting
If you see the error `"The profile appears to be in use by another Chromium process"`:
1. **Check for active instances**: Ensure you don't have another PinchTab or Chrome process already using that profile.
2. **Stale Locks**: If no process is active, PinchTab will attempt to automatically clear stale `SingletonLock` files on the next startup.
3. **Manual Fix**: In rare cases, you may need to manually remove the `SingletonLock` file from the profile directory.
For more details on how PinchTab recovers from crashes, see [Chrome Profile Lock Recovery](docs/implementations/chrome-profile-lock-recovery.md).
|