> ## Documentation Index
> Fetch the complete documentation index at: https://blaxel-feat-keep-alive-timeout-clarification.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/Volumes/Volumes-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.

<Accordion title="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.
</Accordion>

<CodeGroup>
  ```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
  ```
</CodeGroup>

You can create a volume from a [template](/Volumes/Volumes-templates) to automatically pre-populate it with files.

<CodeGroup>
  ```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
  ```
</CodeGroup>

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

<CodeGroup>
  ```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
  ```
</CodeGroup>

## Delete a volume

Delete a volume by calling:

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

  <CodeGroup>
    ```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")
    ```
  </CodeGroup>

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

  <CodeGroup>
    ```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()
    ```
  </CodeGroup>

## Resize a volume

<Note>Currently, it is only possible to increase the volume size (not decrease it).</Note>

Resize a volume by calling:

* the class-level `update()` method with the volume `name` and new size as argument, or

  <CodeGroup>
    ```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 })
    ```
  </CodeGroup>

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

  <CodeGroup>
    ```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 })
    ```
  </CodeGroup>

## List volumes

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

<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.
</Note>

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.
</Tip>

For more information, refer to the [API reference documentation](/api-reference/introduction#pagination).

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

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

<CodeGroup>
  ```typescript TypeScript theme={null}
  const volumes = await VolumeInstance.list()
  ```

  ```python Python theme={null}
  volumes = await VolumeInstance.list()
  ```

  ```shell Blaxel CLI theme={null}
  bl get volumes
  ```
</CodeGroup>

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

<CardGroup cols={2}>
  <Card title="Use volumes with sandboxes" icon="box" href="/Sandboxes/Volumes">
    Attach persistent storage to a sandbox at creation time.
  </Card>

  <Card title="Use volumes with agents" icon="robot" href="/Agents/Volumes">
    Attach persistent storage to a deployed agent via `blaxel.toml`.
  </Card>
</CardGroup>