Volumes Workflow

This guide walks through the full volume lifecycle: create, transfer files, checkpoint, mount on new/existing VMs, unmount, and cleanup.

Prerequisites

CLI
Python
JavaScript

pip install instavm    # Python SDK + CLI
# or
npm install instavm    # JavaScript SDK

pip install instavm

npm install instavm

You need a valid API key from the InstaVM Dashboard.

1) Create a volume

CLI
Python
JavaScript

instavm volume create project-data --quota 10gb

from instavm import InstaVM

client = InstaVM(api_key="your_api_key")

volume = client.volumes.create(
    name="project-data",
    quota_bytes=10 * 1024 * 1024 * 1024,  # 10 GiB
)

volume_id = volume["id"]
print("volume:", volume_id)

import { InstaVM } from 'instavm';

const client = new InstaVM('your_api_key');

const volume = await client.volumes.create({
  name: 'project-data',
  quota_bytes: 10 * 1024 * 1024 * 1024, // 10 GiB
});

const volumeId = String(volume.id);
console.log('volume:', volumeId);

2) Upload, list, download, and delete files without mounting

CLI
Python
JavaScript

# Upload
instavm volume files upload <volume_id> ./README.md \
  --path docs/README.md --overwrite

# List
instavm volume files ls <volume_id> --prefix docs/

# Download
instavm volume files download <volume_id> docs/README.md

# Delete
instavm volume files rm <volume_id> docs/README.md

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

# List
files = client.volumes.list_files(
    volume_id=volume_id,
    prefix="docs/",
    recursive=True,
    limit=1000,
)
print("files:", len(files))

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

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

import fs from 'fs';

await client.volumes.uploadFile(volumeId, {
  filePath: './README.md',
  path: 'docs/README.md',
  overwrite: true,
});

const files = await client.volumes.listFiles(volumeId, {
  prefix: 'docs/',
  recursive: true,
  limit: 1000,
});
console.log('files:', files.length);

const file = await client.volumes.downloadFile(volumeId, 'docs/README.md');
fs.writeFileSync('./README.copy.md', file.content);

await client.volumes.deleteFile(volumeId, 'docs/README.md');

3) Create and manage checkpoints

CLI
Python
JavaScript

# Create
instavm volume checkpoint create <volume_id> --name pre-release

# List
instavm volume checkpoint ls <volume_id>

# Delete
instavm volume checkpoint rm <volume_id> <checkpoint_id>

checkpoint = client.volumes.create_checkpoint(
    volume_id=volume_id,
    name="pre-release",
)

checkpoints = client.volumes.list_checkpoints(volume_id=volume_id)
print("checkpoints:", len(checkpoints))

client.volumes.delete_checkpoint(
    volume_id=volume_id,
    checkpoint_id=checkpoint["id"],
)

const checkpoint = await client.volumes.createCheckpoint(volumeId, {
  name: 'pre-release',
});

const checkpoints = await client.volumes.listCheckpoints(volumeId);
console.log('checkpoints:', checkpoints.length);

await client.volumes.deleteCheckpoint(volumeId, String(checkpoint.id));

4) Mount on a newly created VM

CLI
Python
JavaScript

instavm create --volume <volume_id>:/data:rw

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

mounted = client.vms.mount_volume(
    vm_id=vm_id,
    volume_id=volume_id,
    mount_path="/data",
    mode="rw",
    wait=True,
)
print(mounted)

const vm = await client.vms.create({}, true);
const vmId = String(vm.vm_id);

await client.vms.mountVolume(
  vmId,
  {
    volume_id: volumeId,
    mount_path: '/data',
    mode: 'rw',
  },
  true
);

5) Hot-plug on an existing/running VM

Use the same mount API against an already-running VM.

CLI
Python
JavaScript

# Mount on an already-running VM
instavm create --volume <volume_id>:/mnt/hotplug:rw

client.vms.mount_volume(
    vm_id=vm_id,
    volume_id=volume_id,
    mount_path="/mnt/hotplug",
    mode="rw",
    wait=True,
)

await client.vms.mountVolume(
  vmId,
  {
    volume_id: volumeId,
    mount_path: '/mnt/hotplug',
    mode: 'rw',
  },
  true
);

6) Unmount and cleanup

Unmount requires mount_path.

CLI
Python
JavaScript

# Delete the volume (unmount happens automatically)
instavm volume rm <volume_id>

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

client.volumes.delete(volume_id=volume_id)

await client.vms.unmountVolume(vmId, volumeId, '/data', true);
await client.volumes.delete(volumeId);

Important flags and when to use them

Flag	Where	Why it matters
`refresh_usage`	`volumes.list/get`	Refreshes usage metrics before returning
`overwrite`	upload	Controls replacement behavior for existing file path
`prefix`	list files	Restricts list scope to a subtree
`recursive`	list files	Includes nested paths when `true`
`limit`	list files	Caps result count per list call
`mode`	mount	`rw` or `ro` access mode
`checkpoint_id`	mount	Attach using a specific checkpoint context
`wait`	mount/unmount/create vm	Block until operation completes
`mount_path`	mount/unmount	In-VM path; required for unmount

Operational notes

Keep mount paths explicit and consistent (/data, /mnt/cache, etc.).
Use checkpoints before destructive writes.
Keep volume quotas aligned with workload expectations to avoid write failures.
Treat volumes as durable file storage, not as managed transactional databases.

Prerequisites​

1) Create a volume​

2) Upload, list, download, and delete files without mounting​

3) Create and manage checkpoints​

4) Mount on a newly created VM​

5) Hot-plug on an existing/running VM​

6) Unmount and cleanup​

Important flags and when to use them​

Operational notes​

Next steps​