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

# Backup & Restore

> Take encrypted, verifiable backups of the appliance and restore them onto a fresh, reset, or existing box. Backups are age-encrypted; the private key never lives on the appliance.

The appliance produces a single **encrypted, self-describing backup bundle** you can restore onto a **fresh** appliance, a **factory-reset** appliance, or the **same** appliance in place. Backups are encrypted with [age](https://age-encryption.org); the appliance only ever holds the **public recipient**, so a backup at rest can never be decrypted from the appliance alone.

<Info>
  A backup captures the **durable** state needed to reconstitute the deployment:
  the application database, the durable crypto (the master key and secret-box key
  that wrap your data-encryption keys), and appliance configuration. Ephemeral
  infrastructure secrets are regenerated on restore, which is what lets one bundle
  restore cleanly onto a different box.
</Info>

## What's protected

* **Application database** — tenants, org structure, rooms, file metadata, audit log, policies.
* **Durable key material** — the master key and secret-box key (envelope-wrapped), so restored data remains decryptable with your KMS/keys.
* **Appliance configuration** — the settings needed to bring the platform back up.

Encrypted file *content* lives in your configured object storage / KMS, not in the bundle — point the restored appliance at the same storage and KMS and it reconnects to your data.

## Create a backup

<Tabs>
  <Tab title="Admin UI">
    **Admin → Backup & Restore → Create backup.** The bundle is produced on the appliance and listed for download.
  </Tab>

  <Tab title="Console">
    ```bash theme={null}
    backup                 # create a backup into the local backup directory
    backup status          # show the last backup's timestamp and result
    ```
  </Tab>
</Tabs>

The bundle is named `enclave-backup-<timestamp>.tar.age`. On a cluster, backups run on the **primary** (a replica reports that the primary's schedule already covers it).

## Schedule automatic backups

<Tabs>
  <Tab title="Admin UI">
    **Admin → Backup & Restore → Schedule** — enable and pick a cadence.
  </Tab>

  <Tab title="Console">
    Scheduling is applied via the GUI schedule (a systemd timer under the hood). Enable it and set the `OnCalendar` cadence there.
  </Tab>
</Tabs>

## Verify a backup

Always confirm a backup is intact and restorable **before** you rely on it:

<Tabs>
  <Tab title="Admin UI">
    **Admin → Backup & Restore →** the backup's **Verify** action.
  </Tab>

  <Tab title="Console">
    ```bash theme={null}
    backup verify enclave-backup-<timestamp>.tar.age
    ```
  </Tab>
</Tabs>

Verification checks the bundle's integrity and its manifest/version so a corrupt or incompatible archive fails **loudly** rather than at restore time.

## Copy backups off-box

Keep copies off the appliance so a lost box doesn't lose the backups. Configure an off-box target (SCP or a mounted directory) and test reachability:

<Tabs>
  <Tab title="Admin UI">
    **Admin → Backup & Restore →** configure the off-box destination, then **Test** the connection.
  </Tab>

  <Tab title="Console">
    ```bash theme={null}
    offbox test           # non-destructive reachability check of the configured target
    ```
  </Tab>
</Tabs>

<Warning>
  Store the **age private key (identity)** for your backups somewhere safe and
  off-box — a KMS, secrets manager, or sealed escrow. Without it a backup cannot
  be decrypted, and the appliance deliberately never keeps it.
</Warning>

## Restore

Restoring **overwrites** the target appliance's data with the backup's contents, then reboots.

<Steps>
  <Step title="Start from a clean target">
    Deploy a fresh appliance (or factory-reset an existing one). Complete just enough of first-run to reach the admin UI.
  </Step>

  <Step title="Upload the backup + identity">
    **Admin → Backup & Restore → Restore.** Upload the `.tar.age` bundle and, when prompted, the **age identity (private key)** used to encrypt it. The identity is used only for this restore and is **shredded** immediately afterward — it is never stored at rest.
  </Step>

  <Step title="Confirm and reboot">
    Confirm the overwrite. The appliance restores the database + durable keys, regenerates ephemeral infrastructure secrets, and reboots. A pre-restore **safety snapshot** is taken first, so a mistaken restore is recoverable.
  </Step>

  <Step title="Reconnect storage and KMS">
    Point the restored appliance at the **same object storage and KMS** as the original so it reconnects to your encrypted file content and key material.
  </Step>
</Steps>

Console equivalent:

```bash theme={null}
backup verify enclave-backup-<timestamp>.tar.age    # verify first
restore enclave-backup-<timestamp>.tar.age          # prompts for the age identity; reboots when done
```

<Note>
  **On a cluster,** restore is a **standalone** operation. Restore onto a fresh
  single appliance and then re-form the cluster from it, or roll a node back to
  standalone first. Do not restore into a live cluster member — see
  [High availability & clustering](/enclave/appliance/clustering).
</Note>

## Recovery model at a glance

| Scenario                                     | How                                                                         |
| -------------------------------------------- | --------------------------------------------------------------------------- |
| **Fresh box** (hardware loss / migration)    | Deploy new appliance → restore → reconnect storage/KMS                      |
| **Factory reset** (start over, keep the box) | Reset → restore                                                             |
| **In-place** (roll back a bad change)        | Restore on the same appliance; the safety snapshot guards the current state |

## Next steps

<CardGroup cols={2}>
  <Card title="Key Management" icon="key" href="/enclave/appliance/kms">
    The KMS the restored appliance must reconnect to for file decryption.
  </Card>

  <Card title="Storage" icon="database" href="/enclave/appliance/storage">
    The object storage that holds your encrypted file content.
  </Card>
</CardGroup>