docs/persistence.md

Persistence — staying logged in

The Chrome profile (cookies/logins) lives in /home/chrome/data. How it survives a restart depends on where you run.

Hugging Face → Neon Postgres (required)

HF free cpu-basic Spaces have no persistent disk — the filesystem is wiped on every restart/rebuild. So the profile is snapshotted to an external Postgres DB by the profilesync tool:

• Boot: profilesync restore pulls the last snapshot.
• Every 5 min + on shutdown: profilesync backup saves it.
• Stored as one row: chrome_profile(id, updated_at, data bytea) (auto-created).
• Gated on DATABASE_URL. Not set → restore/backup skipped → logins lost on restart.

Setup

1. Free DB at neon.tech → copy the connection string (postgresql://user:pass@host.neon.tech/db?sslmode=require).
2. HF Space → Settings → Variables and secrets → secret DATABASE_URL = that string.
3. Saving auto-restarts the Space. Log in once after that → first backup within 5 min → survives all future restarts.

Verify a backup landed

SELECT id, updated_at, octet_length(data) FROM chrome_profile;

A row with non-zero size = persisted. (Profile stays small — junk/cache is stripped each boot; typically 0.5–2 MB. Neon free = 512 MB, so it's ~0.1% used.)

Self-host Docker → named volume (no DB needed)

docker-compose.yml mounts the chrome-profile named volume at /home/chrome/data, so logins survive docker compose down/up and reboots automatically. DATABASE_URL is not needed for Docker. To wipe the profile: docker compose down -v.

Important: setting a new secret on HF forces a restart. If you log in before DATABASE_URL is set, that login is lost on the restart the secret triggers — log in again afterward.