Volumes

Volumes are named, persistent directory trees that survive independently of any sandbox and can be attached to sandboxes at create time. A volume is ready immediately on create — there is no provisioning wait. See the Volumes guide.

POST /volumes

Create a volume. Names are unique per project among non-deleted volumes.

Request

curl -X POST https://api.rl.trydaytona.com/volumes \
  -H "Authorization: Bearer $RLP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "training-data", "size_gb": 250 }'

{
  "id": "c2e91b47-5a03-4d68-9f21-7b4e8c0d3a56",
  "name": "training-data",
  "type": "blockmount",
  "size_gb": 250,
  "state": "ready",
  "created_at": "2026-07-31T10:15:00Z",
  "updated_at": "2026-07-31T10:15:00Z"
}

Errors

• 400 — invalid name, unsupported type, or size_gb out of range.
• 409 — a volume with this name already exists.

GET /volumes

List the project's volumes, newest first.

curl https://api.rl.trydaytona.com/volumes \
  -H "Authorization: Bearer $RLP_API_KEY"

{
  "volumes": [
    {
      "id": "c2e91b47-5a03-4d68-9f21-7b4e8c0d3a56",
      "name": "training-data",
      "type": "blockmount",
      "size_gb": 250,
      "state": "ready",
      "created_at": "2026-07-31T10:15:00Z",
      "updated_at": "2026-07-31T10:15:00Z",
      "last_used_at": "2026-07-31T18:02:11Z",
      "used_bytes": 5368709120,
      "used_bytes_at": "2026-07-31T18:05:00Z"
    }
  ]
}

used_bytes is the logical committed usage and is absent until the volume has been written at least once. Optional fields (error_reason, last_used_at, used_bytes, used_bytes_at) are omitted when unset.

GET /volumes/:id_or_name

Fetch one volume by UUID or name. The detail view also includes, when available, last_manifest_id (the latest committed version pointer) and conflicts (an audit trail of concurrent-write conflicts).

curl https://api.rl.trydaytona.com/volumes/training-data \
  -H "Authorization: Bearer $RLP_API_KEY"

Errors

• 400 — the ref matches one volume's id and a different volume's name (ambiguous).
• 404 — no matching volume.

DELETE /volumes/:id_or_name

Retire a volume. Deletion is refused while any live sandbox has it attached. The volume's name is immediately reusable (the retired row is renamed <name>-deleted).

curl -X DELETE https://api.rl.trydaytona.com/volumes/training-data \
  -H "Authorization: Bearer $RLP_API_KEY"

{ "id": "c2e91b47-5a03-4d68-9f21-7b4e8c0d3a56", "state": "deleted" }

Errors

• 404 — no matching volume (or already deleted).
• 409 — the volume is attached to a sandbox; delete or stop it first.

Attaching

Attach volumes at sandbox creation via the volumes array on POST /vms:

{
  "image": "node:20",
  "volumes": [
    { "volume": "training-data", "mount_path": "/data", "subpath": "run-42" }
  ]
}

Rules (validated at create, 400/409 on violation):

• volume is a volume id or name; it must be ready.
• mount_path must be absolute, contain no .., not duplicate another mount, and not be one of the reserved paths (/, /proc, /sys, /dev, /overlay, /mnt/scratch).
• subpath (optional) mounts a subdirectory of the volume.
• At most 8 volumes per sandbox.

A sandbox with volumes always cold-boots, and volumes block pause and fork. See Using Volumes for sharing and consistency semantics.