> ## 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.

# Volumes

> 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](https://docs.blaxel.ai/Volumes/Volumes-templates.md) 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.

> [!TIP]
>
> Refer to our [blog post on choosing the right storage for your Blaxel agents](https://blaxel.ai/blog/choose-the-right-storage-for-your-blaxel-agents) for more information.

## 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.

> [accordion] 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](https://app.blaxel.ai/profile/security). 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:
>
> ```bash theme={null}
> 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 TypeScript theme={null}
import { VolumeInstance } from "@blaxel/core";

const volume = await VolumeInstance.create({
  name: "my-volume",
  size: 2048,          // in MB
  region: "us-pdx-1",
});
```

```python Python theme={null}
from blaxel.core import VolumeInstance

volume = await VolumeInstance.create({
  "name": "my-volume",
  "size": 2048,          # in MB
  "region": "us-pdx-1",
})
```

```bash Blaxel CLI theme={null}
bl apply -f - <<EOF
kind: Volume
metadata:
  name: my-volume
spec:
  size: 2048
  region: us-pdx-1
EOF
```

You can create a volume from a [template](https://docs.blaxel.ai/Volumes/Volumes-templates.md) to automatically pre-populate it with files.

```typescript TypeScript theme={null}
const volume = await VolumeInstance.createIfNotExists({
  name: "myvolume",
  template: "mytemplate:1",  // Use template-name:revision or template-name:latest
  region: "us-pdx-1",
});
```

```python Python theme={null}
volume = await VolumeInstance.create_if_not_exists({
  "name": "myvolume",
  "template": "mytemplate:1",  # Use template-name:revision or template-name:latest
  "region": "us-pdx-1",
})
```

```bash Blaxel CLI theme={null}
bl apply -f - <<EOF
kind: Volume
metadata:
  name: myvolume
spec:
  region: us-pdx-1
  template: "mytemplate:1"
EOF
```

Labels are specified as key-value pairs during volume creation.

```typescript TypeScript theme={null}
const volume = await VolumeInstance.create({
  name: "my-volume",
  size: 2048,
  region: "us-pdx-1",
  labels: { env: "test", project: "12345" },
});
```

```python Python theme={null}
volume = await VolumeInstance.create({
  "name": "my-volume",
  "size": 2048,
  "region": "us-pdx-1",
  "labels": {"env": "test", "project": "12345"},
})
```

```bash Blaxel CLI theme={null}
bl apply -f - <<EOF
kind: Volume
metadata:
  name: my-volume
  labels:
    env: test
    project: 12345
spec:
  size: 2048
  region: us-pdx-1
EOF
```

## Delete a volume

Delete a volume by calling:

* the class-level `delete()` method with the volume `name` as argument, or

  ```typescript TypeScript theme={null}
  import { VolumeInstance } from "@blaxel/core";

  await VolumeInstance.delete("my-volume");
  ```

  ```python Python theme={null}
  from blaxel.core import VolumeInstance

  await VolumeInstance.delete("my-volume")
  ```

* the instance-level `delete()` method:

  ```typescript TypeScript theme={null}
  import { VolumeInstance } from "@blaxel/core";

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

  ```python Python theme={null}
  from blaxel.core import VolumeInstance

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

## Resize a volume

> [!NOTE]
>
> 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 TypeScript theme={null}
  import { VolumeInstance } from "@blaxel/core";

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

  ```python Python theme={null}
  from blaxel.core import VolumeInstance

  updated_volume = await VolumeInstance.update("my-volume", { "size": 1024 })
  ```

* the instance-level `update()` method with the new size as argument:

  ```typescript TypeScript theme={null}
  import { VolumeInstance } from "@blaxel/core";

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

  ```python Python theme={null}
  from blaxel.core import VolumeInstance

  volume = await VolumeInstance.get("my-volume")
  updated_volume = await volume.update({ "size": 1024 })
  ```

## List volumes

To retrieve all volumes in your workspace, use the built-in SDK pagination helper functions.

> [!NOTE]
>
> 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.

```typescript TypeScript theme={null}
import { VolumeInstance } from "@blaxel/core";

const volumes = await VolumeInstance.list({ limit: 50 });
for await (const volume of volumes) {
  console.log(volume.name);
}
```

```python Python theme={null}
import asyncio
from blaxel.core import VolumeInstance

async def main():
    volumes = await VolumeInstance.list(limit=50)
    async for volume in volumes.auto_paging_iter():
        print(volume.name)

asyncio.run(main())
```

```shell Blaxel CLI theme={null}
bl get volumes
```

For more information on the SDK pagination helpers, refer to the [SDK reference documentation](https://docs.blaxel.ai/sdk-reference/introduction.md#pagination).

Pagination is also available via the Management API list endpoint.

Request the first page:

```bash theme={null}
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:

```json theme={null}
{
  "data": [ ... ],
  "meta": {
    "hasMore": true,
    "nextCursor": "...",
    "total": 18
  }
}
```

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

```bash theme={null}
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'
```

> [!TIP]
>
> 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](https://docs.blaxel.ai/api-reference/introduction.md#pagination).

You can use labels for filtering volumes in the Blaxel CLI or Blaxel Console:

```shell theme={null}
# 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

> [card] [Use volumes with sandboxes](https://docs.blaxel.ai/Sandboxes/Volumes.md)
>
> Attach persistent storage to a sandbox at creation time.

> [card] [Use volumes with agents](https://docs.blaxel.ai/Agents/Volumes)
>
> Attach persistent storage to a deployed agent via `blaxel.toml`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.