Volumes

A volume is a named, versioned set of files that the Baseten Delivery Network (BDN) delivers to your deployments. You publish a directory once, and every deployment that references it mounts the same files, read-only, wherever it runs. A volume does for model weights and data what a container image does for code.

​

Versions, tags, and digests

A volume holds a series of sealed versions. When baseten volume push or baseten volume sync finishes, BDN commits the files as a new version and seals it. A sealed version never changes, and BDN identifies it by a digest of its contents, such as bdn:weights/llama@b3:9f3c….

• Namespace: groups volumes in your organization, such as weights.
• Volume: one versioned collection of files, such as llama.
• Version: one sealed, immutable snapshot of the volume, identified by its digest.
• Tag: a mutable, case-sensitive name that points at one version, such as prod. Pushing with --tag prod moves the tag to the new version.
• Head: the default tag, normally pointing at the volume’s latest version. You can move it to another version. File reads and deployment mounts use head when the reference has no tag or digest.

Sealing makes volumes safe to depend on:

• Reproducible deployments: a deployment that mounts a digest gets the same bytes on every replica.
• Small updates: BDN splits files into chunks and stores each chunk once, so a new checkpoint that shares most of its bytes with the previous one uploads only the chunks that changed.
• Fast starts: deployments don’t download the volume before they start. Data streams in as your model reads it.

​

Volume references

Use a bdn: reference to identify a namespace, volume, version, or path within your Baseten organization. Your Baseten credentials select the organization, so the reference doesn’t include an organization name. Write bdn: without //. The Baseten CLI rejects bdn:// references, and cross-organization references aren’t supported. Use a full digest or a unique prefix of 12 to 64 hexadecimal characters. To pin a version in commands or config.yaml, copy its version_ref from the CLI output. A volume reference without a tag or digest names the volume. File access and deployment mounts use its head version. stat returns metadata for the volume itself, and versions lists its versions. Namespace and volume names can be up to 256 characters and can’t contain /, .., or null bytes. Tags can be up to 128 characters: letters, digits, underscores, periods, and hyphens, starting with a letter, digit, or underscore. Namespace names are lowercase letters, digits, and hyphens, at least two characters long, and can’t start with a digit. You can’t name a namespace namespaces or resolve.

​

How deployments resolve tags

When a deployment mounts a tag or a bare volume name, each replica resolves it when the replica starts and keeps that version for its lifetime. Moving the tag later doesn’t change what running replicas serve, but new and scaled-up replicas mount the tag’s new target. A deployment that mounts a tag can therefore serve two versions at once after a push. Pin a digest in config.yaml so every replica serves the same files, and use tags to name versions for people.

​

Requirements

• Install the Baseten CLI.
• Choose a CPU instance or a GPU instance with an accelerator other than NVIDIA T4 or L4.

​

Publish, mount, and deploy a volume

This walkthrough publishes a small directory as a volume, mounts it in a model, and deploys the model. To publish a volume and mount it in a deployment:

1. Create a directory with a few files:
   mkdir -p model-assets/config
   printf 'hello from a BDN volume\n' > model-assets/message.txt
   printf '{"revision": 1}\n' > model-assets/config/metadata.json
   
2. Push the directory as a new volume and tag the version prod. push creates the namespace and volume if they don’t exist, and --jq prints the new version’s immutable reference:
   baseten volume push ./model-assets bdn:<namespace>/model-assets --tag prod --jq '.version_ref'
   
   Save the printed reference. The rest of this walkthrough calls it <version-ref>.
3. Inspect the published version:
   baseten volume ls <version-ref> --recursive
   baseten volume cat <version-ref>/message.txt
   
4. Create a model directory named volume-quickstart with a config.yaml that mounts the version. Pinning the digest means later pushes can’t change what this deployment mounts:
   config.yaml

   model_name: volume-quickstart
   python_version: py311
   resources:
     cpu: "1"
     memory: 2Gi
     use_gpu: false
   bdn:
     mounts:
       - source: <version-ref>
         path: /mnt/model-assets
   
5. Add a model/model.py that reads the mounted files:
   model/model.py

   import json
   from pathlib import Path
   
   
   class Model:
       def load(self):
           root = Path("/mnt/model-assets")
           self.message = (root / "message.txt").read_text().strip()
           self.metadata = json.loads((root / "config" / "metadata.json").read_text())
   
       def predict(self, model_input):
           return {"message": self.message, "metadata": self.metadata}
   
6. Deploy the model from the volume-quickstart directory:
   baseten model push --wait --tail
   
7. Call the deployment with the predict URL from the push output:
   curl -sS -X POST "<predict-url>" \
     -H "Authorization: Bearer $BASETEN_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{}'
   
   The response includes the message and metadata read from the volume.

​

Next steps