Runtime

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).

Back up now

TypeScriptimport { 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 minuteconsole.log(backup.id, backup.state, backup.storedBytes);
Pythonfrom withruntime import Runtimeruntime = 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"])
Terminalruntime volume backup "${vol}" --retention-days 30   # prints the backup idruntime 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:

TypeScriptimport { 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 checkedawait using sbx = await runtime.sandboxes.create({  volumes: [{ volumeId: restored.id, path: "/data" }],});console.log((await sbx.exec("cat /data/note.txt")).stdout);
Pythonfrom withruntime import Runtimeruntime = Runtime()restored = runtime.volumes.restore("<backup id>", name="data-restored")print(restored["state"], restored["restoredFrom"])
Terminalruntime 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

TypeScriptimport { 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);
Terminalruntime volume backup-policy "${vol}" --daily on --retention-days 14runtime 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).

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.

Start

Terminalnpx 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.

Claim 50 hours free