> For the complete documentation index, see [llms.txt](https://wiki.crosswatch.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wiki.crosswatch.app/crosswatch/main-dashboard/tools/backup-and-restore.md).

# Backup & Restore

Back up selected CW data, keep encrypted additional copies, and recover safely.

Open **Tools → Backup & Restore** as an administrator to protect your CrossWatch application, trackers and saved captures.

The **Backups** view contains content selection and saved archives. Open its **Schedule & storage** tab for schedules, destinations and encryption. Existing Config, Normal and Full archives can still be imported and checked. Existing schedules keep their earlier scope until you select **Save settings** under **Schedule & storage → Automatic backups**.

### Choose what to back up

| Selection                  | Contents                                                                                                                                                                                    |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **CrossWatch application** | Settings, connections, sync state, mappings, blocks, custom anime rules, personal shelves and saved artwork choices with their images. Includes the local configuration key when available. |
| **CW trackers**            | Saved data for all trackers, or only the tracker instances you select, including collection copies and manual media info.                                                                   |
| **Saved captures**         | Capture files already saved in CrossWatch. Creating or restoring this backup does not fetch data from providers or apply captures to them.                                                  |

The selections appear directly under **What to back up** in the **Backups** tab. All three are initially enabled. To back up one tracker, enable **CW trackers**, clear **All trackers**, and select the instance. Clear the other content types if you only want that tracker.

This is a backup of selected CrossWatch data, not a copy of every file in `/config` or of your media libraries. Backup archives are stored locally under `/config/backups`. The separate [CW tracker archive](https://wiki.crosswatch.app/crosswatch/main-dashboard/navigation/cw-tracker.md#back-up-and-restore) remains available for portable tracker exports.

### Create a backup

1. In **Backups**, choose the data to include under **What to back up**.
2. Configure local encryption or an additional copy if wanted; see below.
3. Select **Back up now**. CrossWatch saves your selections and queues the backup.
4. Check the status and **Saved backups**. You can leave the page while the job runs. Return through **Tools → Backup & Restore** to see its current progress.

The status distinguishes a saved local backup from a verified additional copy. If an additional copy fails, the local backup remains available. Check the error, correct the connection and use **Retry**. Automatic retries are shown when scheduled; missing or unsupported rclone requires fixing the installation before retrying.

Saved backups show five archives per page. Use **Previous** and **Next** to browse them. Open an archive's **Details** for its **Download** and **Delete** actions.

**Download** saves a local archive to your device. **Delete** removes that local archive only; additional copies are kept separately. Wait for an active backup transfer to finish before deleting its local file.

### While a backup is running

**Back up now** changes to **Backup in progress…** while a job is queued, being created or being copied and verified at its destination. Wait for that job to finish before starting another backup or retrying a failed one.

Content and settings inputs, restoration and deletion actions are locked while a backup is active. You can still switch tabs, browse saved archives and download an existing local backup. Leaving and reopening the page does not cancel the job or unlock those actions.

After a restore is prepared for restart, **Restart pending** keeps backup and restore actions locked until CrossWatch restarts.

### Encryption and recovery keys

Local backups are unencrypted ZIP files unless **Encrypt local backups** is enabled under **Schedule & storage → Encryption → Edit encryption**. Select **Save encryption** to apply the change. Encrypted archives use `.cwbackup`. Additional copies are always encrypted, including copies to mounted folders.

Set a backup password of at least 12 characters, or select **Generate recovery key**. Save it outside CrossWatch and confirm that you have saved it before saving settings. An encrypted archive cannot be recovered without its password or recovery key after losing this installation. Keep earlier passwords for archives created before a password change.

{% hint style="warning" %}
An unencrypted application backup can contain both connection credentials and the key that unlocks them. Store it securely.

The backup password protects the archive. If your configuration uses `CW_CONFIG_KEY` or `CROSSWATCH_CONFIG_KEY`, you also need that original configuration key to restore application settings. It is not included in the archive. See [Config encryption](https://wiki.crosswatch.app/crosswatch/advanced-and-api/configuration-reference/config-encryption.md#backup-and-restore).
{% endhint %}

### Keep an additional copy

Open **Schedule & storage → Destination → Edit destination**. Choose **Nextcloud / WebDAV** or **Mounted folder (advanced)**, set the backup password or recovery key if needed, and select **Save destination**. Use **Test connection** to check an upload, download and checksum comparison before relying on it.

Additional copies require **rclone 1.76.0 or newer** on the CrossWatch host. Docker images built with the redesigned backup support include it. For other installations, install it where CrossWatch can run it.

#### Existing OneDrive or Dropbox plans

Direct OneDrive and Dropbox destinations are no longer supported. Existing plans continue saving local backups and show a notice. Choose a supported destination and create a new backup to resume additional copies. A queued job still targeting a removed destination keeps its local archive, reports the destination failure and stops automatic retries.

To recover an earlier cloud copy, download the archive from that service yourself, then use **Restore from file** with its backup password.

#### Nextcloud / WebDAV

Choose the server type and enter its **WebDAV URL**, **Username**, **App password** and **Backup folder**. Use the WebDAV endpoint supplied by your server, without credentials embedded in the URL. HTTPS is required unless you explicitly select **Allow HTTP for a trusted local server**.

#### Mounted folder

Mount a writable folder into the CrossWatch container, outside `/config`. Choose **Mounted folder (advanced)** and enter its path inside the container. The folder must already exist at `/backups` or below it. A custom allowed root can be set to an absolute directory path with `CW_BACKUP_ROOT`.

For example, add a bind mount from `/your/backup/folder` on the host to `/backups` in the container, then select `/backups` as the destination. This copy still requires rclone and is encrypted before transfer.

### Schedule backups

Open **Schedule & storage → Automatic backups → Edit schedule**. Enable **Back up automatically**, choose a **Time**, select the days under **Days**, and set **Automatic local copies to keep**. Select **Save settings**.

For a fresh setup, automatic backups are off, the time is **03:00**, all days are selected, and the interface offers **Latest 7** local copies. Local encryption is off. Existing settings are retained when present.

The schedule uses the main CrossWatch scheduling timezone, or the host/container timezone when none is configured. It is independent of Standard and Advanced sync plans. To stop it, disable **Back up automatically** here. Saving these settings switches an existing legacy schedule to your selected backup contents.

#### Retention rules

* Local automatic backups and additional automatic copies have separate count limits. The interface offers 7, 14, 30 or 60 copies; additional copies default to **Latest 30**.
* Automatic cleanup keeps manual, imported and safety backups. Delete these yourself when no longer needed.
* Older automatic archives from the existing default schedule remain subject to its local retention limit.
* Local retention continues even if the destination is unavailable. Additional-copy retention runs only after a new copy is verified.
* If a failed job's local archive expires or is deleted, create a new backup instead of retrying that job.

### Restore a backup

#### Open and check the archive

* **Saved backups:** select **Restore** on the archive.
* **A file on your device:** select **Restore from file**, choose a `.zip` or `.cwbackup` file, enter its password if encrypted, then select **Import and review**. Uploads are limited to 2 GB.
* **An additional copy:** in **Backups**, select **At destination**, then **Download to CW**. Use **Previous** and **Next** to browse destination archives; select **On this server** to return to local backups. On a replacement installation, configure the destination first.

In **Review restoration**, start with **Backup details**. Enter the backup password if needed and select **Check backup**. CrossWatch checks archive contents, checksums and database integrity.

After **Backup checked** appears, review **Included in this backup** and choose the available **Restore options**. Restore options appear only after the check succeeds. A tracker created by a newer, incompatible CrossWatch version must be restored with a compatible version.

#### Choose the restore action

Only actions supported by the archive are offered:

| Restore action                            | What happens                                                                                                                                                        |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Recover one tracker as a new instance** | Choose the saved tracker and a new name, then select **Recover tracker**. Your existing tracker stays in place. No sync pairs are created and no restart is needed. |
| **Mappings and blocks only**              | Replace the saved mapping rules and blocks while retaining other current application data.                                                                          |
| **Custom anime rules only**               | Replace custom anime rules with those from the backup.                                                                                                              |
| **Saved captures only**                   | Restore saved capture files, replacing files with matching names. This does not apply them to providers.                                                            |
| **Replace the data in this backup**       | Replace the application, tracker or capture data included in the archive. Unrelated files are not removed.                                                          |

Tracker recovery is selected by default when the archive contains tracker recovery information. Review the choice before proceeding. Older archives may offer fewer recovery actions.

For any replacement action, confirm the selection and choose **Restore and restart**. Wait for active backup transfers to finish first. CrossWatch saves a safety copy and applies the replacement during restart. If replacement fails or is interrupted, it restores the original files. Reopen CrossWatch to check the result; your container or service manager must start it again.

{% hint style="info" %}
After recovering a tracker as a new instance, inspect its data before creating sync pairs. Recovery itself does not send data to connected providers.
{% endhint %}

### Related pages

* [Maintenance](https://wiki.crosswatch.app/crosswatch/settings/maintenance.md)
* [CW Tracker](https://wiki.crosswatch.app/crosswatch/main-dashboard/navigation/cw-tracker.md#back-up-and-restore)
* [Scheduling](https://wiki.crosswatch.app/crosswatch/settings/scheduling.md)
* [Backup CLI commands](https://wiki.crosswatch.app/crosswatch/command-line-interface-cli.md#captures-and-backups)
* [Config encryption](https://wiki.crosswatch.app/crosswatch/advanced-and-api/configuration-reference/config-encryption.md)

### Check backup activity

Administrators can open **Tools → Events → Backups** for manual, scheduled and automatic backup results, destination-copy outcomes and retention cleanup. Check the local backup and copy outcomes separately: a failed copy does not necessarily mean the local backup failed. Use Backup & Restore to inspect, download or restore the actual archive. See [Events](https://wiki.crosswatch.app/crosswatch/main-dashboard/tools/events.md#captures-and-backups).

For the detailed log, select **View logs** on an event when available, or open **Tools → Logs → Backups**. Use **Copy full log** or **Download .log** to share the retained session with its report header.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://wiki.crosswatch.app/crosswatch/main-dashboard/tools/backup-and-restore.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
