> ## Documentation Index
> Fetch the complete documentation index at: https://docs.boxd.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Disaster recovery

> Scheduled disk backups to object storage, and an in-place restore for when something goes wrong.

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:

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

## Turn it on

Backups hang off [`machine config`](/cli/commands), next to the idle timers:

```bash theme={"theme":"github-dark"}
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](#from-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

```bash theme={"theme":"github-dark"}
boxd machine backup list myapp                    # newest first (alias: ls)
boxd machine backup restore myapp <backup-id>     # asks to confirm; -y in scripts
```

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](/guides/checkpoints).

<Warning>
  `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](/guides/checkpoints) first.
</Warning>

The same commands work from the in-VM CLI inside a machine, and backups can also be managed from the [console](https://boxd.sh/app).

## 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".

```typescript theme={"theme":"github-dark"}
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
```

See the [TypeScript SDK](/reference/typescript-sdk) and [Python SDK](/reference/python-sdk) references.