Syncing Your Bookmarks

Pinax is designed with privacy first, which means your data stays on your device by default. However, you have full control over how and where you sync your bookmarks.

How Syncing Works

Pinax stores all your bookmarks in a single bookmarks.json file. This file contains everything - your bookmarks, folders, and tags. Because it’s just a standard JSON file, you can sync it however you want.

This will store only your bookmark data. Settings and cached images are not synced. More on this below.

Your Sync Options

1. File-Based Sync (Available Now)

The simplest and most private option. Point Pinax to a folder that’s already synced by a service you trust:

  • Dropbox - Set your bookmarks file location to your Dropbox folder
  • iCloud Drive - Store bookmarks in iCloud and access across Apple devices
  • Syncthing - Open source, peer-to-peer sync (no cloud servers)
  • Google Drive - Use Google’s file sync
  • OneDrive - Microsoft’s cloud storage
  • Any network drive - Even a USB drive works

Privacy benefit: You choose the service. You control the encryption. No Pinax servers involved.

2. Self-Hosted Sync (Coming in Phase 3)

For maximum control, host your own sync server:

  • CouchDB - Full replication protocol with conflict resolution
  • Simple HTTP Server - Lightweight option for basic sync
  • Your own infrastructure - Complete control over your data

3. Paid Sync Service (Coming in Phase 5)

For convenience without the setup:

  • End-to-end encrypted
  • Automatic sync across all devices
  • Zero-knowledge architecture (we can’t read your bookmarks)
  • Optional - you can always switch back to file-based sync

Setting Up File-Based Sync

Step 1: Choose Your Sync Service

Pick a file sync service you already use or trust. Install it on all devices where you want to access your bookmarks.

Step 2: Configure Pinax

  1. Open Pinax Settings
  2. Go to Storage Settings
  3. Click Change Storage Location
  4. Navigate to your synced folder (e.g., ~/Dropbox/Pinax/)
  5. Click Select Folder

Pinax will move your bookmarks.json file to this location.

Step 3: Repeat on Other Devices

Install Pinax on your other devices and point them to the same folder. That’s it - your bookmarks are now synced.

How Conflicts Are Handled

When the same bookmark is edited on multiple devices, Pinax uses a “last-write-wins” strategy based on timestamps. The most recent change is kept.

Best practices to avoid conflicts:

  • Let file changes sync before editing on another device
  • Most sync services handle file-level conflicts automatically
  • Pinax auto-reloads when it detects file changes

Future improvement: In Phase 5, we’ll add CRDT-based merging for conflict-free sync across all devices.

Settings Sync

Your app settings are stored separately in settings.json and must remain local to each device. This is so Pinax knows where to find your other files. This also allows you to have different preferences per device (like theme, view mode, or window size) while keeping your bookmarks synced.

What syncs:

  • Bookmarks
  • Folders
  • Tags
  • Bookmark metadata (notes, pins, archives)

What doesn’t sync:

  • App settings (theme, view preferences)
  • Window size and position
  • Cache files (OG images)

Cache Files

If you enable OG Image fetching in Settings, Pinax creates a local cache folder to store compressed images. This cache is not synced between devices.

Why cache isn’t synced:

  • Keeps sync payload small and fast
  • Each device fetches images once and caches locally
  • Images are compressed to save space
  • Cache can be deleted anytime (images will re-download if needed)

Cache location:

  • Mac: ~/Library/Application Support/Pinax/cache/
  • Windows: %APPDATA%\Pinax\cache\
  • Linux: ~/.config/Pinax/cache/

Privacy Considerations

File-Based Sync

When using file sync services, your bookmarks are encrypted in transit by the service (Dropbox, iCloud, etc.). However, the service provider can technically access your files.

To maximize privacy:

  • Use end-to-end encrypted services (Syncthing, Tresorit)
  • Encrypt your sync folder with tools like Cryptomator
  • Use self-hosted solutions (Nextcloud with encryption)

Self-Hosted Sync

Complete control over your data. No third parties involved. You manage the encryption and access.

When available, our paid sync will use end-to-end encryption with zero-knowledge architecture. We won’t be able to read your bookmarks even if we wanted to.

Troubleshooting

Bookmarks not syncing

  1. Check that your sync service is running and connected
  2. Verify the file path in Settings matches on all devices
  3. Look for sync conflicts in your sync service
  4. Check file permissions (Pinax needs read/write access)

Duplicate bookmarks

This can happen if you edit on multiple devices before sync completes. Pinax uses timestamps to resolve conflicts, but you may need to manually remove duplicates.

File locked or in use

Some sync services lock files during upload. Pinax will retry automatically. If the issue persists, check your sync service settings.

Next Steps