How Desktop-Cloud-Sync Synchronizes Resources Between Local and Cloud Stores in OpenWork

The desktop-cloud-sync mechanism in OpenWork fetches a fresh ResourceSnapshot from the Den cloud, computes diffs against locally-installed resources on the server, and merges pending changes into the workspace state through a throttled queue, ensuring the desktop client maintains an authoritative mirror of cloud-based LLM providers, marketplaces, and plugins.

Keeping local resource configurations synchronized with cloud-based authoritative sources is critical for distributed applications. In the different-ai/openwork repository, the desktop-cloud-sync module provides a robust, asynchronous pipeline that aligns the desktop application's local state with the OpenWork Den cloud. This process involves three distinct stages—client snapshot retrieval, server-side diffing and persistence, and client-side change consumption—all orchestrated through specific TypeScript implementations.

The Three-Stage Synchronization Flow

The synchronization process operates as a closed loop between the desktop client and the OpenWork server, ensuring that local installations remain consistent with the cloud's authoritative state without causing race conditions.

Stage 1: Fetching the Remote ResourceSnapshot

The client-side initiation occurs in apps/app/src/app/cloud/desktop-cloud-sync.ts within the runDesktopCloudSync function. The desktop app first reads the user’s Den settings to instantiate a Den client, then calls getResourceSnapshot to retrieve the complete remote state encapsulated in a ResourceSnapshot object.

This snapshot contains the authoritative definitions for all cloud-hosted resources, including LLM providers, marketplaces, and plugin configurations. The client then transmits this snapshot to the server via a POST request to the /workspace/:id/desktop-cloud-sync RPC endpoint.

Stage 2: Server-Side Diffing and State Persistence

Upon receiving the snapshot, the server—implemented in apps/server/src/desktop-cloud-sync.ts—invokes the syncDesktopCloudResources function. This function performs four critical operations:

1. Retrieves historical state using readDesktopCloudSyncState to fetch any previously persisted sync data for the workspace.
2. Computes pending changes via diffInstalledCloudResources, comparing the incoming cloud snapshot against the locally-installed cloud imports to identify additions, updates, or removals.
3. Merges change sets through mergePendingChanges, combining newly detected differences with any existing pending changes to create a unified delta.
4. Persists the result by writing the updated desktopCloudSync object back into the workspace’s OpenWork data store.

The server returns the computed changes to the client, completing the transactional update.

Stage 3: Consuming Pending Changes on the Client

After the server updates the state, the desktop client retrieves the pending changes through a GET request to /workspace/:id/desktop-cloud-sync. The functions readPendingCloudSyncChanges and derivePendingCloudPluginChanges—both located in apps/app/src/app/cloud/desktop-cloud-sync.ts—parse this state to generate a actionable map of plugins requiring updates or deletion.

Concurrency Control via the Sync Queue

To prevent race conditions when multiple refresh requests occur simultaneously, OpenWork implements the desktopCloudSyncQueue. This queue serializes all synchronization attempts, ensuring that only one diff-and-merge operation executes at a time per workspace. The throttling mechanism guarantees data integrity by avoiding concurrent writes to the desktopCloudSync state object.

Key Implementation Files and Functions

The following source files contain the core logic for the synchronization mechanism:

• apps/app/src/app/cloud/desktop-cloud-sync.ts – Contains runDesktopCloudSync, refreshDesktopCloudSync, readPendingCloudSyncChanges, and derivePendingCloudPluginChanges for client-side orchestration and state parsing.
• apps/server/src/desktop-cloud-sync.ts – Implements syncDesktopCloudResources, readDesktopCloudSyncState, diffInstalledCloudResources, and mergePendingChanges for server-side diffing and persistence logic.
• apps/server/src/server.ts – Registers the GET and POST /workspace/:id/desktop-cloud-sync route handlers that expose the synchronization RPC endpoints.

Practical Code Examples

Triggering a Sync from the Desktop App

Use the refreshDesktopCloudSync helper to initiate a synchronization cycle from the client:

import { refreshDesktopCloudSync } from '@/app/cloud/desktop-cloud-sync';

refreshDesktopCloudSync({
  openworkClient,
  workspaceId: 'ws_1',
}).then((result) => {
  if (result) {
    console.log('Sync completed – changes:', result.changes);
  } else {
    console.log('Sync not started (missing client or workspace).');
  }
});

Server-Side Endpoint Handling

The server exposes the synchronization logic through a typed route handler:

addRoute(routes, 'POST', '/workspace/:id/desktop-cloud-sync', 'client', async (ctx) => {
  const { workspaceId } = ctx.params;
  const snapshot = await ctx.body.json(); // Remote ResourceSnapshot
  const result = syncDesktopCloudResources({
    openwork: ctx.state.openwork,
    snapshot,
  });
  ctx.body = result; // Returns changes and updated state
});

Deriving Plugin Updates from Pending Changes

Process the server-returned state to identify specific plugin actions:

import {
  readPendingCloudSyncChanges,
  derivePendingCloudPluginChanges,
} from '@/app/cloud/desktop-cloud-sync';

// `state` is the persisted DesktopCloudSyncState obtained from the server
const pendingChanges = readPendingCloudSyncChanges(state);
const installedPlugins = { /* pluginId → { updatedAt, files } */ };

const pluginsToUpdate = derivePendingCloudPluginChanges({
  changes: pendingChanges,
  installedPlugins,
});

console.log('Plugins requiring action:', pluginsToUpdate);

Summary

• Desktop-cloud-sync maintains consistency between the OpenWork Den cloud and local desktop environments through a three-stage pipeline involving snapshot retrieval, server-side diffing, and client-side change application.
• The ResourceSnapshot object serves as the authoritative data transfer unit, captured by the client's runDesktopCloudSync function and processed by the server's syncDesktopCloudResources function.
• Server-side logic in apps/server/src/desktop-cloud-sync.ts handles complex diffing via diffInstalledCloudResources and safe state merging via mergePendingChanges.
• The desktopCloudSyncQueue prevents race conditions by serializing concurrent synchronization requests.
• Client utilities readPendingCloudSyncChanges and derivePendingCloudPluginChanges translate server state into actionable plugin management commands.

Frequently Asked Questions

What is the role of the ResourceSnapshot in desktop-cloud-sync?

The ResourceSnapshot is a complete serialized representation of the cloud's current resource state, including all LLM providers, marketplaces, and plugin configurations. The desktop client retrieves this snapshot from the Den cloud and transmits it to the server, where it serves as the authoritative baseline for diffInstalledCloudResources to compute pending changes against locally-installed items.

How does OpenWork prevent race conditions during synchronization?

OpenWork prevents race conditions through the desktopCloudSyncQueue, which serializes all synchronization requests. When multiple refresh operations trigger simultaneously, the queue ensures that only one syncDesktopCloudResources execution runs at a time per workspace, preventing concurrent overwrites of the desktopCloudSync state object.

Where is the pending sync state stored in the OpenWork architecture?

The pending synchronization state is persisted within the workspace's OpenWork data store on the server. The readDesktopCloudSyncState function retrieves this history from the workspace record, while syncDesktopCloudResources writes the merged changes back to the same location after computing the latest diff.

How can developers trigger a manual cloud sync from the desktop app?

Developers invoke the refreshDesktopCloudSync function imported from @/app/cloud/desktop-cloud-sync, passing an authenticated openworkClient instance and the target workspaceId. This helper handles the Den client initialization, snapshot retrieval, and server RPC call, returning a promise that resolves with the change set or null if prerequisites are missing.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}