Backups
Cloud OS includes a built-in backup engine that supports local, S3-compatible, and SFTP storage targets. All backups are encrypted with AES-256-GCM using Argon2 key derivation and can be scheduled via cron expressions. A restore wizard guides you through recovering data from any backup.
Backup Targets
Configure one or more backup targets under Backups > Targets. Each target defines where backup data is stored.
Local Directory
Store backups on a local or mounted directory. This works well for attached USB drives or NAS mounts.
| Setting | Description |
|---|---|
| Path | Absolute path on the host filesystem (e.g., /mnt/backups) |
| Retention | How many backups to keep |
Amazon S3 / S3-Compatible
Works with AWS S3, MinIO, Wasabi, Backblaze B2, and Cloudflare R2.
| Setting | Description |
|---|---|
| Endpoint | S3 endpoint URL (leave empty for AWS) |
| Region | AWS region (e.g., us-east-1) |
| Bucket | Bucket name |
| Access Key ID | S3 access key |
| Secret Access Key | S3 secret key |
| Path Prefix | Optional prefix for organizing backups |
SFTP
Send backups to any remote server over SFTP.
| Setting | Description |
|---|---|
| Host | SFTP server hostname or IP |
| Port | SSH port (default: 22) |
| Username | SSH username |
| Auth Method | Password or private key |
| Remote Path | Directory on the remote server |
Encryption
All backups are encrypted at rest using AES-256-GCM with key derivation via Argon2. Encryption is always enabled — there is no option to create unencrypted backups. The encryption key is derived from your Quazzar instance configuration, so backups can only be restored on the same instance or with the original encryption passphrase.
Store your encryption passphrase in a safe place. Without it, encrypted backups cannot be restored if you lose the original server.
Scheduling Backups
Navigate to Backups > Schedule to set up automatic backups. Schedules use cron-style expressions for precise timing control:
| Schedule | Cron Expression | Description |
|---|---|---|
| Hourly | 0 * * * * | Runs at the start of every hour |
| Daily | 0 2 * * * | Runs at 2:00 AM each day |
| Weekly | 0 2 * * 0 | Runs at 2:00 AM every Sunday |
| Monthly | 0 2 1 * * | Runs at 2:00 AM on the 1st of each month |
You can create custom cron expressions for any schedule you need. Multiple schedules can target different backup destinations. For example, daily backups to local storage and weekly backups to S3.
Retention Policies
Each schedule has a retention policy to control how many backups are kept:
- Keep last N — retain the N most recent backups
- Keep daily for N days — keep one backup per day for N days
- Keep weekly for N weeks — keep one backup per week for N weeks
Older backups are automatically deleted when the retention limit is reached.
Creating a Manual Backup
- Go to Backups
- Click Backup Now
- Choose the scope:
- Full system — all apps, Cloud OS configuration, and database
- Per-app — select specific apps to back up
- Select a target
- Click Start Backup
The backup progress is shown in real time. A full system backup typically takes a few minutes depending on total data volume.
What Gets Backed Up
| Scope | Includes |
|---|---|
| Full system | All app data volumes, Docker Compose configs, Cloud OS SQLite database, system settings, user accounts |
| Per-app | The app data volumes, Docker Compose config, and environment variables |
Restore Wizard
- Go to Backups > History
- Find the backup you want to restore and click Restore
- The restore wizard guides you through three steps:
- Step 1 — confirm the backup date and contents
- Step 2 — select which apps to restore (for full-system backups, you can choose individual apps)
- Step 3 — confirm the restore operation
- Click Restore to begin
Restoring replaces the current app data with the backup contents. Running containers for the affected apps will be stopped and restarted during the restore process.
Verification
Each backup includes a SHA-256 checksum that is verified automatically before restore. If the checksum does not match (indicating data corruption), the restore is aborted with an error message.
You can also run manual verification on any backup from the history page to confirm its integrity without performing an actual restore.
Backup Verification
Cloud OS can verify the integrity of your backups to ensure they are restorable when you need them.
Backup verification requires the backup_verification license feature (Pro+ plan).
Verification Checks
Each verification runs these checks:
| Check | Description |
|---|---|
| Integrity | Verifies the checksum/hash matches the stored value |
| Size | Confirms the backup file is non-empty and within expected range |
| Dry-Run Restore | Optionally restores the backup to a temporary directory and verifies the data structure |
| Staleness | Alerts if the last successful backup exceeds the configured threshold |
Running a Verification
- Navigate to Backups from the sidebar
- Find the backup you want to verify
- Click Verify (or use the verification dialog)
- The verification runs asynchronously — you can check the status later
Backup Health Overview
The backup health endpoint provides an at-a-glance view of your backup status: last successful backup times, any staleness warnings, and overall health score.
Verification API
| Endpoint | Method | Description |
|---|---|---|
/api/backups/{id}/verify | POST | Start verification (returns job ID) |
/api/backups/{id}/verify/status | GET | Get verification result |
/api/backups/health | GET | Overall backup health summary |
Troubleshooting
Backup fails with “permission denied”
For local targets, ensure the Quazzar process has write access to the backup directory. For SFTP, verify the SSH credentials and that the remote directory exists.
S3 backup fails with “access denied”
Check that the access key has s3:PutObject, s3:GetObject, and s3:ListBucket permissions on the target bucket. For S3-compatible services, verify the endpoint URL is correct.
Restore takes a long time
Large backups (especially media apps like Jellyfin or Immich) can take significant time to restore. The progress indicator shows the current step. Do not interrupt the restore process.
Encrypted backup cannot be restored
This usually means the encryption key has changed. If you reinstalled Cloud OS on a new server, you need the original encryption passphrase to restore old backups.