Skip to main content

Volumes

Volumes are persistent block storage for VMs. Use them when data must outlive a VM/session lifecycle.

When to use volumes​

Use volumes when you need:

  • Data to survive VM termination
  • Shared data across multiple VM runs
  • Explicit storage lifecycle separate from compute lifecycle
  • Preloaded project assets mounted into a VM path

Volumes vs sandbox filesystem vs snapshots​

Storage typePersistenceBest for
Session filesystem (/app)Lost when VM/session endsTemporary execution artifacts
VolumePersists until deletedDurable project data, model artifacts, cached dependencies
SnapshotVM image state at a point in timeFast reproducible VM boot environments

Use snapshots to define boot-time environment state. Use volumes for mutable data that should continue across VM restarts.

Volume lifecycle​

  1. Create a volume (name, quota_bytes)
  2. Upload/list/download/delete files directly on the volume (without mounting)
  3. Optionally create checkpoints for point-in-time restore anchors
  4. Mount volume into a VM path (for example /data)
  5. Unmount when done
  6. Delete volume when no longer needed

Mount model​

  • A volume mount is explicit: volume_id + mount_path + mode
  • Modes:
    • rw (read/write)
    • ro (read-only)
  • You can mount during VM lifecycle operations or hot-plug on an existing VM
  • Unmount requires mount_path

File operations without a mount​

Volume file APIs work outside VM mounts:

  • Upload directly to a volume path
  • List files with prefix, recursive, and limit
  • Download by path
  • Delete by path

This is useful for pre-seeding data before VM boot and for post-run retrieval/cleanup.

Checkpoints​

Volume checkpoints let you capture a volume state marker and later mount from a specific checkpoint context (where supported by your workflow).

Common use cases:

  • Guardrail before risky writes
  • Roll-forward pipeline milestones
  • Controlled dataset versioning

Limitations and guardrails​

  • Volumes are not a managed database service.
  • Do not use volumes as a replacement for transactional database hosting (for example PostgreSQL/MySQL production workloads).
  • If you need ACID semantics, replication, failover, and database-specific durability guarantees, use a dedicated database platform and access it from your VM.

Next steps​