Volumes

A volume is a persistent filesystem that outlives the microVMs it is attached to. Use one for anything a new microVM should start with: a dependency cache, a cloned repository, a model download, or a database's data directory.

How volumes work

• A volume is an empty ext4 filesystem of a fixed size when you create it. You attach it when you create a microVM, at a mount path such as /data.
• One microVM uses a volume at a time. Attaching a volume that another live microVM holds fails with 409 microvm_volume_in_use.
• What the microVM writes under the mount path is saved when the microVM stops: when you stop or delete it, when its timeout ends, or when its organization is suspended. You can also save while it runs.
• The next microVM that attaches the volume sees exactly what the last save contained.
• If a microVM fails, or stops running unexpectedly, its volumes keep their last save and what it wrote after that is lost. Save regularly when that matters.
• Only what changed since the last save is uploaded again, so saving a large, mostly unchanged volume is fast.

Create a volume and attach it

Create the volume once, then attach it to every microVM that needs it. In the console, open your application, go to microVMs, then Volumes, and select Create volume. In code or from a terminal:

import { GigadriveClient, MicroVM } from '@gigadrive/sdk';

const client = new GigadriveClient({ applicationId: '0197b2f1-2f4a-7a0b-8a2d-222222222222' });
const volume = await client.microvms.volumes.create({ name: 'npm-cache', sizeMb: 20480 });

const vm = await MicroVM.create({
  client,
  image: 'node22',
  volumes: [{ volumeId: volume.id, mountPath: '/cache' }],
});
await vm.run('npm config set cache /cache && npm install -g typescript');
await vm.stop(); // resolves once /cache is saved

Mount paths

A mount path must:

• Be absolute and normalized: no . or .. segments, no // and no trailing /.
• Be at most 255 characters of letters, digits, ., _, - and /.
• Not be /, and not be or lie under /proc, /sys, /dev, /run, /etc, /bin, /sbin, /lib, /lib64, /usr or /boot.
• Be unique among the microVM's volumes, and not lie inside another volume's mount path.
• Not cross a symbolic link in the image. For example, /var/run is a link to /run on Debian and Ubuntu images.

The directory is created if the image does not have it.

Save without stopping

Save a running microVM's volumes when it reaches a point you want to keep. The microVM keeps running; it is paused only while its volumes are copied, and then continues where it was.

await vm.run('git clone https://github.com/vercel/next.js /cache/next.js');
await vm.saveVolumes();

A save captures the files as they are at that moment, like a power cut would. For a database, stop it or flush it first, for example pg_ctl stop.

Volume status

lastSavedAt is the time of the last successful save. When a save fails, lastSaveError says why and the volume keeps its previous contents.

Limitations

• A microVM with volumes cannot be paused or snapshotted, and it cannot use onTimeout: "pause". A microVM created from a snapshot cannot attach volumes.
• A microVM with volumes takes a few seconds to start, where one without volumes usually starts in under a second.
• A volume's size cannot change after you create it.
• An attached volume cannot be deleted. Stop its microVM first.

Volumes are billed as snapshot storage for the size of their last save. See Limits and pricing.