> ## Documentation Index
> Fetch the complete documentation index at: https://doc.trycapsule.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Backup & Restore

> How to trigger backups, download decrypted copies, and restore databases from the CLI and dashboard.

## On-demand backup

```bash theme={null}
capsule
```

Use arrow keys to select your connection and press Enter, then choose **Backup now**. Capsule runs the backup immediately, encrypts it on your server, and uploads the result to your dashboard.

You can also trigger on-demand backups from the [web dashboard](https://trycapsule.xyz/dashboard/backups) without touching the CLI.

**When to use:** Any time you want a snapshot before a risky change — a schema migration, a deployment, a bulk delete — and you don't want to wait for the next scheduled backup to fire.

***

## Scheduled backups

Backups run automatically according to the schedules you configure. See [capsule schedule](/cli/schedule) for setup.

The Capsule service must be running for scheduled backups to fire. Check with:

```bash theme={null}
systemctl is-active capsule
```

**When to use:** Set these up once per connection during initial setup. Scheduled backups are the backbone of your data safety — on-demand backups are a supplement, not a replacement.

***

## Restore

There are several ways to restore, covered in detail below. Most people only ever need the first one — start here and only read further if your situation doesn't match:

| Situation                                                       | Method                                                                                                                                                                                 |
| --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Rolling back the same server                                    | TUI or dashboard restore                                                                                                                                                               |
| Restoring from a different machine                              | Dashboard restore                                                                                                                                                                      |
| Cross-environment restore (prod → staging)                      | `capsule download` + `capsule restore --file`                                                                                                                                          |
| Offline / air-gapped recovery                                   | `capsule download` on a server with the key, then `capsule restore --file`                                                                                                             |
| Need to inspect SQL before restoring                            | `capsule download`, unzip, review, restore                                                                                                                                             |
| **Replacing a server entirely (old one won't exist afterward)** | `capsule key show` on the old server **first**, then `capsule auth --restore` on the new one — see [migrating to a new server](#migrating-to-a-new-server-decommissioning-the-old-one) |

### From the TUI

```bash theme={null}
capsule
```

Select your connection → **Backups** → select a snapshot → **Restore**.

Capsule will:

1. Download the encrypted backup from the cloud
2. Verify the SHA-256 checksum
3. Decrypt it locally using your server's encryption key
4. Pipe it into your database using the native restore tool (`psql`, `mysql`, `mongorestore`)

**When to use:** When you need to roll back the same server that originally took the backup. This is the standard disaster recovery path.

<Warning>
  Restoring overwrites the current contents of the target database. Capsule will ask you to confirm before proceeding.
</Warning>

### From the dashboard

Open your [dashboard](https://trycapsule.xyz/dashboard/backups), find the backup you want to restore, and click **Restore**. The dashboard sends a signal to the agent running on your server — the restore runs locally, never through Capsule's servers.

**When to use:** When you prefer a GUI, or when you want to trigger a restore on your server from a different machine.

### From a local file (`capsule restore --file`)

Restores a database directly from a local `.sql.gz` file (typically produced by `capsule download`). No cloud connection is required — the file is piped straight into the target database.

**If you have only one connection configured:**

```bash theme={null}
capsule restore --file ./backup.sql.gz
```

`--connection` can be omitted. Capsule selects your one connection automatically — you'll see `Using connection: <label>` printed before the confirmation prompt.

**If you have more than one connection configured:**

```bash theme={null}
capsule restore --file ./backup.sql.gz --connection staging-db
```

`--connection <label>` is now required. Capsule never guesses or falls back to "the first one" — omit it here and the command lists every connection you have and exits with an error instead of restoring, so nothing is overwritten by accident.

**When to use:**

* You used `capsule download` to get a decrypted copy and want to restore it locally or on a different server
* Cross-environment restore (production backup → staging database)
* Air-gapped or offline recovery where the cloud is not reachable
* You want to inspect the SQL before restoring (unzip the `.sql.gz`, review, re-zip, then restore)

**Flags:**

| Flag                 | Description                                                             |
| -------------------- | ----------------------------------------------------------------------- |
| `--file`, `-f`       | Path to the `.sql.gz` backup file (required)                            |
| `--connection`, `-c` | Connection label to restore into (required when you have more than one) |

***

## Download and decrypt a backup (`capsule download`)

```bash theme={null}
capsule download <backup-id>
capsule download <backup-id> --output ./mybackup.sql.gz
```

Downloads an encrypted backup from cloud storage, decrypts it using your server's local encryption key, and saves it as a standard `.sql.gz` file you can open, inspect, or restore anywhere.

**When to use:**

* You need a readable copy of your data outside of Capsule — importing into a local dev environment, sharing with a colleague, or loading into a data analysis tool
* You're migrating to a different server and want to seed the new database from an existing backup
* You want to restore a backup on a machine that is not running the Capsule agent (e.g. a local laptop)
* You want to archive a specific snapshot to cold storage or an external system

<Info>
  The `.enc` file you can download from the dashboard is encrypted and not directly usable. `capsule download` is the command that gives you the plain, readable `.sql.gz`.
</Info>

**Typical workflow:**

```bash theme={null}
# 1. Get the backup ID from the dashboard or the backups list
capsule download fd2849ca-c994-4ca0-b220-3979180272c6

# Saved: /home/you/fd2849ca-c994-4ca0-b220-3979180272c6.sql.gz
# Restore with: capsule restore --file "/home/you/fd2849ca-c994-4ca0-b220-3979180272c6.sql.gz"

# 2. Restore to any connection
capsule restore --file fd2849ca-c994-4ca0-b220-3979180272c6.sql.gz --connection staging-db
```

**Flags:**

| Flag             | Description                                                               |
| ---------------- | ------------------------------------------------------------------------- |
| `--output`, `-o` | Output file path (default: `<backup-id>.sql.gz` in the current directory) |

<Warning>
  `capsule download` must be run on the same server that took the backup, or any server that has imported the same encryption key via `capsule auth --restore`. Running it on a server with a different key will fail at decryption.
</Warning>

***

## Migrating to a new server (decommissioning the old one)

Everything above assumes the server that originally took the backup is still alive and reachable. If you're replacing that server entirely — the old one is being wiped, returned, or shut down for good — that assumption breaks, because **the encryption key lives only on the server that generated it**, not in Capsule's cloud. Without it, on any machine, existing backups are permanently unreadable — Capsule itself cannot recover a lost key.

This means server migration has an extra step that's easy to miss, and has to happen **before** the old server is gone:

1. **On the old server, before decommissioning it:** save the encryption key.
   ```bash theme={null}
   capsule key show
   ```
   Copy the 64-character key it prints into a password manager or secrets vault. See [`capsule key`](/cli/key) for the full explanation of why this matters and how to store it safely.

2. **On the new server:** install Capsule as normal, then import the saved key instead of generating a new one.
   ```bash theme={null}
   capsule auth --restore
   ```
   This prompts for your license key, then for the saved encryption key (input hidden). Once it completes, the new server can decrypt every backup the old one ever took. Full walkthrough, including the exact prompts you'll see: [`capsule auth` — disaster recovery](/cli/auth#disaster-recovery).

3. **Now** you can download and restore normally — `capsule download <backup-id>` and `capsule restore --file` both work on the new server exactly as they did on the old one, because it holds the same key.

<Warning>
  If you skip step 1 and the old server is already gone, there is no recovery path — not through support, not through the dashboard. The key is never sent to Capsule's servers in any form, by design (that's what "zero-knowledge" means here). Save it *before* you decommission anything, not after.
</Warning>

**When to use:** Replacing a server outright — a hardware refresh, moving providers, or rebuilding from scratch — where the original machine won't exist afterward.

***

## Restore to a different host (source server still exists)

To copy a specific snapshot onto a different server or database instance, while the original server is still alive and reachable:

1. Run `capsule download <backup-id>` on the server that has the encryption key
2. Copy the resulting `.sql.gz` to the target server (via `scp`, a shared volume, etc.)
3. On the target server, run `capsule restore --file ./backup.sql.gz --connection <target>`

The target server doesn't need the encryption key for this — the file is already decrypted by the time it gets there. Compare this with [migrating to a new server](#migrating-to-a-new-server-decommissioning-the-old-one) above: that's for when the *source* server won't exist anymore either, which needs the key itself to move, not just one decrypted file.

**When to use:** Seeding a staging environment from a production backup, or testing a restore on a separate machine before doing it in production — the original server keeps running either way.

***

## How backups are stored

| Property   | Detail                                                          |
| ---------- | --------------------------------------------------------------- |
| Encryption | AES-256-GCM, encrypted on your server before upload             |
| Integrity  | SHA-256 checksum verified on every backup and restore           |
| Format     | Compressed dump (`pg_dump`, `mysqldump`, `mongodump --archive`) |
| Storage    | Capsule-managed encrypted cloud storage                         |
| Retention  | Determined entirely by your plan — see below                    |

**Plan retention periods** — every backup gets an expiry date based on your plan at the time it was created; a background worker deletes it once that date passes:

| Plan     | Backups kept for |
| -------- | ---------------- |
| Hobbyist | 3 days           |
| Solo     | 10 days          |
| Pro      | 30 days          |
| Team     | 120 days         |

If you upgrade or downgrade, existing backups' expiry dates are recalculated against the new plan automatically — you don't need to do anything for the new retention period to apply.

***

## See also

* [`capsule key`](/cli/key) — save your encryption key before decommissioning a server, and understand what happens if it's lost
* [`capsule auth`](/cli/auth#disaster-recovery) — the full `--restore` flow for importing a saved key onto a new server, with exact prompts and output
* [`capsule download`](/cli/download) — download and decrypt a specific backup by ID
* [`capsule backup list`](/cli/backup-list) — find a backup's ID before downloading it