Skip to main content
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

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

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.
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.
For a clean physical database backup, stop the database and verify it is stopped before capture:
This interrupts clients. A running file-level capture is at best crash-consistent. For a logical online capture, use database dumps 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:
backup-retention.toml
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

1

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.
2

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, 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.
3

Restore one selected archive

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.
4

Restore managed volumes before startup

For each matching physical database backup:
The manifest identifies the target database. Restore other application data separately, with writers stopped. The control-plane archive alone cannot recreate missing database contents.
5

Start and verify

Start through the service manager, then run:
Open each important application, test a representative data read, and check certificate trust. Re-link through the App if needed. Diagnose unavailable resources before changing or deleting their restored state.
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.