> ## Documentation Index
> Fetch the complete documentation index at: https://namespace.so/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Inspect and release volumes
> List, describe, and destroy cache volumes, persistent volumes, and snapshots with the TypeScript SDK.
`client.storage` covers the two volume types Namespace attaches to instances. [Cache volumes](/docs/architecture/storage/cache-volumes) are identified by a tag and reused across runs, with one generation per use. Persistent volumes are block volumes with their own identity and snapshots.
The examples on this page use a Compute client:
```typescript theme={null}
import { createComputeClient } from "@namespacelabs/sdk/api/compute";
const client = createComputeClient();
```
## `storage.listCacheVolumes()`
Return every cache volume in the workspace.
Example
```typescript {1} theme={null}
const { cacheVolume } = await client.storage.listCacheVolumes({});
for (const volume of cacheVolume) {
console.log(volume.id, volume.tag, volume.metadata?.sizeMb);
}
```
API reference
```typescript theme={null}
listCacheVolumes(
request: MessageInitShape,
options?: CallOptions,
): Promise
```
Arguments and options
The request has no fields. Pass an empty object.
Cancellation, timeout, and header options. See [Shared call options](/docs/reference/typescript-sdk/compute/manage#shared-call-options).
Return value
Returns a `ListCacheVolumesResponse` with `cacheVolume`, a list of `CacheVolume`. Each entry carries `id`, `tag`, `metadata` with the lifecycle timestamps, size, and state, and `attachment` with the instance the volume was attached to and its utilization.
***
## `storage.getCacheVolume()`
Return a single cache volume generation by ID.
Example
```typescript {1} theme={null}
const { cacheVolume } = await client.storage.getCacheVolume({ id: volumeId });
console.log(cacheVolume?.metadata?.state);
```
API reference
```typescript theme={null}
getCacheVolume(
request: MessageInitShape,
options?: CallOptions,
): Promise
```
Arguments and options
The unique identifier of the cache volume generation. A single tag can have multiple generations over time.
Cancellation, timeout, and header options. See [Shared call options](/docs/reference/typescript-sdk/compute/manage#shared-call-options).
Return value
Returns a `GetCacheVolumeResponse` with the matching `cacheVolume`.
***
## `storage.listVolumeTagSummaries()`
Summarize every cache volume tag in the workspace. Use this to see cache usage per tag rather than per generation.
```typescript {1} theme={null}
const { summaries } = await client.storage.listVolumeTagSummaries({});
for (const summary of summaries) {
console.log(summary.tag, summary.sizeMb, summary.generations.length);
}
```
```typescript theme={null}
listVolumeTagSummaries(
request: MessageInitShape,
options?: CallOptions,
): Promise
```
The request has no fields. Pass an empty object.
Cancellation, timeout, and header options. See [Shared call options](/docs/reference/typescript-sdk/compute/manage#shared-call-options).
Returns a `ListVolumeTagSummariesResponse` with `summaries`, a list of `TagSummary`. Each summary carries the `tag`, its requested `sizeMb`, and the `generations` that belong to it.
***
## `storage.getVolumeTagSummary()`
Summarize a single cache volume tag.
```typescript {1} theme={null}
const { summary } = await client.storage.getVolumeTagSummary({ tag: "node-modules" });
console.log(summary?.sizeMb);
```
```typescript theme={null}
getVolumeTagSummary(
request: MessageInitShape,
options?: CallOptions,
): Promise
```
The name of the cache volume tag.
Cancellation, timeout, and header options. See [Shared call options](/docs/reference/typescript-sdk/compute/manage#shared-call-options).
Returns a `GetVolumeTagSummaryResponse` with the matching `TagSummary`.
***
## `storage.destroyCacheVolume()`
Release all cache volumes that belong to a tag.
Example
```typescript {1} theme={null}
await client.storage.destroyCacheVolume({ tag: "node-modules" });
```
API reference
```typescript theme={null}
destroyCacheVolume(
request: MessageInitShape,
options?: CallOptions,
): Promise
```
Arguments and options
The cache volume tag to release.
Cancellation, timeout, and header options. See [Shared call options](/docs/reference/typescript-sdk/compute/manage#shared-call-options).
Return value
Returns an empty response. Omitting the tag fails with `InvalidArgument`, and an unknown tag fails with `NotFound`.
Releasing a cache volume cannot be undone. The next run that uses the tag starts from an empty cache.
***
## `storage.listPersistentVolumes()`
Return one page of persistent volumes, optionally filtered by tag and site.
Example
```typescript {1-4} theme={null}
const page = await client.storage.listPersistentVolumes({
tag: "workspace-data",
maxEntries: 50n,
});
for (const volume of page.volumes) {
console.log(volume.id, volume.site, volume.attachedTo);
}
```
API reference
```typescript theme={null}
listPersistentVolumes(
request: MessageInitShape,
options?: CallOptions,
): Promise
```
Arguments and options
Only return volumes with this tag. When omitted, all persistent volumes are returned.
Only query the matching sites. When omitted, all sites are queried.
The maximum number of entries to return. The service may return fewer.
The `paginationCursor` from a previous response, to continue reading results.
Cancellation, timeout, and header options. See [Shared call options](/docs/reference/typescript-sdk/compute/manage#shared-call-options).
Return value
Returns a `ListPersistentVolumesResponse` with `volumes` and a `paginationCursor`. A set cursor means more results are available. Each `PersistentVolume` carries `id`, `tag`, `sizeMb`, `site`, `createdAt`, `attachedTo`, and the release and destruction timestamps.
***
## `storage.describePersistentVolume()`
Return details of a single persistent volume.
Example
```typescript {1-4} theme={null}
const { volume } = await client.storage.describePersistentVolume({
id: volumeId,
tag: "workspace-data",
});
console.log(volume?.sizeMb, volume?.attachedTo);
```
API reference
```typescript theme={null}
describePersistentVolume(
request: MessageInitShape,
options?: CallOptions,
): Promise
```
Arguments and options
The unique identifier of the persistent volume.
The tag of the persistent volume.
The site the volume is located in. When provided, only that site is queried.
Cancellation, timeout, and header options. See [Shared call options](/docs/reference/typescript-sdk/compute/manage#shared-call-options).
Return value
Returns a `DescribePersistentVolumeResponse` with the matching `volume`. If the volume does not exist, the call fails with `NotFound`.
***
## `storage.destroyPersistentVolumes()`
Destroy every persistent volume that matches the given criteria.
Example
```typescript {1,4-6} theme={null}
import { StringMatcher_Operator } from "@namespacelabs/sdk/proto/namespace/stdlib/matchers_pb";
const { destroyedVolumes } = await client.storage.destroyPersistentVolumes({
tag: {
values: ["workspace-data"],
op: StringMatcher_Operator.IS_ANY_OF,
},
});
console.log(`destroyed ${destroyedVolumes.length} volumes`);
```
API reference
```typescript theme={null}
destroyPersistentVolumes(
request: MessageInitShape,
options?: CallOptions,
): Promise
```
Arguments and options
At least one of `id` or `tag` must be set. For safety the service rejects the `IS_NOT` operator.
Matches volumes by ID.
Matches volumes by tag.
Cancellation, timeout, and header options. See [Shared call options](/docs/reference/typescript-sdk/compute/manage#shared-call-options).
Return value
Returns a `DestroyPersistentVolumesResponse` with `destroyedVolumes`, the metadata of the volumes that were destroyed.
Omitting both matchers or using `IS_NOT` fails with `InvalidArgument`. When no volume matches, the call fails with `NotFound`.
***
## `storage.listPersistentVolumeSnapshots()`
Return every snapshot of a persistent volume.
Example
```typescript {1-4} theme={null}
const { snapshots } = await client.storage.listPersistentVolumeSnapshots({
id: volumeId,
tag: "workspace-data",
});
for (const snapshot of snapshots) {
console.log(snapshot.id, snapshot.usedBytes, snapshot.abandonedAt);
}
```
API reference
```typescript theme={null}
listPersistentVolumeSnapshots(
request: MessageInitShape,
options?: CallOptions,
): Promise
```
Arguments and options
The unique identifier of the persistent volume.
The tag of the persistent volume.
The site the volume is located in. When provided, only that site is queried.
Cancellation, timeout, and header options. See [Shared call options](/docs/reference/typescript-sdk/compute/manage#shared-call-options).
Return value
Returns a `ListPersistentVolumeSnapshotsResponse` with `snapshots`. Each `PersistentVolumeSnapshot` carries `id`, `createdAt`, `usedBytes`, `netNewUsedBytes`, the parent in `snapshotFrom`, and the attachment and release state.
***
## `storage.destroyPersistentVolumeSnapshot()`
Mark a snapshot as abandoned. Abandoned snapshots are excluded when Namespace selects a base snapshot for new volumes, which is useful for skipping a corrupted snapshot without destroying the volume.
Example
```typescript {1-4} theme={null}
const { snapshot } = await client.storage.destroyPersistentVolumeSnapshot({
id: volumeId,
tag: "workspace-data",
});
console.log(snapshot?.abandonedAt);
```
API reference
```typescript theme={null}
destroyPersistentVolumeSnapshot(
request: MessageInitShape,
options?: CallOptions,
): Promise
```
Arguments and options
The unique identifier of the snapshot, which is the volume ID.
The tag of the persistent volume.
The site the volume is located in. When provided, only that site is queried.
Cancellation, timeout, and header options. See [Shared call options](/docs/reference/typescript-sdk/compute/manage#shared-call-options).
Return value
Returns a `DestroyPersistentVolumeSnapshotResponse` with the abandoned `snapshot`.
If the snapshot does not exist, the call fails with `NotFound`. If it is still attached to an instance, the call fails with `FailedPrecondition`.
## Related documentation
Cache volumes, artifact storage, and the container registry.
Report on cache and persistent volume storage.