Volumes for sandboxes

Attach Blaxel Volumes to sandboxes for persistent storage that survives sandbox destruction and recreation, with mount path configuration.

Blaxel Volumes provide persistent storage that survives sandbox destruction and recreation.

For full documentation on creating, deleting, resizing, and listing volumes, see the Volumes overview.

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.

Use createIfNotExists() / create_if_not_exists() so that re-running your setup code is safe even if the sandbox already exists with the volume attached:

TypeScript

import { SandboxInstance } from "@blaxel/core";

const sandbox = await SandboxInstance.createIfNotExists({
  name: "my-sandbox",
  image: "blaxel/nextjs:latest",
  memory: 4096,
  region: "us-pdx-1",
  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.

Check volume attachment status

Each volume returned from the API includes a state.attachedTo field indicating which sandbox the volume is currently attached to.

When a sandbox is deleted, Blaxel automatically clears this field on the volume. You can therefore check state.attachedTo directly to determine whether a volume is free to attach to a new sandbox.

Learn more about volumes

Learn how to create and manage volumes.

Learn more about volume templates

Pre-populate volumes with files for faster environment setup.