Disaster recovery

Backups protect the data on a machine: a bad migration, a deleted database, corruption you only notice a day later. Take one on demand before a risky change, or set a schedule and boxd uploads the machine’s disk to object storage for you, off the cluster that runs the machine. When you need to go back, one command rewrites the disk from any backup you still have. The backup schedule is per machine and off by default. On-demand backups work whether or not a schedule is set.

Backups, checkpoints, and snapshots

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

	Best for	What’s captured	Where it lives
Backups	Recovering data after loss or corruption	Disk only, on demand or on a schedule	Object storage, off the cluster
Checkpoints	An undo button before a risky change	Memory and disk, on demand	The machine’s own worker
Snapshots	Booting fresh copies of a known-good machine	Memory and disk, as a named image	Replicated across workers

Back up now

boxd machine backup now <machine> captures the disk right away, independent of any schedule and without disturbing one. Reach for it before a migration or deploy you’re not sure about, or any time you want a fresh restore point.

boxd machine backup now myapp
# backing up myapp now, id bkp_e4f5a6b7

boxd machine backup list myapp        # watch it go from pending to ready

The console has the same action on a machine’s Backups tab. Only one capture runs per machine at a time, so triggering another while one is in flight does nothing until the first finishes. An on-demand backup is kept for the machine’s own retention if it has a schedule, otherwise the org default, otherwise 7 days.

Turn it on

A schedule hangs off machine config, next to the idle timers:

boxd machine config set myapp backups.period 24h       # back up daily
boxd machine config set myapp backups.retention 14d    # keep two weeks (default: 7d)
boxd machine config set myapp backups.period off       # disable again

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 capture does

Every backup, on demand or on a schedule, works the same way. 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:

An unchanged disk uploads nothing. A backup that finds the disk untouched since the last one 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. To drop one sooner, delete it by hand (below).

List, restore, and delete

boxd machine backup list myapp                    # newest first (alias: ls)
boxd machine backup restore myapp <backup-id>     # asks to confirm; -y in scripts
boxd machine backup remove myapp <backup-id>      # delete one backup (alias: rm; -y in scripts)

backup remove (or the Delete button on the console’s Backups tab) reclaims a backup the same way an expiry does: the object goes from storage first, then the record. Two backups are refused: one that’s still being captured, and one that a newer unchanged-since backup still points at, where you delete the newer one first or let it expire. 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 on-demand capture, the schedule, the backup list, restore, and delete 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”.

const backupId = await boxd.machines.backups.trigger(machine.id);   // back up now

await boxd.machines.backups.setSchedule(machine.id, {
  intervalSecs: 24 * 3600,
  retentionSecs: 7 * 24 * 3600,
});

const backups = await boxd.machines.backups.list(machine.id);
await boxd.machines.backups.restore(machine.id, backups[0].id);   // destructive
await boxd.machines.backups.delete(machine.id, backups[0].id);

See the TypeScript SDK and Python SDK references.

Getting started

Guides

Integrations & automations

Use cases

References

Disaster recovery

Backups, checkpoints, and snapshots

Back up now

Turn it on

What a capture does

List, restore, and delete

From the SDKs

​Backups, checkpoints, and snapshots

​Back up now

​Turn it on

​What a capture does

​List, restore, and delete

​From the SDKs

Backups, checkpoints, and snapshots

Back up now

Turn it on

What a capture does

List, restore, and delete

From the SDKs