Skip to main content

Volumes

The volumes manager handles persistent storage: lifecycle, files, checkpoints, and VM mounts.

Create volume​

from instavm import InstaVM

client = InstaVM("your_api_key")

volume = client.volumes.create(
    name="project-data",
    quota_bytes=10 * 1024 * 1024 * 1024,
)
print(volume["id"])

List and get​

Use refresh_usage=True when you need up-to-date used_bytes.

volumes = client.volumes.list(refresh_usage=True)
for v in volumes:
    print(v["id"], v["name"], v["used_bytes"], v["quota_bytes"])

volume = client.volumes.get(
    volume_id="vol_abc123",
    refresh_usage=True,
)
print(volume)

Update and delete​

updated = client.volumes.update(
    volume_id="vol_abc123",
    name="project-data-v2",
    quota_bytes=20 * 1024 * 1024 * 1024,
)
print(updated["name"])

client.volumes.delete(volume_id="vol_abc123")

File operations​

upload_file(volume_id, file_path, path, overwrite=False)​

client.volumes.upload_file(
    volume_id="vol_abc123",
    file_path="./README.md",
    path="docs/README.md",
    overwrite=True,
)

list_files(volume_id, prefix="", recursive=True, limit=1000)​

files = client.volumes.list_files(
    volume_id="vol_abc123",
    prefix="docs/",
    recursive=True,
    limit=1000,
)

for f in files:
    print(f["path"], f["size"])

download_file(volume_id, path, local_path=None, decode_base64=True)​

payload = client.volumes.download_file(
    volume_id="vol_abc123",
    path="docs/README.md",
)
print(payload["filename"], payload["size"])

Save directly to disk:

saved = client.volumes.download_file(
    volume_id="vol_abc123",
    path="docs/README.md",
    local_path="./README.copy.md",
)
print(saved["local_path"], saved["saved_bytes"])

delete_file(volume_id, path)​

client.volumes.delete_file(
    volume_id="vol_abc123",
    path="docs/README.md",
)

Checkpoints​

create_checkpoint(volume_id, name=None)​

checkpoint = client.volumes.create_checkpoint(
    volume_id="vol_abc123",
    name="pre-release",
)
print(checkpoint["id"], checkpoint["status"])

list_checkpoints(volume_id)​

checkpoints = client.volumes.list_checkpoints(volume_id="vol_abc123")
for cp in checkpoints:
    print(cp["id"], cp.get("name"), cp["status"])

delete_checkpoint(volume_id, checkpoint_id)​

client.volumes.delete_checkpoint(
    volume_id="vol_abc123",
    checkpoint_id="cp_123",
)

VM volume attachments​

mount_volume(vm_id, volume_id, mount_path, mode="rw", checkpoint_id=None, wait=True)​

mount = client.vms.mount_volume(
    vm_id="vm_abc123",
    volume_id="vol_abc123",
    mount_path="/data",
    mode="rw",
    checkpoint_id=None,
    wait=True,
)
print(mount)

list_volumes(vm_id)​

mounted = client.vms.list_volumes(vm_id="vm_abc123")
for m in mounted:
    print(m["volume_id"], m["mount_path"], m["mode"], m["status"])

unmount_volume(vm_id, volume_id, mount_path, wait=True)​

mount_path is required by the API.

client.vms.unmount_volume(
    vm_id="vm_abc123",
    volume_id="vol_abc123",
    mount_path="/data",
    wait=True,
)

Typical flow​

client = InstaVM("your_api_key")

vol = client.volumes.create("dataset", 5 * 1024 * 1024 * 1024)
vol_id = vol["id"]

client.volumes.upload_file(vol_id, "./train.csv", "datasets/train.csv", overwrite=True)
cp = client.volumes.create_checkpoint(vol_id, "before-training")

vm = client.vms.create(wait=True)
vm_id = vm["vm_id"]

client.vms.mount_volume(vm_id, vol_id, "/data", mode="rw", checkpoint_id=cp["id"], wait=True)
# run workload...
client.vms.unmount_volume(vm_id, vol_id, "/data", wait=True)

Next steps​