Persistent volumes

Attach a durable disk to a service so data written to a mount path survives restarts and redeploys.

View as MarkdownOpen in ClaudeOpen in ChatGPT

A persistent volume is a durable disk attached to a service at a mount path. Files your app writes there survive restarts, redeploys, and rescheduling. The rest of the service's filesystem resets on every deploy.

Attach a volume#

  1. 1

    Open Settings

    On the service page, open the Settings tab and find Persistent volumes.

  2. 2

    Add volume

    Click "Add volume", enter an absolute mount path (for example /data) and an optional name, then save.

  3. 3

    Redeploy to apply

    The mount takes effect on the next deploy. Click "Deploy" when you’re ready.

Via CLI#

Shell
gheima volumes add my-app /data --name uploads
gheima volumes list my-app
Attach and list volumes for a service (by id, name, or slug).

Via API#

Shell
curl -X POST https://api.gheima.ma/v1/services/{id}/volumes \
  -H "Authorization: Bearer $GHEIMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"uploads","mountPath":"/data"}'
Returns the new volume's id. To detach the volume, send DELETE to the same URL with /{volumeId} appended.

Detach a volume#

Detaching removes the mount on the next deploy. A detached volume cannot be reattached, and its data is permanently deleted 7 days after you detach it. If the service has not been redeployed by then, deletion waits until it has. Copy anything you want to keep before detaching.

Volumes are node-local. The platform pins a service that has volumes to the node it is scheduled on, so its disks follow it across deploys. Volumes are not shared between services and are not backed up automatically. If you need durability beyond one node, copy anything important to object storage.

Limits & rules#

  • A service can have one volume per mount path. Attaching a second volume at the same path is rejected.
  • The mount path must be absolute and normalized, with no empty, ".", or ".." segments. Each segment may use only letters, digits, ".", "_", and "-". The path can't be / or sit under /bin, /boot, /dev, /etc, /lib, /proc, /root, /sbin, /sys, or /usr.
  • Mount paths are capped at 512 characters.
  • The maximum number of volumes across your account is set by your plan.

✦ Your service has durable, per-node storage for uploads, caches, or any data that must outlive a deploy.