Volumes overview

Attach Blaxel volumes to sandboxes and other resources for persistent storage that survives recreation, enabling stateful environments.

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.

Learn more about authentication on Blaxel

The Blaxel SDK requires two environment variables to authenticate:

Variable	Description
BL_WORKSPACE	Your Blaxel workspace name
BL_API_KEY	Your 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.

TypeScript

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.

TypeScript

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.

TypeScript

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

  TypeScript

  import { VolumeInstance } from "@blaxel/core";
  
  await VolumeInstance.delete("my-volume");
  

• by calling the instance-level delete() method:

  TypeScript

  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

  TypeScript

  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:

  TypeScript

  import { VolumeInstance } from "@blaxel/core";
  
  const volume = await VolumeInstance.get("my-volume");
  const updatedVolume = await volume.update({ size: 1024 });
  

List volumes

To retrieve all volumes in your workspace, use the Management API list endpoint with pagination.

Pagination is recommended for list operations because retrieving all available resources in a single request is slow and resource-intensive, and therefore does not scale well.

Request the first page:

curl 'https://api.blaxel.ai/v0/volumes?limit=50' \
  -H 'X-Blaxel-Authorization: Bearer YOUR-API-KEY' \
  -H 'Blaxel-Version: 2026-04-28'

The response includes a data array and a meta object:

{
  "data": [ ... ],
  "meta": {
    "hasMore": true,
    "nextCursor": "...",
    "total": 18
  }
}

Pass meta.nextCursor as cursor on the next request and repeat until meta.hasMore is false:

curl 'https://api.blaxel.ai/v0/volumes?limit=50&cursor=NEXT_CURSOR' \
  -H 'X-Blaxel-Authorization: Bearer YOUR-API-KEY' \
  -H 'Blaxel-Version: 2026-04-28'

For accounts with multiple workspaces, specify the workspace as an additional request parameter, such as ?workspace=WORKSPACE_NAME&..., or via an additional X-Blaxel-Workspace: WORKSPACE_NAME header in the request.

For more information, refer to the API reference documentation.

It is also possible to list all volumes in a workspace using the SDKs.

This approach does not currently support pagination and is therefore not recommended when working with large lists.

TypeScript

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.