> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bead.run/llms.txt
> Use this file to discover all available pages before exploring further.

# Sandbox persistent volumes

> Attach sandbox persistent volumes, inspect readiness, extend retention, and detach or delete them when finished.

Attach sandbox persistent volumes to keep a separate ext4 volume across temporary machine lifetimes. A volume has its own retention deadline and one writer at a time.

## Create and wait

Save this as `volume.json`:

```json theme={null}
{"name":"dataset","size_gib":1,"retention_seconds":86400}
```

```bash theme={null}
bead api POST /volumes --input volume.json
bead api GET /volumes
```

Creation returns 202 and a volume ID. Poll the list until `state` is `ready`. A `blocked` state includes an actionable error; provisioning can recover after capacity is released. Delete and recreate if you need to request a smaller volume.

An organization can have up to 32 volumes, each 1–128 GiB. Volumes have one writer and at most one mount per machine. Trial accounts cannot use persistent volumes.

## Attach at machine creation

Save this as `create-volume-machine.json`:

```json theme={null}
{
  "templateID":"base",
  "size":"small",
  "kind":"temporary",
  "timeout":300,
  "volumeMounts":[{"name":"dataset","path":"/data"}]
}
```

```bash theme={null}
bead api POST /v2/sandboxes --input create-volume-machine.json
```

Mount at `/data` or below `/mnt/`, without traversal or symlink targets. Persistent machine creation with `volumeMounts` is rejected. Volume placement is local to its supported placement; volumes do not provide cross-host replication or shared read-only mounts.

## Extend retention

Retention accepts 60–86400 seconds. Save `{"retention_seconds":86400}` as `extend-volume.json`:

```bash theme={null}
bead api POST /volumes/VOLUME_UUID/extend --input extend-volume.json
bead api GET /volumes
```

Read the requested and worker-confirmed deadlines. Machine leases cannot exceed confirmed retention. Extend before expiry; adding credit alone does not extend the deadline. Storage funding covers the retention window even while detached.

## Detach and delete

Close files and mappings on the volume before detaching from a running machine:

```bash theme={null}
bead api POST /sandboxes/ID/volume/detach
bead api DELETE /volumes/VOLUME_UUID
```

A busy filesystem returns 409. Deletion refuses attached volumes and returns 202 when accepted. Poll the list until the volume disappears. Machine deletion also releases attachment after lifecycle cleanup; the volume remains until its own deletion or expiry.

## Snapshots and contents

Saved snapshots and forks reject sources with an attached persistent volume. Close files and mappings, then detach the volume before capture; volume contents are not copied into a saved snapshot.

Export required data before the retention deadline. Subscribe to `volume.expiring` through [webhooks](https://docs.bead.run/platform/webhooks.md).


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