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

# Managing volumes

> Create, list, inspect, field-select, and delete persistent volumes.

Use volume management APIs for metadata and lifecycle operations. Direct file
operations live on `volume.files` and are covered in the file task pages.

## Create

<CodeGroup>
  ```python Python SDK theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  from nullspace import Volume

  volume = Volume.create("team-data")
  print(volume.id, volume.name, volume.status)
  ```

  ```typescript TypeScript SDK theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  import { NullspaceClient } from "nullspace";

  const client = new NullspaceClient();
  const volume = await client.volumes.create("team-data");
  console.log(volume.id, volume.name, volume.status);
  ```

  ```bash CLI theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  nullspace volume create team-data
  ```

  ```bash HTTP API theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  curl -X POST "${NULLSPACE_API_URL}/v1/volumes" \
    -H "Authorization: Bearer ${NULLSPACE_API_KEY}" \
    -H "Content-Type: application/json" \
    -d '{"name": "team-data"}'
  ```
</CodeGroup>

Use `Volume.from_name(..., create_if_missing=True)` when setup scripts should be
idempotent:

```python theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
volume = Volume.from_name("team-data", create_if_missing=True)
```

## Get

<CodeGroup>
  ```python Python SDK theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  by_id = Volume.get("vol_123")
  by_name = Volume.get_by_name("team-data")
  print(by_name.used_bytes, by_name.max_size_bytes)
  ```

  ```typescript TypeScript SDK theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  const byId = await client.volumes.get("vol_123");
  const byName = await client.volumes.getByName("team-data");
  console.log(byName.usedBytes, byName.maxSizeBytes);
  ```

  ```bash CLI theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  nullspace volume get team-data
  nullspace volume get vol_123
  ```

  ```bash HTTP API theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  curl -X GET "${NULLSPACE_API_URL}/v1/volumes/vol_123" \
    -H "Authorization: Bearer ${NULLSPACE_API_KEY}"

  curl -X GET "${NULLSPACE_API_URL}/v1/volumes/by-name/team-data" \
    -H "Authorization: Bearer ${NULLSPACE_API_KEY}"
  ```
</CodeGroup>

`Volume.from_id(id)` is an alias for `Volume.get(id)`.

## List

<CodeGroup>
  ```python Python SDK theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  for item in Volume.list():
      print(item.id, item.name, item.status, item.mount_count)
  ```

  ```typescript TypeScript SDK theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  for (const item of await client.volumes.list()) {
    console.log(item.id, item.name, item.status, item.mountCount);
  }
  ```

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

  ```bash HTTP API theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  curl -X GET "${NULLSPACE_API_URL}/v1/volumes" \
    -H "Authorization: Bearer ${NULLSPACE_API_KEY}"
  ```
</CodeGroup>

## Select Fields

Use `fields=` when dashboards or scripts only need a few metadata attributes.
When fields are requested, the SDK returns raw dictionaries instead of
`VolumeInfo` objects.

<CodeGroup>
  ```python Python SDK theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  rows = Volume.list(fields=["id", "name", "mount_count", "used_bytes"])
  info = Volume.get_by_name("team-data", fields=["id", "status", "max_size_bytes"])
  ```

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

  ```bash HTTP API theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  curl -X GET "${NULLSPACE_API_URL}/v1/volumes?fields=id,name,mount_count,used_bytes" \
    -H "Authorization: Bearer ${NULLSPACE_API_KEY}"

  curl -X GET "${NULLSPACE_API_URL}/v1/volumes/by-name/team-data?fields=id,status,max_size_bytes" \
    -H "Authorization: Bearer ${NULLSPACE_API_KEY}"
  ```
</CodeGroup>

## Refresh Metadata

```python theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
info = volume.get_info()
print(info.used_bytes, info.max_size_bytes)
```

Refresh metadata after large writes when you need current capacity and usage.
`used_bytes` is observed usage from the latest reconciliation.
`max_size_bytes` is the current enforced cap. In the 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.

## Delete

<CodeGroup>
  ```python Python SDK theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  volume.delete()
  ```

  ```typescript TypeScript SDK theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  await client.volumes.delete("vol_123");
  ```

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

  ```bash HTTP API theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  curl -X DELETE "${NULLSPACE_API_URL}/v1/volumes/vol_123" \
    -H "Authorization: Bearer ${NULLSPACE_API_KEY}"
  ```
</CodeGroup>

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

## Async

```python theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
from nullspace import AsyncVolume

volume = await AsyncVolume.from_name("team-data", create_if_missing=True)
info = await volume.get_info()
await volume.delete()
```

## Related

* [Mounting volumes](./mounting-volumes)
* [Read & write](./read-write)
* [CLI volume commands](../cli/manage-volumes)