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

# Back up and recover

> Protect Engine identity, credentials, application data, and managed databases with the right backups.

There is no single archive that backs up an entire machine. Plan recovery for Engine metadata, encrypted secrets, database contents, ordinary application volumes, source/images, and model weights separately.

## What each backup protects

| Backup                            | Contains                                                                                                                            | Does not replace                                                                              |
| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| `nerdit backup`                   | Consistent Engine SQLite snapshot, secrets master key and encrypted secrets, available Caddy CA/certificates/ACME account material. | Database or application data backups; configuration and node-link identity preservation.      |
| `nerdit backup --volume DATABASE` | Managed database data directory and its on-disk credential material.                                                                | Engine metadata/secrets backup; application-consistent capture while the database is running. |
| `nerdit db dump DATABASE`         | Logical PostgreSQL or Redis data captured by the engine.                                                                            | Full Engine recovery or exact physical database replacement. Current merged source only.      |

Control-plane backup excludes ordinary application volumes, model weights, uploads, logs, audit archives, node-link private key, and an optional offline product-license file. Preserve Engine configuration separately in protected storage. After rebuilding a machine, plan to re-link its account connection and reinstall any applicable offline entitlement.

## Take and store backups

```bash theme={null}
nerdit backup
```

Read the returned archive location on the Engine machine. Copy the archive to protected storage on another machine or offline media, verify the copied file, then remove unnecessary local copies.

<Warning>
  A control-plane archive contains the secrets master key and unencrypted TLS private keys. Anyone holding it can decrypt the stored secrets and impersonate the node's TLS identity. There is no built-in backup passphrase. Protect archives with restrictive permissions and encryption at the storage layer.
</Warning>

For a clean physical database backup, stop the database and verify it is stopped before capture:

```bash theme={null}
nerdit services stop main-db
nerdit services list
nerdit backup --volume main-db
nerdit services restart main-db
nerdit services wait main-db --timeout 300
```

This interrupts clients. A running file-level capture is at best crash-consistent. For a logical online capture, use [database dumps](/engine/databases#logical-dumps-and-live-restore) when running a source version that provides them. Every logical dump holds the database's records, even though it excludes the secrets master key.

Back up ordinary application volumes with a tool appropriate to the application. Stop or quiesce writers where consistency requires it. Keep enough information to rebuild application images and re-download model weights.

## Configure retention

Control-plane and physical volume backups are retained indefinitely by default. Configure a limit deliberately:

```toml backup-retention.toml theme={null}
[retention]
backup_keep_last = 3
volume_backup_keep_last = 3
```

```bash theme={null}
nerdit config apply backup-retention.toml --dry-run
nerdit config apply backup-retention.toml
nerdit daemon restart
nerdit disk
```

Zero means no pruning. Retention does not create off-machine copies or prove they can be restored. Rehearse recovery in an isolated environment before relying on a backup.

## Restore the control plane offline

<Steps>
  <Step title="Prepare the target">
    Use a compatible Nerdit version and restore the protected Engine configuration, including the original data directory and any `secrets_key_file` override. Run restore as the service user whose configuration points to that directory. Preserve current state before replacing it.
  </Step>

  <Step title="Stop the managed Engine">
    First stop every application or database container that writes to data you will restore. Use `nerdit services stop NAME` while the Engine is available, then verify each writer is stopped with `nerdit services list`. On a damaged target, an operator must stop the affected containers directly. Stopping the Engine alone leaves application and database containers running.

    Then use the [platform service manager](/engine/installation#files-and-service-management), for example `sudo systemctl stop nerdit.service` on a Linux system installation. Confirm it has stopped and keep all writers stopped until data restoration is complete. Do not use `nerdit init` to restart an installed Engine, or restore into a live data directory. The Engine's restore lock does not exclude an independently running database container.
  </Step>

  <Step title="Restore one selected archive">
    ```bash theme={null}
    nerdit restore /path/to/SELECTED_CONTROL_PLANE_ARCHIVE.tar.gz
    ```

    Inspect the archive contents summary and confirmation. Use one exact filename, not a wildcard matching multiple backups. Restore checks its manifest, archive member types/paths, permissions, and an exclusive data-directory lock.
  </Step>

  <Step title="Restore managed volumes before startup">
    For each matching physical database backup:

    ```bash theme={null}
    nerdit restore --volume /path/to/SELECTED_VOLUME_ARCHIVE.tar.gz
    ```

    The manifest identifies the target database. Restore other application data separately, with writers stopped. The control-plane archive alone cannot recreate missing database contents.
  </Step>

  <Step title="Start and verify">
    Start through the service manager, then run:

    ```bash theme={null}
    nerdit doctor
    nerdit services list
    nerdit db list
    ```

    Open each important application, test a representative data read, and check certificate trust. Re-link through the [App](/app/) if needed. Diagnose unavailable resources before changing or deleting their restored state.
  </Step>
</Steps>

Offline restore is a host-local operation. It ignores the CLI's remote connection and does not restore a remote machine over HTTP. There is no control-plane restore API or MCP tool; the backup API returns metadata only.

## Recover an interrupted restore

If control-plane restore was interrupted, keep the Engine stopped and rerun **the same archive**. This completes the key/ciphertext/database replacement consistently. Do not rotate the secrets key or initialize an empty Engine as a substitute.

Caddy trees present in the archive replace the corresponding live trees. Trees absent from an older archive are preserved. Restoring certificate and ACME account state avoids unnecessary reissuance; check expiry and network reachability before declaring HTTPS recovered.

For a source-only Redis logical restore, the old append-only directory is retained as `appendonlydir.pre-restore-<stamp>`. An interruption between renames may require an operator to finish the swap offline. Preserve both directories and stop the database before inspecting them; do not delete the retained original while diagnosing recovery.

The restore lock relies on `flock`; do not place the data directory on NFS if you depend on its exclusion guarantees. Native Windows restore is unsupported; use Linux, macOS, or WSL2.