Persistent volumes

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

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 — unlike the rest of the service's filesystem, which resets on every deploy.

Attach a volume#

  1. 1

    Open Settings

    On the service page, go to the Settings tab and find Volumes.

  2. 2

    New volume

    Click “New volume”, enter an absolute mount path (e.g. /data) and an optional name, then save.

  3. 3

    Redeploy to apply

    The mount takes effect on the next deploy — hit “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://gheima.ma/api/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; DELETE the same path with /volumes/{volumeId} to detach.

Detach a volume#

Detaching removes the mount on the next deploy. The underlying disk is retained, not deleted, so a stray detach doesn't destroy data.

Volumes are node-local: the platform pins a service with volumes to the node it's scheduled on, so its disks follow it across deploys. They aren't shared across services and aren't backed up automatically — copy anything important to object storage if you need durability beyond the node.

Limits & rules#

  • One volume per mount path per service — attaching a second volume at the same path is rejected.
  • The mount path must be absolute, normalized (no “.” or “..” segments), and can't target a reserved system directory (/etc, /bin, /usr, and similar).
  • 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.