Backups and Recovery
Backups save and stop the game, create an archive, and restart the game. Players are disconnected during a backup. Autosave writes the live world in place and does not create an archive.
Open Backups & recovery in the dashboard and request a backup. Follow its status and confirm the server becomes healthy afterward.
Use Back up now to create an archive. Expand an archive for details and use Inspect & verify to check its contents. This September 22 screenshot shows the 3.4.1 interface with a demonstration archive. Select it to view full size.
From the Docker host:
docker compose exec --user tml:tml -T tmodloader tmod-backup backupThe supplied Compose deployment stores archives in ./backups. Keep another copy on separate storage.
Each backup is a bundle directory containing manifest.json and data.tar.gz. Copy the whole bundle when moving backups; verification and restore require both files.
/backups must be a separate writable mount outside /data, as in the supplied Compose file. Backups reject symbolic links, special files, and nested filesystem mounts within the data being archived. Restore also needs enough free space in /data to stage the restored files alongside the originals.
| Setting | Default | Meaning |
|---|---|---|
TMOD_BACKUP_INTERVAL |
0 |
Minutes between backups; 0 disables scheduling |
TMOD_BACKUP_KEEP |
7 |
Verified backup bundles retained for this data directory and current build |
TMOD_BACKUP_MIN_FREE_MB |
1024 |
Minimum available space in MiB before beginning a backup |
TMOD_AUTOSAVE_INTERVAL |
10 |
Minutes between live saves; 0 disables scheduled autosaves |
Set the backup interval to 1440 for approximately one backup every 24 hours. This is an interval, not a fixed time-of-day schedule; container startup or a manual backup resets it.
Retention cleanup happens after a successful backup and restart. It preserves archives from other container builds and does not prune retained recovery originals, so total storage can exceed the configured archive count. The free-space threshold is a reserve check, not an estimate of the required archive size.
Select an archive name to expand its backup date, world files, last running world when recorded, enabled mods, Workshop selections, file counts, sizes, included settings/logs, and runtime compatibility. Inspect & verify checks the checksum and actual archive contents, including older bundles without a recorded summary. Inspection progress and errors appear beside the archive.
Check the world-identification source: a newer backup can record Running settings at backup, while an older backup may only report Saved world selection (running world unconfirmed). A saved selection is not proof that the world was running when the archive was made.
Since 3.4.0, new backups record the actual selected tModLoader runtime, which can differ from the runtime originally bundled in the image. Compare this runtime when inspecting compatibility; an image tag alone no longer identifies the running game version.
Runtime caches and update checkpoints under /data/.tmod-control/updates are excluded from ordinary archives. Keep an independent data-volume backup for disaster recovery. Runtime checkpoint rollback is a separate workflow from archive restore; see Recover a runtime checkpoint. The dashboard-saved Workshop key is also excluded from container backups and may need to be entered again after recovery.
After inspection, Prepare for Running Container Version appears when the archive uses the same selected tModLoader release as the running server but a different container build. Confirming creates and verifies a separate bundle for the current build, preserving the original archive and the archived world data. The copy records which archive it came from and when it was prepared. Allow enough backup storage for the copy plus the configured free-space reserve.
This does not convert between game releases. Different or unknown tModLoader versions require the matching original image/runtime environment; an image alone may not reproduce a runtime selected by the updater. If recorded tModLoader binary hashes differ, preparation is also rejected even when the version labels match. Inspect an older archive first to recover any available version information.
- Open Backups & recovery, expand the intended archive, and use Inspect & verify.
- For a compatible archive, choose Restore this backup inside its expanded details. If needed, prepare a compatible copy first and inspect that copy.
- The Review Restore popup verifies the archive and available space. Check the preview, then choose Confirm restore. The game stops while data is replaced.
- Follow recovery progress and verify the resulting world and server health.
Restore checks the container build fingerprint. Keep the original image version or digest: an archive from another build requires a verified compatible copy or its original image. If the archive changes after inspection or preview, repeat that check before continuing. Opening the review popup does not itself restore data.
Review the verified archive and storage checks before confirming. This September 16 local preview screenshot only shows the review; no restore was performed.
The dashboard restore preserves the current admin credential. Original data is retained under /data/.tmod-control/before-restore-*; this is recovery material that consumes space, not part of normal archive retention.
Inspect the recovery status and logs. Use the dashboard startup retry after correcting the reported startup problem.
If /data/.tmod-control/restore-pending exists, a restore was interrupted. Keep the game stopped and preserve that marker and the retained original directory for manual recovery. Do not remove the marker simply to force startup; it guards partially replaced data.
Keep separate copies of .env, the Compose file, external secrets, and custom configuration files. Container backups do not include those external deployment files. See Updates and storage for persistent-folder handling.