Skip to main content
Blaxel Volumes are currently in private preview. Please contact us if you would like to get access before the public release date.
Blaxel Volumes provide persistent storage that survives sandbox destruction and recreation, enabling stateful development environments and data retention across VM lifecycle events. While Blaxel automatically snapshots the full state of a sandbox at scale down and stores it in a 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 sandbox.
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 { SandboxInstance, VolumeInstance } from "@blaxel/core";

const volume = await VolumeInstance.create({
  name: "my-volume",
  size: 2048,          // in MB
  region: "us-pdx-1",   // if not specified, Blaxel will choose a default region
  labels: { env: "test", project: "12345" }, // labels
});
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
});

Manage volume templates

Create volumes containing the same set of files every time.

​
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";

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

// Get existing volume
const volume = await VolumeInstance.get("my-volume");

// Delete volume using instance-level method
await volume.delete()

​
List volumes

To list existing volumes: 
const volumes = await VolumeInstance.list()

​
Attach a volume to a sandbox

At this time, you can only attach one volume to a sandbox. A volume can also only be attached to one sandbox at a time.
To use a volume, attach it when you create a sandbox by passing an array of volume configurations to the volumes property. Each configuration must include the name of the volume to attach and the mountPath where it will be accessible inside the sandbox’s filesystem. The mount path will override the existing content of a directory. 
const sandbox = await SandboxInstance.create({
  name: "my-sandbox",
  image: "blaxel/nextjs:latest",
  memory: 4096,
  region: "us-pdx-1",     // Must be the same region as the created volume
  volumes: [{
    name: "my-volume",     // Must match the name of the created volume
    mountPath: "/app",     // Directory inside the sandbox
    readOnly: false       // Set to true to prevent writes
  }],
  // ... other sandbox properties
});
Any files written to the /app directory within this sandbox will be stored on my-volume and will persist even if this sandbox is deleted. At this time, you cannot detach a volume from a sandbox.