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

# Volumes

> Persistent named storage you can attach to sandboxes

A volume is named storage that outlives any sandbox. Create it once, attach it to sandboxes at a mount path, write to it, and publish to share the result with future sandboxes.

> [!NOTE]
>
> Sandbox volumes (`prime sandbox volumes`) are separate from [Hosted Training volumes](/hosted-training/volumes), which back Model Factory training runs.

## How a volume works

* A sandbox that attaches a volume gets a **private copy** of it, taken from the volume's latest checkpoint when the sandbox is created. Its writes are invisible to every other sandbox, and a running sandbox never picks up later publishes.
* Volumes attach **read-write** (the default) or **read-only** (`:ro`). A read-only attachment cannot write or publish.
* **Publishing** turns one sandbox's private writes into a new volume checkpoint. Only sandboxes created after the publish completes see the new data. A volume that was never published is empty.
* Volumes use [checkpoints](/sandboxes/checkpoints) under the hood: each publish saves the volume's contents as a checkpoint.
* Published data survives sandbox termination; unpublished writes do not. **Publish before deleting a sandbox** whose writes you want to keep.
* A volume is a separate disk: it doesn't count against the sandbox's `disk_size_gb`, and a sandbox checkpoint captures the root filesystem only, never a mounted volume. Each volume holds up to **100 GiB**.

## Quickstart

```bash CLI theme={null}
# Create an empty volume
prime sandbox volumes create my-data

# Attach it to a new sandbox at /data and write to it
prime sandbox create python:3.11-slim --volume my-data:/data
prime sandbox run <sandbox-id> "bash -c 'echo hello > /data/hello.txt'"

# Publish: the sandbox's private writes become a new volume checkpoint
prime sandbox volumes publish my-data --sandbox <sandbox-id>

# A new sandbox sees the published data; :ro mounts it read-only
prime sandbox create python:3.11-slim --volume my-data:/data:ro
prime sandbox run <sandbox-id-2> "cat /data/hello.txt"
```

```python Python theme={null}
from prime_sandboxes import (
    APIClient,
    CreateSandboxRequest,
    SandboxClient,
    VolumeMount,
)

client = SandboxClient(APIClient())

client.volumes.create("my-data")

writer = client.create(
    CreateSandboxRequest(
        name="writer",
        docker_image="python:3.11-slim",
        volumes=[VolumeMount(name="my-data", mount_path="/data")],
    )
)
client.wait_for_creation(writer.id)
client.execute_command(writer.id, "bash -c 'echo hello > /data/hello.txt'")

# Publishes and waits until the new checkpoint is durable
client.volumes.publish(writer.id, "my-data")

reader = client.create(
    CreateSandboxRequest(
        name="reader",
        docker_image="python:3.11-slim",
        volumes=[VolumeMount(name="my-data", mount_path="/data", read_only=True)],
    )
)
client.wait_for_creation(reader.id)
print(client.execute_command(reader.id, "cat /data/hello.txt").stdout)
```

Pass `--volume NAME:/mount/path[:ro]` up to 8 times per sandbox. `:ro` mounts the volume read-only; writable mounts have no suffix.

## Import a local directory

```bash theme={null}
prime sandbox volumes create my-data --from ./dataset
```

`--from` needs `rsync` on your machine. The CLI copies the directory through a short-lived helper sandbox and publishes it as the volume's first checkpoint; the helper is deleted once the publish is confirmed durable. If the volume already exists, the directory is copied into its current published contents.

## Publish rules

* `publish` waits until the new checkpoint is `DURABLE` by default. With `--no-wait` (CLI) or `wait=False` (SDK) it returns immediately — poll `prime sandbox checkpoint get <checkpoint-id>` or `client.get_checkpoint(...)` until `DURABLE`. A publish that times out can still finish.
* If a sandbox tries to publish after the volume's checkpoint has advanced past the one it attached, publishing fails with 409. A sandbox can still publish again on top of its own earlier publishes. To recover, re-attach in a fresh sandbox, or publish with `--force` to make this sandbox's entire copy the volume's new checkpoint. `--force` replaces the published contents; it does not merge files.
* Read-only attachments cannot publish.
* If a publish fails, the volume keeps its previous checkpoint, and the sandbox keeps its private writes.

## Manage volumes

```bash CLI theme={null}
prime sandbox volumes list --num 50
prime sandbox volumes get my-data
prime sandbox volumes delete my-data
```

```python Python theme={null}
page = client.volumes.list(page=1, per_page=50)
print(page.volumes, page.has_next)

volume = client.volumes.get("my-data")
print(volume.head_checkpoint_id)  # None until the first publish is durable

client.volumes.delete("my-data")
```

* `list` paginates with `--page` / `--num` (max 100 per page); `--json` prints raw fields.
* `delete` fails with 409 while any active sandbox has the volume attached, and removes the volume and all of its published data. Deleting a team volume requires a team admin.

### Scopes and permissions

* Volumes are personal by default. Pass `--team-id` (CLI) or `team_id` (SDK) to work in a team; without it, the CLI uses the team from your config, if any.
* Team members can create, attach, and publish team volumes; only team admins can delete them.
* API tokens need the `sandbox:read` scope to list or get volumes and `sandbox:write` to create, delete, or publish.

### Names and mount paths

* Volume names: 1–40 characters, lowercase letters, digits, and hyphens; must start and end with a letter or digit; unique within their scope.
* Mount paths: absolute, not `/`, unique per sandbox, and not nested inside each other.

## Common errors

| Error | Cause | Fix |
| - | - | - |
| 404 `Volume not found` | No volume with that name in your scope | Check `prime sandbox volumes list` and your team scope |
| 409 `A volume with this name already exists in this scope` | Name taken on create | Pick another name or use the existing volume |
| 409 `Volume is mounted by one or more sandboxes` | Delete while attached | Delete or stop the attached sandboxes first |
| 400 `Read-only attachments cannot publish` | Publishing a `:ro` mount | Attach writable, then publish |
| 404 `Volume is not attached to this sandbox` | Publishing a name this sandbox doesn't have | Check the sandbox's `--volume` mounts |
| 409 `Another sandbox is publishing this volume` | Concurrent publish | Wait for the other publish to finish |
| 409 on publish, volume checkpoint advanced | The volume's checkpoint advanced after this sandbox attached | Publish with `--force` to replace the volume's contents, or re-attach in a fresh sandbox |

Published volume data is billed as [checkpoint storage](/sandboxes/overview#pricing).


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