Multi-Machine Sync

Upsight supports running on multiple machines by syncing your data directory with Syncthing. A session lock mechanism prevents two instances from writing to the same database simultaneously.

How It Works

Upsight stores all its data in an XDG-compliant data directory (see Settings > Paths). By syncing this directory with Syncthing, you can access the same accounts, contacts, and configuration from any machine. The session lock file ensures only one instance is active at a time.

Session Lock File

On startup, Upsight writes a upsight.session file in the data directory containing:

• Hostname -- the machine name
• PID -- the process ID
• Started at -- when the session began
• Heartbeat at -- updated every 30 seconds while the app is running

When you launch Upsight on a second machine, it reads the session file and determines whether the lock is held:

• Own session (same hostname and PID from a previous crash) -- the lock is taken over
• Remote session with fresh heartbeat -- the app shows a locked screen
• Stale session (heartbeat older than 2 minutes) -- the lock is assumed abandoned and taken over

The Locked Screen

If the session is locked by another machine, Upsight shows a screen that says:

Upsight is open on another machine

Currently running on [hostname] since [timestamp].

Close it there, then click Retry.

You have two options:

• Retry -- re-check the session file (use this after closing the app on the other machine)
• Exit -- close Upsight

Tip

If the other instance crashed and did not release the lock, wait 2 minutes for the stale heartbeat to expire, then click Retry.

Syncthing Setup

Which Directories to Sync

Sync the Upsight data directory:

Platform	Default Path
Linux	~/.local/share/upsight/
macOS	~/Library/Application Support/upsight/

You may also want to sync the config directory if you want settings to follow you across machines:

Platform	Default Path
Linux	~/.config/upsight/
macOS	~/Library/Application Support/upsight/

.stignore Patterns

Add the following patterns to your Syncthing .stignore file for the data directory to avoid syncing transient files:

upsight.session
upsight.session.tmp
*.db-wal
*.db-shm

The session file is machine-specific and should not be synced. The WAL and SHM files are SQLite runtime files that are checkpointed into the main database on graceful shutdown.

Workflow

1. Work on Machine A -- Upsight holds the session lock and writes data
2. Close Upsight on Machine A -- the session file is deleted, and the WAL is checkpointed into the database
3. Syncthing syncs the updated upsight.db to Machine B
4. Open Upsight on Machine B -- it acquires the session lock and loads the latest data

Warning

Always close Upsight on one machine before opening it on another. Running two instances simultaneously against the same synced database will cause conflicts.

Stale Lock Recovery

If a machine loses power or the app is force-killed, the session file is left behind. The heartbeat timestamp stops updating. After 2 minutes without a heartbeat, any other machine treats the lock as stale and takes over the session.

On the crashed machine, the next launch detects its own stale session (same hostname and PID) and reclaims it immediately.

Tips for Smooth Syncing

• Close before switching -- always quit Upsight before moving to another machine
• Wait for sync -- give Syncthing a few seconds to propagate changes before opening on the other machine
• Check Syncthing status -- if the locked screen appears unexpectedly, verify that Syncthing has finished syncing the data directory
• Use the .stignore patterns -- prevents transient files from causing unnecessary sync conflicts