How backups work

This article explains how Architect Agent creates, stores, lists and restores server backups. For the Manager UI overview, see Backup Management.

Backups must be enabled per server under Configuration, Server Operations. If backups are disabled, the Agent does not create automatic or at-startup backups.

What is included

Each backup is built from:

Each configured path becomes its own `.zip` archive inside the backup record. A folder named `mpmissions` is stored as `mpmissions.zip`, not as loose files.

Storage layout

Local backups are written under the Agent backups directory (next to `deployments` by default):

backups/<server_id>/<timestamp>/

`` is a UTC Unix timestamp in milliseconds and is also the backup id in the database.

Optional S3 (or S3-compatible) backup targets are supported. In that case the Agent still builds the archives locally first, uploads them, then removes the temporary local copy. The backup metadata remains in the Agent database so Manager can list and restore those backups.

Archive format and size

Backups are packaged as ZIP files using store mode. Files are archived, but not compressed.

That means:

- On-disk backup size is roughly the same as the size of the selected source files
- Large worlds, mission folders or log trees produce large backups
- Frequent intervals multiply that disk usage quickly

Plan free disk space for at least one full copy of every path you include, plus headroom for several keep periods. At-startup backups of multi-GB trees are a common cause of long starts and full disks.

`original_size` and `compressed_size` in backup details both reflect the archived payload. Because store mode is used, they are typically very close.

When backups run

While a backup runs, server status may show `current_procedure` as `backup`.

Force-kill during an in-flight at-startup backup cancels the zip work and abandons that backup record so the start can finish cleaning up. Manual and scheduled backups are not tied to that abort path.

Locked files and VSS (Windows)

By default the Agent zips directly from the live server files. Files that cannot be opened (for example locked by a running process) are skipped.

On Windows you can opt into Volume Shadow Copy:

[filesystem]
backups_vss = true

Requires an Agent restart. See Configuration.

Partial success

Backup entries are processed with limited parallelism. If some paths fail and others succeed, the Agent keeps the successful entries and still creates a backup record. If no entry succeeds, the backup fails.

Always check backup details after large or first-time backups to confirm the paths you care about were actually archived.

Listing backups

Manager lists backups newest first. The Agent caps list responses (100 newest) and default query pages (50) so large histories do not stall the Agent. Older backups remain on disk or on the remote target until deleted or cleaned up by Maximum Keep Time.

Restore

Restore is available from the Backups tab.

Important notes:
- The server must not be running, starting or stopping
- Existing files at the original paths are removed, then replaced from the archive
- Restricted paths enforced by the Agent are skipped
- Remote-target backups are downloaded to a temporary folder, restored, then cleaned up

Restoring a backup will fully overwrite the restored files or folders.

Practical recommendations

- Prefer narrow `filelist` paths (world / save / config) over entire server trees
- Avoid backing up cache, steamcmd leftovers or huge log folders unless you need them
- Keep Maximum Keep Time enabled on busy servers
- Treat at-startup backups of multi-GB paths as a deliberate choice; they delay every start
- On Windows, enable `backups_vss` only when you need consistent running-server backups of locked files
- After changing Agent `config.toml`, restart Architect Agent

Related configuration (server)