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

> Discover how Cherry Studio's WebDAV synchronization plugin enables seamless file management and automatic backups with customizable schedules and retention policies. Secure your data effortlessly.

- Repository: [CherryHQ/cherry-studio](https://github.com/cherryhq/cherry-studio)
- Tags: deep-dive
- Published: 2026-02-27

---

**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`](https://github.com/cherryhq/cherry-studio/blob/main/src/renderer/src/store/settings.ts) and orchestrates backup triggers through [`BackupService.ts`](https://github.com/cherryhq/cherry-studio/blob/main/BackupService.ts).
- **Preload Bridge**: Exposes type-safe IPC channels in [`src/preload/index.ts`](https://github.com/cherryhq/cherry-studio/blob/main/src/preload/index.ts) for `backupToWebdav`, `listWebdavFiles`, `checkWebdavConnection`, and `deleteWebdavFile`.
- **Main Process**: Executes WebDAV operations in [`src/main/services/BackupManager.ts`](https://github.com/cherryhq/cherry-studio/blob/main/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`](https://github.com/cherryhq/cherry-studio/blob/main/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:

```typescript
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`](https://github.com/cherryhq/cherry-studio/blob/main/src/preload/index.ts) (lines 179-184). This IPC channel routes to `BackupManager.backupToWebdav` in [`src/main/services/BackupManager.ts`](https://github.com/cherryhq/cherry-studio/blob/main/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

```typescript
// 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`](https://github.com/cherryhq/cherry-studio/blob/main/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`](https://github.com/cherryhq/cherry-studio/blob/main/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`](https://github.com/cherryhq/cherry-studio/blob/main/src/renderer/src/services/NutstoreService.ts) (lines 53-55), which reuses the same WebDAV infrastructure for Chinese cloud storage compatibility.

```typescript
// 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`](https://github.com/cherryhq/cherry-studio/blob/main/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`](https://github.com/cherryhq/cherry-studio/blob/main/BackupService.ts) to schedule recurring uploads with state tracking in [`src/renderer/src/store/backup.ts`](https://github.com/cherryhq/cherry-studio/blob/main/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`](https://github.com/cherryhq/cherry-studio/blob/main/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`](https://github.com/cherryhq/cherry-studio/blob/main/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`](https://github.com/cherryhq/cherry-studio/blob/main/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`](https://github.com/cherryhq/cherry-studio/blob/main/BackupManager.ts), it is compatible with any service exposing a WebDAV interface, including Nextcloud, ownCloud, and various hosted WebDAV providers.