How WebDAV Synchronization Works in Cherry Studio for File Management and Backups

Cherry Studio implements WebDAV synchronization as a plugin-style remote backup system that supports both manual one-click backups and automatic scheduled synchronization with configurable retention policies.

The cherryhq/cherry-studio repository uses a three-layer architecture to manage WebDAV file operations, enabling users to securely back up application data to any WebDAV-compatible storage provider. This implementation handles connection validation, incremental uploads, automatic cleanup of old backups, and real-time sync status monitoring through the Redux state management system.

WebDAV Architecture Overview

Cherry Studio separates WebDAV concerns across the Electron process boundary to maintain security and performance:

• Renderer Process (UI Layer): Manages WebDAV configuration in the Redux store at src/renderer/src/store/settings.ts and orchestrates backup triggers through BackupService.ts.
• Preload Bridge: Exposes type-safe IPC channels in src/preload/index.ts for backupToWebdav, listWebdavFiles, checkWebdavConnection, and deleteWebdavFile.
• Main Process: Executes WebDAV operations in src/main/services/BackupManager.ts using the webdav npm client, handling retries, streaming uploads, and backup rotation.

Configuring WebDAV Synchronization

WebDAV settings persist in the Redux slice defined in src/renderer/src/store/settings.ts (lines 133-152). The configuration object includes:

• webdavHost: The WebDAV server URL (e.g., https://dav.example.com/remote)
• webdavUser and webdavPass: Authentication credentials
• webdavPath: Target directory on the remote server
• webdavAutoSync: Boolean flag enabling automatic synchronization
• webdavSyncInterval: Timer duration in milliseconds between auto-sync attempts
• webdavMaxBackups: Retention limit for automatic cleanup

Enable auto-sync by dispatching the appropriate actions:

import { setWebdavAutoSync, setWebdavHost, setWebdavUser, setWebdavPass, setWebdavPath, setWebdavSyncInterval } from '@/store/settings'

// Configure connection
dispatch(setWebdavHost('https://dav.example.com/remote'))
dispatch(setWebdavUser('alice'))
dispatch(setWebdavPass('secure-password'))
dispatch(setWebdavPath('/cherry-studio'))

// Enable automatic synchronization every 30 minutes
dispatch(setWebdavAutoSync(true))
dispatch(setWebdavSyncInterval(30 * 60 * 1000))

Manual Backup Process

When triggering a manual backup, the renderer process calls window.api.backup.backupToWebdav through the preload bridge defined in src/preload/index.ts (lines 179-184). This IPC channel routes to BackupManager.backupToWebdav in src/main/services/BackupManager.ts (lines 446-470).

The backup execution follows this sequence:

1. Payload Generation: The renderer serializes application data to JSON
2. Client Initialization: The main process creates a webdav client instance using the provided host, user, and password
3. Streaming Upload: The backup data streams to ${webdavPath}/${fileName} on the remote server
4. Retention Cleanup: If webdavMaxBackups exceeds zero, the system retrieves the remote directory listing, sorts files by timestamp, and deletes oldest entries until the limit is satisfied

// Example: Manual backup trigger from renderer process
async function performManualBackup() {
  const settings = useAppSelector(state => state.settings)
  
  const backupPayload = JSON.stringify({
    conversations: await getConversations(),
    settings: settings,
    timestamp: Date.now()
  })

  try {
    const success = await window.api.backup.backupToWebdav(backupPayload, {
      webdavHost: settings.webdavHost,
      webdavUser: settings.webdavUser,
      webdavPass: settings.webdavPass,
      webdavPath: settings.webdavPath,
      skipBackupFile: settings.webdavSkipBackupFile,
      disableStream: settings.webdavDisableStream
    })
    
    return success
  } catch (error) {
    console.error('Backup failed:', error)
    return false
  }
}

Automatic Synchronization

The auto-sync mechanism resides in src/renderer/src/services/BackupService.ts (lines 498-529 and 571-579). When webdavAutoSync is enabled, the service initializes a timeout loop that:

• Checks connection prerequisites (webdavHost must be defined)
• Invokes backupToWebdav with autoBackupProcess: true to distinguish scheduled runs from manual triggers
• Updates the Redux store at src/renderer/src/store/backup.ts with sync status, timestamps, and error states

The sync state interface includes:

• syncing: Boolean indicating active upload
• lastSyncTime: Timestamp of last successful backup
• lastSyncError: Error message from failed attempts

Connection Testing and File Management

Before establishing regular sync schedules, users can verify WebDAV connectivity through checkWebdavConnection exposed in the preload bridge. This method attempts a stat operation on the configured remote path to validate credentials and accessibility.

For backup rotation and cleanup, the system exposes:

• listWebdavFiles: Retrieves directory contents using getDirectoryContents from the webdav client
• deleteWebdavFile: Removes specific remote files when enforcing retention limits

These utilities also power the Nutstore integration found in src/renderer/src/services/NutstoreService.ts (lines 53-55), which reuses the same WebDAV infrastructure for Chinese cloud storage compatibility.

// Example: Listing and managing remote backups
async function cleanupOldBackups(maxBackups: number) {
  const settings = useAppSelector(s => s.settings)
  
  const files = await window.api.backup.listWebdavFiles({
    webdavHost: settings.webdavHost,
    webdavUser: settings.webdavUser,
    webdavPass: settings.webdavPass,
    webdavPath: settings.webdavPath
  })
  
  const sortedBackups = files
    .filter(f => f.fileName.endsWith('.json'))
    .sort((a, b) => a.lastModified - b.lastModified)
  
  while (sortedBackups.length > maxBackups) {
    const oldest = sortedBackups.shift()
    await window.api.backup.deleteWebdavFile({
      ...settings,
      fileName: oldest.fileName
    })
  }
}

Error Handling and Logging

All WebDAV operations funnel through the centralized logger service using loggerService.withContext('backup'). The main process catches exceptions during client initialization, network requests, and file operations, surfacing them to the renderer through the IPC response and Redux state.

Error states persist in backup.webdavSync.lastSyncError, allowing the UI to display specific failure reasons such as authentication errors, network timeouts, or path not found exceptions without exposing sensitive credential details in logs.

Summary

• Cherry Studio implements WebDAV synchronization through a three-tier Electron architecture separating UI state, IPC bridging, and WebDAV client execution.
• Configuration persists in the Redux store at src/renderer/src/store/settings.ts with fields for host, credentials, path, and auto-sync intervals.
• Manual backups stream JSON payloads through window.api.backup.backupToWebdav, handled by BackupManager.backupToWebdav in the main process.
• Automatic synchronization uses BackupService.ts to schedule recurring uploads with state tracking in src/renderer/src/store/backup.ts.
• Retention management enforces webdavMaxBackups by listing remote files with listWebdavFiles and deleting oldest entries via deleteWebdavFile.
• Connection validation occurs through checkWebdavConnection before establishing sync schedules.

Frequently Asked Questions

How do I enable automatic WebDAV backups in Cherry Studio?

Enable automatic synchronization by dispatching setWebdavAutoSync(true) to the Redux store and configuring the connection parameters including webdavHost, webdavUser, webdavPass, and webdavPath. Set webdavSyncInterval to define the milliseconds between automatic backups. The BackupService.ts scheduler handles the recurring execution when these values are present.

What happens when the maximum backup limit is reached?

When webdavMaxBackups is configured with a value greater than zero, the system automatically manages storage rotation. After each successful upload, BackupManager.backupToWebdav calls listWebdavFiles to retrieve the remote directory contents, sorts the backup files by timestamp, and deletes the oldest files using deleteWebdavFile until the total count matches the configured limit.

How does Cherry Studio validate WebDAV connections before syncing?

The application verifies connectivity through the checkWebdavConnection method exposed in the preload bridge at src/preload/index.ts. This IPC call routes to the main process where a temporary WebDAV client attempts a stat operation on the configured webdavPath. The method returns a boolean indicating success or failure, allowing the UI to validate credentials and accessibility before enabling automatic synchronization or manual backups.

Can I use WebDAV synchronization with Nutstore or other Chinese cloud storage providers?

Yes, Cherry Studio's WebDAV implementation is provider-agnostic and specifically supports Nutstore integration. The NutstoreService.ts file reuses the same WebDAV infrastructure, calling checkWebdavConnection and other backup methods with Nutstore-specific endpoints. Since the system uses the standard webdav npm client in BackupManager.ts, it is compatible with any service exposing a WebDAV interface, including Nextcloud, ownCloud, and various hosted WebDAV providers.

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