Mounting volumes

Mount volumes when a machine needs durable shared files. You can declare volumes at machine create time or attach them to an already running machine with the SDK or HTTP API. A machine can have up to 8 active volume attachments. The create-time examples show the Python SDK form first and the equivalent CLI create command second. Runtime examples use the Python SDK and raw HTTP API.

Mount A Volume

from nullspace import Machine, Volume

volume = Volume.from_name("team-data", create_if_missing=True)

with Machine.create(
    template="base",
    volumes=[volume.mount("/workspace/shared")],
) as machine:
    machine.files.write("/workspace/shared/hello.txt", "persistent\n")

nullspace machine create \
  --template base \
  --volume ref=team-data,mount=/workspace/shared

Mount paths must be absolute machine paths outside runtime-managed paths such as /workspace/.nullspace.

Mount A Subpath

Expose only one directory from the volume:

mount = volume.mount("/workspace/datasets", subpath="/datasets")
machine = Machine.create(template="base", volumes=[mount])

nullspace machine create \
  --template base \
  --volume ref=team-data,mount=/workspace/datasets,subpath=/datasets

subpath is resolved inside the volume and exposes only that subtree at the machine mount path.

Read-Only Mounts

mount = volume.mount("/workspace/models", subpath="/published-models", read_only=True)
machine = Machine.create(template="base", volumes=[mount])

nullspace machine create \
  --template base \
  --volume ref=team-data,mount=/workspace/models,subpath=/published-models,ro=true

read_only=True prevents writes through the machine mount. Callers with API access can still modify the volume through direct volume.files or nullspace volume ... operations.

Dictionary Mounts

SDK calls also accept dictionaries, which is useful when mount configuration is loaded from JSON:

machine = Machine.create(
    template="base",
    volumes=[
        {
            "ref": "team-data",
            "mount_path": "/workspace/shared",
            "subpath": "/datasets",
            "read_only": True,
        },
    ],
)

ref can be a volume name or volume ID.

Runtime Attach And Detach

Attach a volume to a running machine with the same mount descriptor shape used at create time:

from nullspace import Machine, Volume

machine = Machine.connect("mch_...")
volume = Volume.from_name("team-data")

attachment = machine.attach_volume(volume.id, "/workspace/shared")
print(attachment.id, attachment.state, attachment.mount_path)

curl -fsS -X POST "${NULLSPACE_API_URL}/v1/machines/${MACHINE_ID}/volumes" \
  -H "Authorization: Bearer ${NULLSPACE_API_KEY}" \
  -H "Content-Type: application/json" \
  --data '{"ref":"team-data","mount_path":"/workspace/shared"}'

List the current attachments for a machine or a volume:

for attachment in machine.list_volumes():
    print(attachment.id, attachment.volume_id, attachment.state)

for attachment in volume.attachments():
    print(attachment.machine_id, attachment.mount_path, attachment.state)

The equivalent HTTP list routes are GET /v1/machines/{id}/volumes and GET /v1/volumes/{id}/attachments. Detach one runtime attachment by ID:

released = machine.detach_volume(attachment.id)
print(released.state)

curl -fsS -X DELETE \
  "${NULLSPACE_API_URL}/v1/machines/${MACHINE_ID}/volumes/${ATTACHMENT_ID}" \
  -H "Authorization: Bearer ${NULLSPACE_API_KEY}"

The Python SDK accepts a volume ID, volume name, VolumeMount, or dictionary for machine.attach_volume(...). If read_only is omitted, the runtime API defaults it to false.

Health And Remount

Use health and remount operations when a mounted volume is degraded or after an operator asks you to refresh the live mount:

health = machine.get_volume_health(attachment.id)
if health.state == "failed":
    print(health.last_error_code, health.last_error_message)

remounted = machine.remount_volume(attachment.id)
print(remounted.state)

curl -fsS \
  "${NULLSPACE_API_URL}/v1/machines/${MACHINE_ID}/volumes/${ATTACHMENT_ID}/health" \
  -H "Authorization: Bearer ${NULLSPACE_API_KEY}"

curl -fsS -X POST \
  "${NULLSPACE_API_URL}/v1/machines/${MACHINE_ID}/volumes/${ATTACHMENT_ID}/remount" \
  -H "Authorization: Bearer ${NULLSPACE_API_KEY}"

Attachment states include requested, mounting, mounted, paused, remounting, unmounted, releasing, released, and failed. Destroy the machine to release all remaining volume attachments. Hibernating or pausing a machine releases the live mount lease while the VM is stopped, but it preserves the attachment intent; resume remounts the same volumes. Fork and snapshot restore also remount the stored attachments in the new machine. The CLI currently supports create-time --volume entries. Use the SDK or HTTP API for runtime attach, detach, health, and remount operations.

Snapshot Behavior

Shared volume data is durable storage external to VM memory and mutable rootfs snapshots. Hibernate, resume, and fork remount volume attachments; they do not copy volume data into the VM snapshot.

Get started

Machines

Commands

Filesystem

Code Interpreter

Desktop

Templates

Volumes

Networking

Interactive access

Observability

Mount A Volume

Mount A Subpath

Read-Only Mounts

Dictionary Mounts

Runtime Attach And Detach

Health And Remount

Snapshot Behavior

​Mount A Volume

​Mount A Subpath

​Read-Only Mounts

​Dictionary Mounts

​Runtime Attach And Detach

​Health And Remount

​Snapshot Behavior

​Related

Mount A Volume

Mount A Subpath

Read-Only Mounts

Dictionary Mounts

Runtime Attach And Detach

Health And Remount

Snapshot Behavior

Related