> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ns.rocks/llms.txt
> Use this file to discover all available pages before exploring further.

# Volumes

> Create, mount, and manage durable shared filesystems.

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.

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

## 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.

```python theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
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())
```

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
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

<CardGroup cols={2}>
  <Card title="Managing volumes" href="./managing-volumes">
    Create, list, inspect, field-select, and delete volume metadata.
  </Card>

  <Card title="Mounting volumes" href="./mounting-volumes">
    Attach volumes at create time or runtime, including read-only and subpath mounts.
  </Card>

  <Card title="Read and write" href="./read-write">
    Read, write, batch-write, move, remove, and edit direct volume files.
  </Card>

  <Card title="File and directory metadata" href="./file-directory-metadata">
    List directories, stat paths, check existence, search, replace, and watch changes.
  </Card>

  <Card title="Upload data" href="./upload-data">
    Upload files, directories, stdin streams, and resumable transfers into volumes.
  </Card>

  <Card title="Download data" href="./download-data">
    Download files, directories, archives, and signed URLs from volumes.
  </Card>
</CardGroup>

## 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.

## Related

* [Filesystem](../filesystem)
* [Python SDK volumes](../guides/python-sdk/volumes)
* [CLI volume commands](../cli/manage-volumes)
* [Shared volume example](../examples/shared-volume)