Managing volumes

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)

import { NullspaceClient } from "nullspace";

const client = new NullspaceClient();
const volume = await client.volumes.create("team-data");
console.log(volume.id, volume.name, volume.status);

nullspace volume create team-data

curl -X POST "${NULLSPACE_API_URL}/v1/volumes" \
  -H "Authorization: Bearer ${NULLSPACE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"name": "team-data"}'

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_123")
by_name = Volume.get_by_name("team-data")
print(by_name.used_bytes, by_name.max_size_bytes)

const byId = await client.volumes.get("vol_123");
const byName = await client.volumes.getByName("team-data");
console.log(byName.usedBytes, byName.maxSizeBytes);

nullspace volume get team-data
nullspace volume get vol_123

curl -X GET "${NULLSPACE_API_URL}/v1/volumes/vol_123" \
  -H "Authorization: Bearer ${NULLSPACE_API_KEY}"

curl -X GET "${NULLSPACE_API_URL}/v1/volumes/by-name/team-data" \
  -H "Authorization: Bearer ${NULLSPACE_API_KEY}"

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)

for (const item of await client.volumes.list()) {
  console.log(item.id, item.name, item.status, item.mountCount);
}

nullspace volume list

curl -X GET "${NULLSPACE_API_URL}/v1/volumes" \
  -H "Authorization: Bearer ${NULLSPACE_API_KEY}"

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"])

nullspace volume list --fields id,name,mount_count,used_bytes
nullspace volume get team-data --fields id,status,max_size_bytes

curl -X GET "${NULLSPACE_API_URL}/v1/volumes?fields=id,name,mount_count,used_bytes" \
  -H "Authorization: Bearer ${NULLSPACE_API_KEY}"

curl -X GET "${NULLSPACE_API_URL}/v1/volumes/by-name/team-data?fields=id,status,max_size_bytes" \
  -H "Authorization: Bearer ${NULLSPACE_API_KEY}"

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()

await client.volumes.delete("vol_123");

nullspace volume delete vol_123

curl -X DELETE "${NULLSPACE_API_URL}/v1/volumes/vol_123" \
  -H "Authorization: Bearer ${NULLSPACE_API_KEY}"

Delete by volume ID. Deleting an attached volume can be rejected; destroy attached machines before retrying. Hibernating or pausing a machine 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()

Get started

Machines

Commands

Filesystem

Code Interpreter

Desktop

Templates

Volumes

Networking

Interactive access

Observability

Create

Get

List

Select Fields

Refresh Metadata

Delete

Async

​Create

​Get

​List

​Select Fields

​Refresh Metadata

​Delete

​Async

​Related

Create

Get

List

Select Fields

Refresh Metadata

Delete

Async

Related