Early Bird - the Full Version is $19 right now, before it goes to $39. See pricing →
Needlework Studio

Desktop Sync

Synchronize your patterns and thread inventory between the desktop app and a self-hosted Needlework Studio server.

Some features on this page require the Full Version.

Overview

The Needlework Studio desktop app can operate entirely offline as a standalone application, but it also supports bidirectional synchronization with a self-hosted Needlework Studio server. When sync is configured, your data flows in both directions - changes made on the desktop are pushed to the server, and changes made on the server (or from another synced desktop) are pulled to the desktop.

This means you can design patterns on your laptop, review them on your phone through the server's web interface, and track stitching progress from either device. All data stays in sync automatically.

Setting Up Sync

To pair the desktop app with a server:

  1. Open the sync panel - Click the cloud icon in the desktop app's navigation bar. This opens the sync configuration panel.
  2. Enter the server URL - Type the full URL of your Needlework Studio server instance (for example, https://needlework.example.com or http://192.168.1.50:6850). The URL should point to the root of the application, not to a specific page.
  3. Enter your credentials - Provide the username and password for your account on the server. These credentials are used only once during the pairing process to authenticate and request an API token.
  4. Enter the pairing code, if your server asks for one - A server on your own network that makes its own certificate has a pairing code. Read it from the server's sign-in page in a browser, from its Settings page, or from the container's startup output. See Deployment for where to find it. A server behind a reverse proxy with a domain name does not need one, and the field can be left empty.
  5. Pair - Click the pair button. The desktop app sends your credentials to the server, which validates them and issues an API token. This token is stored securely on the desktop and used for all subsequent sync operations.

Why the Pairing Code Exists

A server that made its own certificate is not vouched for by anyone your computer already trusts, so on its own the desktop app cannot tell your server apart from something else answering on the same address. The pairing code closes that gap. It describes the server's certificate, and the desktop checks it before your username and password leave your computer. If it does not match, nothing is sent.

Because the code is checked first, the desktop app will not pair with a server on your own network without one. If you leave the field empty for a local address, it will ask you for the code rather than sending your credentials anyway.

After pairing, the desktop keeps checking that certificate on every sync. If it ever changes, syncing stops and you are told. That happens if the server was reinstalled, in which case you disconnect and pair again with its new code. It also happens if something is sitting between you and the server, which is worth understanding before you reconnect.

Security Note

Your username and password are not stored on the desktop after pairing. They are sent to the server once to obtain an API token, and then discarded. Only the API token is retained. The token provides the desktop app with the ability to read and write your data on the server without needing to store your credentials. If you are concerned about token security, you can revoke it at any time by unpairing (see below).

Server Requirements

To use sync, you need a running Needlework Studio server that is accessible from the machine running the desktop app. The server can be on your local network (accessible by IP address) or exposed to the internet with a domain name. If you have not set up a server yet, see the Installation and Deployment guides.

How Sync Works

Synchronization transfers data between the desktop app and the server to keep both copies up to date.

Automatic Sync on Launch

When the desktop app starts and a server is paired, it automatically performs a sync operation. This pulls any changes from the server (such as patterns you created via the web interface) and pushes any local changes that have not yet been synced. You do not need to take any action - sync happens in the background during startup.

Manual Sync

You can trigger a sync at any time by clicking the Sync Now button in the sync panel. This is useful if you have just made changes on the server and want them to appear on the desktop immediately without restarting the app, or if you want to ensure your latest desktop changes are pushed to the server before switching devices.

What Syncs

The sync process covers all of the core data in Needlework Studio. Sync operates in two separate phases:

  1. Full sync - Transfers patterns (grid data, legend, stitches, thumbnails, metadata), reference chart pages, thread inventory, stitching history, and deletions between the desktop and server. This is the heavier operation and runs on app launch and when you click Sync Now.
  2. Progress sync - A lightweight, independent phase that transfers only stitch progress data (stitched cells, marked backstitches, knots and beads, place markers, per-color completion, and accumulated time). Because it carries a much smaller payload, progress sync can run more frequently and finish faster, so your stitching progress stays up to date across devices without waiting for a full sync.

Both phases are bidirectional - changes are pulled from and pushed to the server. The two phases can run independently of each other.

Full Sync: Saved Patterns

During full sync, all saved patterns are synced, including:

  • Grid data - The complete stitch grid with all full stitch placements and colors.
  • Legend - The thread color legend with DMC/Anchor thread references, symbols, and color definitions.
  • Part stitches - Half stitches, quarter stitches, and three-quarter stitches with their positions and orientations.
  • Backstitches - All backstitch lines with start and end coordinates and thread color assignments.
  • French knots - All French knot positions and their thread color assignments.
  • Thumbnails - Pattern thumbnail images for display in the gallery.
  • Metadata - Pattern name, status (Not Started / In Progress / Completed), creation date, and modification timestamps.

Full Sync: Thread Inventory

Your thread inventory data is synced across devices during full sync, including:

  • Ownership status - Whether each thread is marked as Own, Need, or Don't Own.
  • Skein quantities - The number of skeins recorded for each thread.
  • Notes - Any free-text notes you have attached to individual threads.

Full Sync: Deletions

When you delete a pattern on one device, that deletion is propagated to the other device during the next full sync. The pattern will be removed from both the desktop and the server. Deletions are tracked so that a deleted pattern does not reappear from the other device's copy.

Full Sync: Reference Chart Pages

Reference chart pages travel with the pattern they belong to. Import a chart on one computer and the pages appear on your other computers and on the server, images included, with the same placement, size, rotation, crop, and opacity you set.

Images are larger than the rest of a pattern, so a page that has not finished transferring fills in on the next sync rather than holding up everything else. If a chart looks like it is missing pages just after a sync, give it another round.

Reference pages only sync between computers running a version that understands them. Update the app everywhere you stitch, and if you run your own server, update the server before your desktops.

Full Sync: Stitching History

Your day by day stitching history belongs to your account rather than to one computer. Days you stitched on the desktop show up on the laptop's chart, on the days they actually happened, and your streak and finish estimates count them too.

History travels with the regular full sync, so give it a moment to catch up after you switch machines. See Stats for what the history is used for.

Progress Sync

Progress sync runs as a separate, lightweight phase and transfers only stitch progress data. This includes:

  • Stitched cells - Which cells have been marked as stitched in the pattern viewer.
  • Cleared cells - Cells that were previously stitched but have been unmarked.
  • Backstitches, knots, and beads - Specialty stitches you have marked as done, tracked separately from full crosses. See Pattern Viewer.
  • Place markers - Markers you have placed on the pattern to track your position.
  • Per-color completion - Which DMC colors have been fully completed.
  • Accumulated time - Total stitching time tracked for the pattern.

Because progress sync carries only this compact data, it is significantly faster than a full sync and can run independently for quicker updates when you are actively stitching.

Conflict Resolution

In cases where the same piece of data has been modified on both the desktop and the server since the last sync, a conflict occurs. Needlework Studio uses a last-write-wins strategy based on modification timestamps to resolve conflicts.

When two versions of the same pattern or thread record have different modification times, the version with the more recent timestamp is kept, and the older version is overwritten. This approach is simple and predictable: the most recent change always takes precedence.

In practice, conflicts are rare if you follow a natural workflow of making changes on one device at a time and syncing regularly. If you are concerned about accidental data loss, you can duplicate a pattern before making major changes, which creates an independent backup copy that will not be affected by sync conflicts on the original.

Status Indicator

The sync status is communicated visually through the cloud icon in the desktop app's navigation bar. The icon changes color and animation to reflect the current state:

  • Gray - Unpaired. The desktop app is not connected to any server. Sync is not configured. Click the icon to set up pairing.
  • Green - Paired and idle. The desktop app is paired with a server and the last sync completed successfully. Data is up to date.
  • Gold pulse - Syncing. A sync operation is currently in progress. The icon pulses with a gold animation while data is being transferred. Avoid closing the app while syncing to ensure all data is transferred completely.
  • Red - Error. The last sync attempt failed. This typically means the server is unreachable (network issue, server is down, or the URL has changed). Check your network connection and server status. The icon will return to green after a successful sync.

Unpairing

If you want to disconnect the desktop app from the server, you can unpair at any time:

  1. Click the cloud icon to open the sync panel.
  2. Click the Unpair button.
  3. Confirm the action in the dialog.

When you unpair, the following happens:

  • The API token stored on the desktop is deleted.
  • The token is revoked on the server, so it cannot be reused even if someone were to recover it.
  • The desktop app returns to standalone mode. Your local data remains intact - nothing is deleted from the desktop. However, future changes on the server will no longer be pulled to the desktop, and local changes will no longer be pushed.

You can re-pair with the same server (or a different one) at any time by going through the setup process again. Re-pairing will issue a new API token and resume synchronization.