Volumes

Volumes are durable shared filesystems. Create them once, mount them into one or more machines, or manage their files directly through the SDK and CLI without starting a machine.

Volumes require a microVM-runtime deployment with the shared-volume backend and Supabase-backed control-plane state enabled.

When To Use Volumes

Need	Use Volumes?
Persist files after a machine is destroyed	Yes. Volume data is external to VM memory and rootfs snapshots.
Share files across machines	Yes, mount the same volume where supported by deployment configuration.
Keep live VM memory or process state	No. Use hibernate/auto-resume for VM state.
Move large datasets in and out	Yes, use volume upload/download or direct volume file APIs.
Store application database state	Use a database when you need transactional semantics.

Quick Example

The Python SDK and CLI snippets below are equivalent ways to create a volume, write data, and mount it into a new machine. Use one control plane unless you are intentionally handing a volume name or machine ID between tools.

from nullspace import Machine, Volume

volume = Volume.from_name("team-data", create_if_missing=True)
volume.files.write("/hello.txt", "persistent\n")

with Machine.create(volumes=[volume.mount("/workspace/shared")]) as machine:
    print(machine.files.read("/workspace/shared/hello.txt").strip())

nullspace volume create team-data
printf "persistent\n" | nullspace volume write team-data /hello.txt
nullspace machine create --template base --volume ref=team-data,mount=/workspace/shared

Mounts Vs Direct File APIs

Operation	Use
Machine code reads and writes data	Mount the volume into the machine.
Your controller app manages durable files	Use `volume.files.*` APIs directly.
Attach data to an already running machine	Use runtime volume attachment.
Inspect or transfer data without compute	Use volume list, read, write, upload, and download commands.

Volume Tasks

Managing volumes

Create, list, inspect, field-select, and delete volume metadata.

Mounting volumes

Attach volumes at create time or runtime, including read-only and subpath mounts.

Read and write

Read, write, batch-write, move, remove, and edit direct volume files.

File and directory metadata

List directories, stat paths, check existence, search, replace, and watch changes.

Upload data

Upload files, directories, stdin streams, and resumable transfers into volumes.

Download data

Download files, directories, archives, and signed URLs from volumes.

Behavior

Shared volume data is external to VM memory and mutable rootfs snapshots. Hibernate, resume, and fork remount shared volumes; they do not make external storage part of VM memory snapshots. Runtime attachment operations return attachment records with mounted, released, or failed state. Destroying the machine releases remaining attachments. Hibernating or pausing a machine releases live mount leases while the VM is stopped, but it preserves attachment intent and remounts those volumes on resume. In 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. There is no public resize API for private beta.

Get started

Machines

Commands

Filesystem

Code Interpreter

Desktop

Templates

Networking

Interactive access

Observability

Volumes

When To Use Volumes

Quick Example

Mounts Vs Direct File APIs

Volume Tasks

Managing volumes

Mounting volumes

Read and write

File and directory metadata

Upload data

Download data

Behavior

​When To Use Volumes

​Quick Example

​Mounts Vs Direct File APIs

​Volume Tasks

Managing volumes

Mounting volumes

Read and write

File and directory metadata

Upload data

Download data

​Behavior

​Related

When To Use Volumes

Quick Example

Mounts Vs Direct File APIs

Volume Tasks

Behavior

Related