Volumes

​

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

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

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)

​

Import a local directory

prime sandbox volumes create my-data --from ./dataset

​

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

prime sandbox volumes list --num 50
prime sandbox volumes get my-data
prime sandbox volumes delete my-data

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