Volume templates

Volume templates let you create pre-populated volumes with files and directories, improving copy performance by up to 90% compared to cp -r. Use them to build development environments with pre-installed dependencies, datasets, or application code.

Create a volume template

Initialize a new template

To create a new volume template, use the following command:

bl new volume-template mytemplate

This creates a folder named mytemplate containing a blaxel.toml file with the following configuration:

type = "volume-template"
directory = "."          # Root of your volume - everything at and below this level will be copied
defaultSize = 2048       # Default size in MB for volumes created from this template

The directory field specifies which folder’s contents will be included in the template:

"." (default) - Includes everything in the template folder
"app" - Includes only files inside the app subdirectory
"src/data" - Includes only files inside the src/data subdirectory

For example, if you want to include only your application code without configuration files:

type = "volume-template"
directory = "app"        # Only files inside the 'app' folder will be copied
defaultSize = 2048

Deploy a volume template

Deploy your volume template to make it available for creating other volumes:

bl deploy

To preview the deployment without making changes:

bl deploy --dryrun

Each deployment creates a new revision of your template. Revisions are auto-incremented and versioned for rollback capabilities.

Use volume templates

Once deployed, you can create volumes from your template:

const volume = await VolumeInstance.createIfNotExists({
  name: "myvolume",
  template: "mytemplate:1"  // Use template-name:revision or template-name:latest
});

Override the default volume size if needed:

const volume = await VolumeInstance.createIfNotExists({
  name: "myvolume",
  template: "mytemplate:latest",
  size: 4096  // Override the default size if needed
});

Template revisions are incremental and auto-generated. The system maintains a limited number of versions for each template.

Manage volume templates

List all available templates in your workspace:

bl get volumetemplates

View details of a specific template, including size requirements:

bl get volumetemplate mytemplate

Size constraints

Volumes must be provisioned with sufficient space for the template content. If a volume is smaller than the template data, creation will fail with an error. Always add a delta (extra space) to your volume size beyond the template content size. This ensures you can add files to the volume after it’s attached. We recommend provisioning at least 20-30% extra space. To check your template directory size before deployment:

du -sh mytemplate

For example, if your template is 1.5GB, create volumes with at least 2GB of space:

const volume = await VolumeInstance.createIfNotExists({
  name: "myvolume",
  template: "mytemplate:latest",
  size: 2048  // 2GB for a 1.5GB template - leaves 500MB for new files
});

This helps you set an appropriate defaultSize in your blaxel.toml or specify the correct size when creating volumes.

Delete a template

To delete a volume template and all its associated revisions:

bl delete volumetemplate mytemplate

Deleting a template does not affect existing volumes created from that template. However, you won’t be able to create new volumes from deleted templates.

Limitations

Volume templates do not handle symlinks or hardlinks, which may cause unexpected behavior. In addition, symlinks pointing outside the template (for example, symlink -> /etc/hosts) are explicitly forbidden. In these cases, use a copy instead. As a result, using package managers like pnpm or uv may also behave unexpectedly if dependencies are vendored within the template.

Get Started

Sandboxes

Agent Drive

Volumes

Batch Jobs

Agents Hosting

MCP Servers Hosting

Model Gateway

Observability

Integrations

Administration & security

Troubleshooting