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

> Python SDK object reference for persistent volumes and direct volume files.

Volumes persist data independently of a machine. Mount them into machines for
runtime access, or manage their files directly through `volume.files`.

## Volume Objects

| Method                                                                        | Use                                                            |
| ----------------------------------------------------------------------------- | -------------------------------------------------------------- |
| `Volume.create(name=...)`                                                     | Create a persistent volume.                                    |
| `Volume.get(id)` / `Volume.from_id(id)`                                       | Load by ID.                                                    |
| `Volume.get_by_name(name)` / `Volume.from_name(name, create_if_missing=True)` | Load by name, optionally creating it.                          |
| `Volume.list(...)`                                                            | List volumes with filters and field selection.                 |
| `volume.get_info(fields=...)`                                                 | Refresh or inspect volume metadata.                            |
| `volume.delete()`                                                             | Delete the volume and its persistent data.                     |
| `volume.mount(path=..., read_only=False, subpath=None)`                       | Create a mount descriptor for `Machine.create(volumes=[...])`. |
| `volume.attachments()`                                                        | List machine attachments that currently reference the volume.  |

Use `volume.mount(...)` for create-time machine mounts. Use
`machine.attach_volume(...)`, `machine.detach_volume(...)`,
`machine.get_volume_health(...)`, and `machine.remount_volume(...)` for runtime
attachment management on a running machine.

## Direct Volume Files

| Namespace                                                         | Use                                                 |
| ----------------------------------------------------------------- | --------------------------------------------------- |
| `volume.files.read/write/write_files`                             | Manage persistent files without starting a machine. |
| `volume.files.list/info/exists`                                   | Inspect volume paths and metadata.                  |
| `volume.files.upload_file/upload_dir/resume_upload`               | Upload data directly to a volume.                   |
| `volume.files.download_file/download_dir`                         | Download files or directory archives.               |
| `volume.files.find_files/search_files/replace_in_files/watch_dir` | Search, replace, and watch persistent data.         |

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

with Machine.create(template="base", volumes=[volume.mount("/data")]) as machine:
    machine.commands.run("echo hello > /data/hello.txt", shell=True)

print(volume.files.read("/hello.txt"))
```

## Related

* [Volumes guide](../../volumes/overview)
* [Direct volume files](../../volumes/files)
* [Volume transfers](../../volumes/transfers)