Skip to main content
Use volume management APIs for metadata and lifecycle operations. Direct file operations live on volume.files and are covered in the file task pages.

​
Create

from nullspace import Volume

volume = Volume.create("team-data")
print(volume.id, volume.name, volume.status)
Use Volume.from_name(..., create_if_missing=True) when setup scripts should be idempotent: 
volume = Volume.from_name("team-data", create_if_missing=True)

​
Get

by_id = Volume.get("vol_12345678")
by_name = Volume.get_by_name("team-data")
print(by_name.used_bytes, by_name.max_size_bytes)
Volume.from_id(id) is an alias for Volume.get(id).

​
List

for item in Volume.list():
    print(item.id, item.name, item.status, item.mount_count)

​
Select Fields

Use fields= when dashboards or scripts only need a few metadata attributes. When fields are requested, the SDK returns raw dictionaries instead of VolumeInfo objects. 
rows = Volume.list(fields=["id", "name", "mount_count", "used_bytes"])
info = Volume.get_by_name("team-data", fields=["id", "status", "max_size_bytes"])

​
Refresh Metadata

info = volume.get_info()
print(info.used_bytes, info.max_size_bytes)
Refresh metadata after large writes when you need current capacity and usage. used_bytes is observed usage from the latest reconciliation. max_size_bytes is the current enforced cap. In the hosted private beta, auto-grow is currently disabled and the default cap is 2 GiB per volume unless an operator has applied a tenant-specific override.

​
Delete

volume.delete()
Delete by volume ID. Deleting an attached volume can be rejected; destroy attached sandboxes before retrying. Hibernating or pausing a sandbox is not a volume detach operation because the attachment intent remains and the volume remounts on resume.

​
Async

from nullspace import AsyncVolume

volume = await AsyncVolume.from_name("team-data", create_if_missing=True)
info = await volume.get_info()
await volume.delete()