Persistent volumes

A persistent volume is a durable disk attached to a web service. Everything the service writes under the volume's mount path survives restarts, redeploys, and detaches.

Databases never use these volumes — a Postgres or Redis database's disk is included automatically, sized from its memory.

A service with a volume runs in volume mode, one of the web service modes: it is pinned to one location with exactly one replica, and a volume never combines with serverless or cron mode — the console blocks those toggles while a volume is attached, so detach first to switch. Each volume gets a friendly two-word name of its own, because the disk's identity is independent of whichever service it is attached to.

Attach a volume

1. Click the service's node on the environment canvas and go to its Settings tab.
2. Under Persistent volume, click Attach volume.
3. Choose Create a new volume — or Attach an existing detached volume and pick one from the list.
4. Set the Mount path — where the disk is mounted in the container, /data by default.
5. Press Deploy on the changes bar (Shift+Enter).

Attaching is a staged change: the disk is created and attached when you deploy, not before. A new volume starts at Koo's base size — grow it any time with an expand (below); through the API, the service's volume field also accepts an initial sizeGb.

Re-attaching an existing detached volume keeps its data and its location. The disk never moves: the service must run in the disk's location to see its data. Picking a disk that lives in a different location mounts a new, empty disk instead — the console warns you when you pick it, and the deploy asks you to acknowledge starting empty before it goes through (confirmDataLoss on the API).

Detach a volume

1. In the service's Settings, under Persistent volume, click Detach on the volume card.
2. Press Deploy on the changes bar.

Detaching never deletes data. The disk survives as a detached volume — still listed in the environment, keeping its data and location — and can be re-attached later, to the same service or a different one.

Deleting the service works the same way: its volume is detached and kept, never destroyed.

Day-2 operations

A volume's drawer has Overview and Snapshots tabs. Open it by clicking the volume on the environment canvas (a detached volume shows as its own node), or from the volume card in the service's Settings. The environment's Volumes page — open Volumes from the rail on the left of the canvas — reaches the same operations through Manage.

Expand

On the Overview tab, enter a new size and click Expand. Volumes only grow — you cannot shrink one. The disk expands in place — no redeploy needed.

Take a snapshot

On the Snapshots tab, optionally name the snapshot and click Take snapshot. A snapshot is a manual point-in-time copy of the disk; leave the name blank and a timestamped one is generated.

Snapshots exist only for these web-service volumes — databases have no snapshots.

Restore from a snapshot

Click Restore next to a snapshot and confirm. Restoring is destructive: it overwrites the volume's current data with the snapshot's, in place — same disk, same attachment — and the console asks you to confirm the data loss before it runs.

Delete a snapshot

Click Delete next to a snapshot and confirm. This removes only the copy — the volume's live data is untouched.

The environment's volumes list

The environment's Volumes page lists every volume — attached and detached — with its name, what it is attached to, its size, and its live state. Manage opens any volume's operations; Delete appears only on detached ones.

Delete a volume

Only a detached volume can be deleted — detach it from its service first; the API rejects a delete while the volume is attached. There are two ways:

1. On the Volumes page, click Delete and type the volume's name to confirm — the disk is destroyed immediately.
2. From the detached volume's drawer on the canvas, the Danger tab stages the deletion — the disk is destroyed when you press Deploy, after confirming the data loss.