Attach persistent storage
Create and mount a volume, then manage its size and lifecycle.
Attach a volume when files must survive container restarts, deployments and rollbacks. Bind it to the service when you create it. A detached volume cannot later be attached to a service.
Before you start
- Have a runtime service in the same environment as the new volume.
- Choose an absolute mount path, such as
/var/lib/data, that your application will write to. - Plan for an interruption on each deployment, restart and rollback: the old container must release the disk before the new one starts.
- For MCP, use a product-scoped token with Deployment
writeto create, resize or detach;readto inspect; andadminto delete.
Creating and resizing volumes are tool-only operations; the Product App has no creation or resize screen.
1. Create the volume
Call deployment_volume_create with:
Input | Value to supply |
|---|---|
environmentId | The service’s environment ID |
name | A name up to 80 characters |
sizeGb | An integer from 1 to 1024, in GB |
mountPath | The absolute path inside the container |
attachedServiceId | The service that should mount the volume |
The slug is derived from the name unless you supply one. Although attachedServiceId is optional in the schema, omitting it creates an unattached volume. There is no later attach action; create a new volume bound to the service instead.
2. Wait and deploy
Read the volume with deployment_volume_get. It moves from provisioning to ready; a failure is recorded as failed with its reason. An unattached volume shows detached.
Redeploy the service to apply the mount. A volume belongs to one service at a time; a service can have several volumes at different paths. The canvas shows a volume node and the attached service’s mount path and size.
Verify it works
Have the application write a small test file under the mount path. Redeploy the service, allowing for the interruption, then read the file again. A file written outside the mount belongs to the temporary container filesystem and will not survive replacement.
For database storage, consider a managed database before operating an engine yourself on a volume.
Grow the volume
Call deployment_volume_resize with its ID and a larger sizeGb, up to 1024 GB. Shrinking is refused. Growth does not rewrite or move the data. Inspect the volume again to confirm the new size.
Detach or delete
Detach volume on the volume panel, or deployment_volume_detach, preserves its contents but separates it from the service. The service loses the mount on its next deployment. Detachment is one-way: do it only when you are finished with the attachment.
Delete volume, or deployment_volume_delete, permanently destroys the disk and its contents without taking a backup. Deletion is refused while attached, so detach first. The UI confirmation asks for the volume slug. Copy any data you need before deletion.
Deleting the service does not delete its volumes. Inspect remaining resources separately after removing a service.