Persistent Storage

What a volume is

A volume is a persistent per-egg disk mounted at /data. Unlike the default filesystem (/app is reset on every deploy and /tmp is wiped on sleep), anything your egg writes under /data survives sleep, wake, and redeploys.

It's a good fit for SQLite databases, file uploads, generated caches, or any single-host file-based state. Volumes are off by default — enable one per egg when you need it.

Enable a volume

Provision a volume for your egg. It takes effect on your next deploy:

hatch volume enable [slug] --size 1024

The egg slug is auto-detected from .hatch.toml in the current directory, or pass --app / -a.

Check status

Show the volume's size, usage and mount point:

hatch volume status [slug]

Reports size, used MB, the /data mount point, and the current status (active or grace_deleting).

Disable a volume

Detach the volume. Its data is kept for a 7-day grace period — re-enable within that window to keep it:

# Detach now, data deleted after the 7-day grace period
hatch volume disable [slug]

# Delete immediately and irreversibly (skips the grace period)
hatch volume disable [slug] --now

An append-only erasure record (GDPR Art. 17 evidence) is written before the data is removed.

Size limits

The maximum volume size depends on your egg's tier:

If a volume's usage exceeds its size cap, new deploys are blocked with a 422 (“volume over quota”) until you clean up /data or increase the size.