Skip to main content
Blaxel Volumes provide persistent storage that survives resource destruction and recreation, enabling stateful environments and data retention across lifecycle events. While Blaxel automatically snapshots the full state of a sandbox at scale down and stores it in warm storage for ultra-fast boot times, volumes offer a more cost-effective solution to persist files for weeks to years. Use volume templates to start from a pre-populated filesystem.

​
Create a volume

To create a standalone volume, you must provide a unique name and specify its size in megabytes (MB). You can also specify optional labels. This volume exists independently of any resource it may later be attached to.
The Blaxel SDK authenticates with your workspace using credentials from these sources, in priority order:
  1. when running on Blaxel, authentication is handled automatically
  2. variables in your .env file (BL_WORKSPACE and BL_API_KEY, or see this page for other authentication options).
  3. environment variables from your machine
  4. configuration file created locally when you log in through Blaxel CLI (or deploy on Blaxel)
When developing locally, the recommended method is to just log in to your workspace with Blaxel CLI. This allows you to run Blaxel SDK functions that will automatically connect to your workspace without additional setup. When you deploy on Blaxel, this connection persists automatically.When running Blaxel SDK from a remote server that is not Blaxel-hosted, we recommend using environment variables as described in the third option above.
import { VolumeInstance } from "@blaxel/core";

const volume = await VolumeInstance.create({
  name: "my-volume",
  size: 2048,          // in MB
  region: "us-pdx-1",
});
You can create a volume from a template to automatically pre-populate it with files. 
const volume = await VolumeInstance.createIfNotExists({
  name: "myvolume",
  template: "mytemplate:1",  // Use template-name:revision or template-name:latest
  region: "us-pdx-1",
});
Labels are specified as key-value pairs during volume creation. 
const volume = await VolumeInstance.create({
  name: "my-volume",
  size: 2048,
  region: "us-pdx-1",
  labels: { env: "test", project: "12345" },
});

​
Delete a volume

Delete a volume by calling:
  • the class-level delete() method with the volume name as argument, or 
    import { VolumeInstance } from "@blaxel/core";

await VolumeInstance.delete("my-volume");
  • by calling the instance-level delete() method: 
    import { VolumeInstance } from "@blaxel/core";

const volume = await VolumeInstance.get("my-volume");
await volume.delete()

​
Resize a volume

Currently, it is only possible to increase the volume size (not decrease it).
Resize a volume by calling:
  • the class-level update() method with the volume name and new size as argument, or 
    import { VolumeInstance } from "@blaxel/core";

const updatedVolume = await VolumeInstance.update("my-volume", { size: 1024 });
  • by calling the instance-level update() method with the new size as argument: 
    import { VolumeInstance } from "@blaxel/core";

const volume = await VolumeInstance.get("my-volume");
const updatedVolume = await volume.update({ size: 1024 });

​
List volumes

const volumes = await VolumeInstance.list()
You can use labels for filtering volumes in the Blaxel CLI or Blaxel Console: 
# Get volumes with specific label (e.g., env=test)
bl get volumes -o json | jq -r '.[] | select(.metadata.labels.env == "test") | .metadata.name'

​
Use volumes with sandboxes and agents

Use volumes with sandboxes

Attach persistent storage to a sandbox at creation time.

Use volumes with agents

Attach persistent storage to a deployed agent via blaxel.toml.