Volumes and snapshots

A lease's disk lives exactly as long as the lease. Two objects carry work past that: a Volume, which is a disk of its own, and a Snapshot, which is a lease's disk and image captured at one moment.

#Volumes

A Volume is a persistent disk scoped to one environment, encrypted at rest, and created with the size you want:

sylphx sandboxes volumes create \
  --parent orgs/acme/projects/shop/envs/production \
  --spec.size-gib 1

curl -X POST "https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/volumes" \
  -H "Authorization: Bearer $SYLPHX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"spec":{"size_gib":1}}'

const response = await sylphx.sandboxes.volumes.create({
  parent: 'orgs/acme/projects/shop/envs/production',
  volume: { spec: { sizeGib: 1 } },
})

It is attached by name when the lease is created:

The lease becomes the volume's one writer, fenced by that lease's generation, so a mount is not a shared folder: a volume is attached to at most one lease at a time, and a create that names an already-attached volume is refused RESOURCE_IN_USE. That is the property to design around. Two machines writing one disk is the failure this prevents.

The volume outlives the lease. When the lease ends the volume is detached and the data stays, and the next lease that mounts it sees what the last one wrote. Nothing about the lease destroys it: a Volume is destroyed only by delete, and that call is refused RESOURCE_IN_USE while the volume is attached. update grows spec.size_gib and edits its metadata.

#Snapshots

A Snapshot captures a running lease's disk and image at one moment:

sylphx sandboxes snapshots create \
  --parent orgs/acme/projects/shop/envs/production \
  --spec.source-lease lease

curl -X POST "https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/snapshots" \
  -H "Authorization: Bearer $SYLPHX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"spec":{"source_lease":"lease"}}'

const response = await sylphx.sandboxes.snapshots.create({
  parent: 'orgs/acme/projects/shop/envs/production',
  snapshot: { spec: { sourceLease: 'lease' } },
})

A lease created with source_snapshot boots from it — its disk and its image — instead of from spec.image, which is ignored in that case. That makes the useful pattern a two-step one: set a machine up once, snapshot it at the moment it is ready, and start every lease after that from the snapshot rather than repeating the setup.

Process memory is not captured. A lease booted from a snapshot starts its processes fresh, exactly as a resumed lease does, so a snapshot is a starting point for work rather than a paused machine. Use pause for the latter — and read the lifecycle page when the difference between paused, snapshotted and ended matters.

#Pools

A Pool keeps never-leased machines of one shape and image warm, so a lease starts in seconds instead of waiting for a boot. spec.pool names one, and unset means the platform's own pool for that shape and image.

The property worth knowing: a pool changes how fast a lease arrives, never what you get. A lease served from a warm machine is the same shape, the same image and the same isolation as one that took longer, so nothing you write has to depend on the pool in order to be correct. The pools collection carries the spec, including the bounds on warm machines, and the operations.