Skip to main content
Backups protect the data on a machine: a bad migration, a deleted database, corruption you only notice a day later. Enable them on a machine and boxd uploads its disk to object storage on a schedule, off the cluster that runs the machine. When you need to go back, one command rewrites the disk from any backup you still have. Backups are per machine and off by default.

​
Backups, checkpoints, and snapshots

Three tools capture machine state, and each answers a different question:

​
Turn it on

Backups hang off machine config, next to the idle timers:
  • backups.period takes a duration (24h, 7d, …). Setting it enables backups. off or 0 disables them.
  • backups.retention also takes a duration and defaults to 7 days. It requires a period to be set first.
  • The interval counts from the last backup. The SDKs can set a wall-clock cron schedule instead, down to one backup every 15 minutes. That floor is enforced server-side for both kinds: a tighter interval or a cron expression whose occurrences fire closer together is rejected.
  • Forks inherit the source machine’s backup schedule, so a fleet forked from a golden keeps the golden’s protection.

​
What a backup tick does

On each tick, the machine’s vCPUs pause for an instant (state only, without a memory dump), the disk is cloned with a reflink, and the machine resumes. The upload to object storage happens in the background from the clone, so your app sees a sub-second pause and nothing else. A failed capture never leaves the machine paused. Two things keep the storage bill honest:
  • Unchanged ticks upload nothing. A tick that finds the disk untouched since the last backup records a pointer to it instead of re-uploading.
  • Uploads are sparse-aware. Only bytes actually written to the disk are uploaded and stored, so a mostly-empty 100 GB disk backs up small.
Backups older than the retention window are reclaimed automatically.

​
List and restore

Restore is a full, in-place disk rewrite. The machine cold-boots into the backup’s disk and keeps its name, URL, SSH port, and settings. Memory and running state are not part of a backup, and everything written to the disk after that backup is gone. For a rewind that brings back memory and running processes, use a checkpoint.
backup restore overwrites the machine’s current disk. Anything since the chosen backup is lost, and there is no undo. If the current disk still matters, save a checkpoint first.
The same commands work from the in-VM CLI inside a machine, and backups can also be managed from the console.

​
From the SDKs

Both SDKs expose the schedule, the backup list, and restore under machines.backups. intervalSecs counts from the last backup; pass cron (standard 5-field syntax) instead for wall-clock schedules like “03:00 every night”.
See the TypeScript SDK and Python SDK references.