# Attach persistent storage

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 `write` to create, resize or detach; `read` to inspect; and `admin` to 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`](/reference/mcp-tools/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`](/reference/mcp-tools/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](/ship/deployment/databases) before operating an engine yourself on a volume.

## Grow the volume

Call [`deployment_volume_resize`](/reference/mcp-tools/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`](/reference/mcp-tools/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`](/reference/mcp-tools/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.