Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.blaxel.ai/llms.txt

Use this file to discover all available pages before exploring further.

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. Volumes use block storage and can only be accessed by attaching them to a running sandbox or agent. They cannot be mounted locally on your machine. Blaxel also does not support mounting external storage (such as S3 buckets) as volumes.

​
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 requires two environment variables to authenticate:
VariableDescription
BL_WORKSPACEYour Blaxel workspace name
BL_API_KEYYour Blaxel API key
You can create an API key from the Blaxel console. Your workspace name is visible in the URL when you log in to the console (e.g. app.blaxel.ai/{workspace}).Set them as environment variables or add them to a .env file at the root of your project:
export BL_WORKSPACE=my-workspace
export BL_API_KEY=my-api-key
When developing locally, you can also log in to your workspace with Blaxel CLI (as shown above). This allows you to run Blaxel SDK functions that will automatically connect to your workspace without additional setup. When you deploy on Blaxel, authentication is handled automatically — no environment variables needed.
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.
Last modified on May 1, 2026