Skip to main content
Attach sandbox persistent volumes to keep a separate ext4 volume across temporary machine lifetimes. A volume has its own retention deadline and one writer at a time.

​
Create and wait

Save this as volume.json:
Creation returns 202 and a volume ID. Poll the list until state is ready. A blocked state includes an actionable error; provisioning can recover after capacity is released. Delete and recreate if you need to request a smaller volume. An organization can have up to 32 volumes, each 1–128 GiB. Volumes have one writer and at most one mount per machine. Trial accounts cannot use persistent volumes.

​
Attach at machine creation

Save this as create-volume-machine.json:
Mount at /data or below /mnt/, without traversal or symlink targets. Persistent machine creation with volumeMounts is rejected. Volume placement is local to its supported placement; volumes do not provide cross-host replication or shared read-only mounts.

​
Extend retention

Retention accepts 60–86400 seconds. Save {"retention_seconds":86400} as extend-volume.json:
Read the requested and worker-confirmed deadlines. Machine leases cannot exceed confirmed retention. Extend before expiry; adding credit alone does not extend the deadline. Storage funding covers the retention window even while detached.

​
Detach and delete

Close files and mappings on the volume before detaching from a running machine:
A busy filesystem returns 409. Deletion refuses attached volumes and returns 202 when accepted. Poll the list until the volume disappears. Machine deletion also releases attachment after lifecycle cleanup; the volume remains until its own deletion or expiry.

​
Snapshots and contents

Saved snapshots and forks reject sources with an attached persistent volume. Close files and mappings, then detach the volume before capture; volume contents are not copied into a saved snapshot. Export required data before the retention deadline. Subscribe to volume.expiring through webhooks.