Backup System

Backups capture server state as zip archives stored on the node (or S3 if configured).

Backup Model

Creating Backups

POST /api/v2/servers/:id/backups
{ "name": "Before update" }

The daemon creates a zip archive of the server directory. Progress can be polled:

GET /api/v2/servers/:id/backups/progress

Backup Limits

Each server has a backupLimit (default 5). The API rejects creation when the limit is reached. Admins can adjust this per-server.

Backup Ignore List

Servers can have a backupIgnoreList (paths excluded from backups, e.g., large log files, temp data).

Restoring Backups

POST /api/v2/servers/:id/backups/:backupId/restore

Restoration progress:

GET /api/v2/servers/:id/backups/restore/progress

Restoring a backup replaces the current server files. The server should be stopped before restoration.

Downloading Backups

GET /api/v2/servers/:id/backups/:backupId/download

Returns the backup as a streaming zip download.

Locking Backups

Locked backups cannot be deleted:

PATCH /api/v2/servers/:id/backups/:backupId/lock

Toggles the lock state. Useful for preserving critical backups.

Deleting Backups

DELETE /api/v2/servers/:id/backups/:backupId

Fails if the backup is locked. Notifies the daemon to remove the file.

S3 Storage

Backups can be stored in S3-compatible object storage. Configure in admin settings:

• s3Enabled (enable S3 storage)
• s3Endpoint (S3 endpoint URL)
• s3Region (AWS region)
• s3Bucket (bucket name)
• s3AccessKey (access key)
• s3SecretKey (secret key)
• s3PathStyle (use path-style URLs)

Test the connection with:

POST /api/v2/admin/settings/s3/test

Sub-User Permissions

Sub-users need backups permission to view backups, backups.create to create, and backups.delete to delete.