# How to back up and restore a sandbox volume

Volumes are backed up off their server daily; `volumes.backup(id)` makes one now and `volumes.restore(backupId)` restores it.

**On Runtime a volume outlives the server it lives on.** A volume is a disk
that outlives sandboxes, kept on one server, and it is copied off that server
every day without your asking, encrypted with a key that belongs to your
organization alone. A restore can land on any server in the region. Backups
are incremental and cost $0.012 per decimal GB per 30-day month of what they
store, so a week of daily backups that store 3 GB in all costs about 4 cents
a month ([storage and backups](/docs/storage#volume-backups)).

## Back up now

```ts check
import { Runtime } from "withruntime";

const runtime = new Runtime();
const volume = await runtime.volumes.create({ sizeMiB: 10_240, name: "data" });

await using sbx = await runtime.sandboxes.create({
  volumes: [{ volumeId: volume.id, path: "/data" }],
});
await sbx.exec("sudo chown runtime /data && echo kept > /data/note.txt && sync", { check: true });

const backup = await runtime.volumes.backup(volume.id, { retentionDays: 30 }); // waits up to a minute
console.log(backup.id, backup.state, backup.storedBytes);
```

```python check
from withruntime import Runtime

runtime = Runtime()
volume = runtime.volumes.create(10_240, name="data")
with runtime.sandboxes.create(volumes=[{"volume_id": volume["id"], "path": "/data"}]) as sbx:
    sbx.exec("sudo chown runtime /data && echo kept > /data/note.txt && sync", check=True)

backup = runtime.volumes.backup(volume["id"], retention_days=30)
print(backup["id"], backup["state"])
```

```bash no-run
runtime volume backup "${vol}" --retention-days 30   # prints the backup id
runtime volume backups "${vol}"                      # newest first
```

A backup is `pending` until its copy is written off the server, read back and
checked, then `ready`. The volume's `backedUp` turns `true` at that point, and
`backups.lastReadyAt` says when the newest one was taken.

## Restore it

A restore is always a new volume, the size of the backup, in the same region,
on whichever server has room. The original is never touched:

```ts check
import { Runtime } from "withruntime";

const runtime = new Runtime();
const restored = await runtime.volumes.restore("<backup id>", { name: "data-restored" });
console.log(restored.state, restored.restoredFrom); // "creating" until every byte is checked

await using sbx = await runtime.sandboxes.create({
  volumes: [{ volumeId: restored.id, path: "/data" }],
});
console.log((await sbx.exec("cat /data/note.txt")).stdout);
```

```python check
from withruntime import Runtime

runtime = Runtime()
restored = runtime.volumes.restore("<backup id>", name="data-restored")
print(restored["state"], restored["restoredFrom"])
```

```bash no-run
runtime volume restore "${backup}" --name data-restored
```

The restored volume is ready once every byte has been downloaded and checked.
Attach it to a new sandbox as you would any volume.

## Daily backups and how long they are kept

```ts check
import { Runtime } from "withruntime";

const runtime = new Runtime();
await runtime.volumes.setBackupPolicy("<volume id>", { daily: true, retentionDays: 14 });
for await (const each of await runtime.volumes.backups({ volumeId: "<volume id>" }))
  console.log(each.id, each.trigger, each.readyAt, each.expiresAt);
```

```bash no-run
runtime volume backup-policy "${vol}" --daily on --retention-days 14
runtime volume backup-rm "${backup}"
```

An agent does the same with the `runtime_volume_backup`,
`runtime_volume_backup_get`, `runtime_volume_backup_policy` and
`runtime_volume_backup_delete` MCP tools, and restores with
`runtime_volume_create` and `fromBackup`.

## The rules

| What                | How it works                                                                              |
| ------------------- | ----------------------------------------------------------------------------------------- |
| Daily backup        | On for every volume, first taken an hour after it is created; `daily: false` turns it off |
| Retention           | 7 days unless you set 1 to 365, per volume or per backup                                  |
| On request          | `backup(id)` makes one now and waits up to a minute for it to be ready                    |
| What is stored      | Only what changed since an earlier backup of the same volume; empty space not at all      |
| Consistency         | A point in time, as a disk is after a power cut                                           |
| Encryption          | Your organization's own data key; every piece is checked when read back                   |
| Deleting the volume | Its backups stay until each one's retention ends                                          |
| Limit               | 200 volume backups per organization at a time                                             |
| Price               | $0.012 per decimal GB per 30-day month, on `storedBytes`, once the copy is ready          |

The volume itself is charged on its full size, 153 microdollars per GiB-hour
or about $0.11 per GiB a month, and the free trial keeps your first 10 GiB of
volumes free ([pricing](/docs/pricing#snapshots-images-and-volumes)).

## Mistakes and how Runtime handles them

- **Backing up in the middle of a write.** A backup holds what the disk held
  at that moment, not what a program still had in memory. For a clean point,
  stop the sandbox first: a stop writes out what it wrote to its volumes, and a
  stop that waits answers once they are free. Otherwise run `sync`, or stop the
  database, before `backup`.
- **Letting a lease run out.** A sandbox whose lease ends stops at once,
  without that final write-out. Run `sync` after writes you must keep.
- **Losing the server.** If a volume's server is lost, the volume goes with
  it, and its error names the newest backup to restore from.
- **Expecting a restore to overwrite.** It never does; it makes a new volume
  with `restoredFrom` set, so the damaged one is still there to compare.
- **Snapshotting instead.** A sandbox with volumes cannot be snapshotted.
  Back the volume up, and rebuild the sandbox from an image.
- **Keeping data on the sandbox's own disk.** A sandbox's disk has no copy off
  its server. Keep what you cannot rebuild on a volume.

## Related

- [Mount an S3 bucket](/how-to/mount-an-s3-bucket) for data that already
  lives in object storage.
- [Pause and resume a sandbox](/how-to/pause-and-resume-a-sandbox) to keep a
  whole machine, memory included.
- [What is a sandbox snapshot?](/glossary/sandbox-snapshot)

## Start

```bash no-run
npx withruntime volume create --size-mib 1024 --name trial-data
```

New accounts get 50 free sandbox hours and 10 GiB of free volume storage, no
card. The first command prints a link to approve in your browser.

Facts on this page were checked on 25 September 2026.