How to attach a persistent volume to a sandbox

On Runtime, a volume is a disk that outlives every sandbox that uses it. It is backed up off its server every day. It costs 153 microdollars per GiB-hour, or about $0.11 per GiB per 30-day month. A 10 GiB cache therefore costs about $1.10 a month. An account without credit stores its first 10 GiB of volumes free, for as long as you keep them. Rates are in force since 23 September 2026 (pricing).

Create, attach, write

TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime();const volume = await runtime.volumes.create({ sizeMiB: 10_240, name: "cache" });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");

Pythonfrom withruntime import Runtimeruntime = Runtime()volume = runtime.volumes.create(size_mib=10_240, name="cache")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")

Terminalvol=$(runtime volumes create --size-mib 10240 --name cache)id=$(runtime sandboxes create --volume "${vol}:/data")runtime sandboxes exec "${id}" -- sh -c 'sudo chown runtime /data && echo kept > /data/note.txt'runtime sandboxes stop "${id}"

The first command gives /data to the sandbox user, runtime. Later commands can write to it without sudo. The next sandbox that attaches this volume finds /data/note.txt where this one left it.

Read-write to one, read-only to many

TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime();const weights = await runtime.volumes.create({ sizeMiB: 20_480, name: "weights" });const workers = await Promise.all(  [1, 2, 3].map(() =>    runtime.sandboxes.create({      volumes: [{ volumeId: weights.id, path: "/models", mode: "snapshot" }],    }),  ),);await Promise.all(workers.map((w) => w.stop()));

A sandbox can attach up to four volumes.

Facts to plan around

Back it up and restore it

You can also make a backup on request. A restore creates a new volume in the same region, on whichever server has room. The original volume is not changed (volume backups).

TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime();const volume = await runtime.volumes.create({ sizeMiB: 10_240, name: "data" });const backup = await runtime.volumes.backup(volume.id, { retentionDays: 30 });const restored = await runtime.volumes.restore(backup.id, { name: "data-restored" });console.log(restored.id);

Terminalruntime volumes backup "${vol}" --retention-days 30runtime volumes restore "${backup}" --name data-restored

Only what changed since an earlier backup of the same volume is stored again. Deleting a volume keeps its backups until the retention period of each one ends.

Mistakes to avoid

• Two writers. A read-write volume attaches to one sandbox at a time. For many readers, attach it as snapshot. For many writers, give each its own volume, or mount a bucket.
• Keeping work only on the sandbox's own disk. That disk has no copy off its server. Keep what you cannot rebuild on a volume.
• Oversizing. A volume is charged on its full size from creation. A 100 GiB volume that holds 2 GiB costs the same as a full one. Start near the size you need.
• Expecting a snapshot to include the volume. A sandbox with volumes cannot be snapshotted. Snapshot a sandbox without volumes, and attach the volume to each copy you start.

Where volumes fit

A volume suits state that outlives a task. Examples are a per-user dev environment's home directory, a data analysis agent's datasets, or a package cache shared across runs. To keep a whole machine, memory included, between uses, pause it instead.

Facts on this page were checked on 26 October 2026.