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

# Manage Volumes

> Create, mount, inspect, transfer, and edit persistent volumes from the CLI.

Use `nullspace volume ...` to manage durable shared filesystems without starting
a machine. Use `nullspace machine create --volume ...` to mount a volume into a
new machine.

## Create And Inspect

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
nullspace volume create team-data
nullspace volume list
nullspace volume list --fields id,name,mount_count,used_bytes
nullspace volume get team-data
nullspace volume get team-data --fields id,status,max_size_bytes
```

`volume get` accepts a volume ID such as `vol_...` or an exact volume name.
`--fields` returns compact metadata for scripts.

## Mount Into A Machine

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
nullspace machine create \
  --template base \
  --volume ref=team-data,mount=/data
```

Mount a subdirectory read-only:

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
nullspace machine create \
  --template base \
  --volume ref=team-data,mount=/models,subpath=/published-models,ro=true
```

`ref` can be a volume name or ID. `mount` must be an absolute machine path.
`subpath` is resolved inside the volume. `ro=true` makes the machine mount
read-only, but callers with API access can still modify the volume through
direct `nullspace volume ...` commands.

The CLI currently supports create-time volume mounts. Use the Python SDK or
HTTP API to attach, detach, check health, or remount a volume on an already
running machine. Destroying a machine releases its remaining volume
attachments. `nullspace machine hibernate` releases live mount leases while
stopped, but preserves attachment intent and remounts the same volumes on
resume.

## Read And Write Direct Files

Direct volume file paths are volume-internal absolute paths rooted at `/`.

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
nullspace volume ls-files team-data /
nullspace volume cat team-data /README.md
nullspace volume read team-data /models/manifest.json
nullspace volume read team-data /models/model.bin --encoding base64
printf "hello\n" | nullspace volume write team-data /hello.txt
printf 'Zm9vCg==' | nullspace volume write team-data /foo.txt --encoding base64
```

Write many small files with JSON or `@file.json`:

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
nullspace volume write-files team-data '[["/a.txt","a\n"],["/b.txt","b\n"]]'
nullspace volume write-files team-data @files.json
```

## Manage Paths

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
nullspace volume exists team-data /models/model.bin
nullspace volume info team-data /models/model.bin
nullspace volume stat team-data /models/model.bin
nullspace volume mkdir team-data /models
nullspace volume mv team-data /models/old.bin /models/new.bin
nullspace volume chmod team-data /models/new.bin 0644
nullspace volume rm team-data /tmp/old.bin
```

`exists` exits with status `0` when the path exists and `1` when it does not.
`info` and `stat` both return metadata JSON.

## Search, Replace, And Watch

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
nullspace volume find team-data /models "weights"
nullspace volume search team-data /models "*.bin"
nullspace volume replace team-data "old" "new" /models/config.json --dry-run
nullspace volume watch team-data /models --recursive --timeout 30
```

`find` searches file contents. `search` matches file names. `replace` returns a
structured replacement result, including dry-run details. `watch` streams JSON
events until interrupted or until `--timeout` expires.

## Upload And Download

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
nullspace volume upload team-data ./model.bin /models/model.bin
nullspace volume upload team-data ./models /models --concurrency 4
nullspace volume upload team-data ./models /models --conflict merge --exclude '*.tmp'
nullspace volume upload team-data ./large.bin /models/large.bin \
  --resumable always \
  --checksum auto \
  --concurrency 4
```

Resume a failed upload with the reported upload ID:

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
nullspace volume upload team-data ./large.bin /models/large.bin --resume upload_123
```

Download files or directories:

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
nullspace volume download team-data /models/model.bin ./model.bin --force
nullspace volume download team-data /datasets ./datasets-copy --force
nullspace volume download team-data /datasets ./datasets.tar --archive --force --json
```

`--force` overwrites an existing local destination. Directory downloads extract
by default; `--archive` keeps the downloaded tar archive.

## Signed URLs

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
nullspace volume upload-url team-data /models/model.bin
nullspace volume download-url team-data /models/model.bin
nullspace volume download-url team-data /datasets --archive-format tar
```

Use signed URLs when a browser, CI job, or another service should transfer data
directly.

## Delete

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
nullspace volume delete vol_12345678
```

Delete by volume ID. Deleting an attached volume can be rejected; destroy
attached machines before retrying. Hibernating a machine is not a volume detach
operation because the attachment remounts on resume.

## Related

* [Volumes](../volumes/overview)
* [Direct Volume Files](../volumes/files)
* [Volume Transfers](../volumes/transfers)
* [CLI Reference](../reference/cli)