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

# Manage volumes

> Publish new volume versions, roll back, inspect and download data, and delete or restore versions.

Use the [`baseten volume`](/reference/cli/baseten/volume) commands to publish new versions, roll back a deployment, inspect and download data, and delete or restore versions. For how versions, tags, and references work, see [Volumes](/development/volumes/overview).

## Publish a new version

Each push seals a new version. Pass `--tag` to move a tag to it; only the chunks that changed upload:

```sh theme={"system"}
baseten volume push ./model-assets bdn:<namespace>/model-assets --tag prod
```

List the volume's versions, newest first, and check where a tag points:

```sh theme={"system"}
baseten volume versions bdn:<namespace>/model-assets
baseten volume stat bdn:<namespace>/model-assets:prod --full-ref
```

To serve the new version from a deployment that pins a digest, set `source` in `bdn.mounts` to the new version's reference and redeploy. A push fails if another push to the same volume is in progress; run it again.

## Roll back a deployment

The CLI can't move a tag to an existing version. To roll back, find the earlier version's digest with `baseten volume versions`, set `source` in `bdn.mounts` to that version's reference, and redeploy.

## Inspect and download data

| Command | Use |
| - | - |
| `baseten volume ls [REF]` | List namespaces with no reference, volumes in a namespace, or entries in a version. Add `--recursive` for the full tree. |
| `baseten volume stat REF` | Show metadata for a volume, version, directory, or file, including expiration. Add `--full-ref` to resolve a tag to its immutable reference. |
| `baseten volume cat REF` | Write one file's bytes to stdout. `cat` rejects `--output` and `--jq`. |
| `baseten volume pull REF DIR` | Download a version, a directory in it, or selected paths. |

Download a version or a directory in it:

```sh theme={"system"}
baseten volume pull bdn:<namespace>/model-assets:prod ./download
```

Download selected files into an existing directory:

```sh theme={"system"}
baseten volume pull bdn:<namespace>/model-assets:prod ./download --include "config/**" --overwrite
```

For large transfers, tune concurrency and memory using the [push](/reference/cli/baseten/volume#push) and [pull](/reference/cli/baseten/volume#pull) options:

```sh theme={"system"}
baseten volume pull bdn:<namespace>/model-assets:prod ./download --chunk-operations 8 --max-in-flight-mib 512
baseten volume push ./model-assets bdn:<namespace>/model-assets --file-jobs 16
```

For all download options, including path filtering and restarting partial downloads, see [`baseten volume pull`](/reference/cli/baseten/volume#pull).

## Delete and restore a version

`baseten volume rm` deletes one version selected by digest, or every version of a volume with `--recursive`:

```sh theme={"system"}
baseten volume rm bdn:<namespace>/model-assets@<digest> --yes
```

A deleted version stays restorable for 7 days. List deleted versions with `--include-tombstoned`, and restore one by its full digest:

```sh theme={"system"}
baseten volume versions bdn:<namespace>/model-assets --include-tombstoned
baseten volume restore bdn:<namespace>/model-assets@<full-digest>
```

Restoring a version doesn't restore its tags. Point deployments at the restored version's digest, or push again with `--tag`.

<Warning>
  Deleting a version that a deployment mounts doesn't stop its running replicas, but new replicas, including scale-ups, fail to start. Move every deployment to another version before you delete one.
</Warning>

## Mount paths

Each entry in `bdn.mounts` mounts one volume read-only at `path`. BDN rejects a mount path that:

* Isn't absolute, is `/`, or contains `..`.
* Is a system root: `/bin`, `/dev`, `/etc`, `/lib`, `/lib64`, `/proc`, `/run`, `/sbin`, `/sys`, `/tmp`, `/usr`, or `/var`. You can mount at a subdirectory such as `/usr/share/models` unless it overlaps a runtime path.
* Is in a tree Baseten reserves: `/app`, `/bdn`, `/bptr`, `/cache`, `/control`, `/probe-bin`, `/scratch`, or `/secrets`.
* Overlaps a path the model container uses, such as `/dev/shm`, `/etc/ssl/certs`, `/root/.cache/huggingface`, `/usr/bin`, or `/usr/local/bin`.
* Repeats another mount's path or a [`weights`](/development/model/bdn#weights) `mount_location`.

Use a path under `/mnt`, such as `/mnt/data`.

## Namespaces Baseten manages

Baseten stores platform data, such as startup caches, container images, and snapshots, in volumes under your organization. You may see namespaces such as `caches`, `images`, and `snapshots` in `baseten volume ls`. These namespaces are read-only and Baseten manages their lifecycle, so you can't create, push, or delete volumes under them.

For volume mount errors and replica startup failures, see [BDN volume troubleshooting](/troubleshooting/deployments#bdn-volumes).