Project host storage, backups, and snapshots

What the Storage tab is for

The host Storage tab is where you inspect provider disk capacity, storage mode, usage, reservations, and host-level storage actions. It is the right place to check before growing a disk, moving projects onto a host, draining a host, or changing infrastructure that could affect local project data.

Project host storage is not the same thing as a project backup. The host disk is where running project files live. Project backups are the portable recovery copy that CoCalc can use when moving or restoring projects.

Persistent and ephemeral storage

Persistent storage is designed to survive ordinary host restarts and provider machine replacement according to the provider's disk model. Ephemeral or local storage is faster or cheaper for some workloads, but it should be treated as recoverable only through project backups and explicit project data copies.

Before placing important projects on a host, check whether the host uses persistent storage, ephemeral storage, or provider-specific attached disks. Do not assume that files outside the project backup path, such as temporary files, will survive deprovision, move, or provider replacement.

Shared scratch disks are a separate host-scoped storage feature. They are mounted at /scratch in projects on the host, shared by those projects, and not included in project backups or project moves. Use the Shared scratch disks docs before enabling scratch for a host with multiple users or projects.

Growing disk

For provisioned GCP and Nebius hosts using persistent storage, disk enlarge supports online growth. Ephemeral storage cannot be resized this way. Growing disk is one-way: plan for future use, but do not treat it as a reversible experiment.

After growing disk, verify both the provider disk size and usable filesystem capacity in the Storage tab. If the provider resize succeeds but filesystem growth reports a warning, follow its recovery instructions and verify the capacity again. Also check the host status. If usage remains high, check whether projects are producing temporary files, caches, datasets, or build artifacts that should be moved or deleted instead of simply growing the disk again.

Backups and snapshots

Use project backups for portable project recovery, cross-host moves, and protection before lifecycle actions. For how snapshots and backups are made, their default schedule and what they guarantee, see How snapshots and backups work.

Snapshots in ~/.snapshots are host-local copies of the project's files. They do not include the edit history (TimeTravel), which CoCalc stores separately. To recover from a snapshot, copy the files you need to another path and compare them with current work before replacing anything. Restoring the whole HOME from a snapshot, alone or together with the root filesystem, is temporarily unavailable on hosts that store edit history separately: the restore is refused before the project is stopped. Restoring the root filesystem only still works.

To bring back many HOME files, restore them from a completed backup. A backup restore writes the backed-up files over the current ones and keeps files that are not in the backup, so HOME does not return exactly to its earlier state. Recover research files and environments helps choose the smallest recovery operation.

Provider disk snapshots are separate infrastructure recovery tools. Use them only when the UI or provider explicitly exposes that workflow for the host; they do not replace project backups.

Project backups can skip files whose apparent size exceeds the backup file-size limit, which normally follows the project's disk quota. Sparse or compressed files can exceed this limit while occupying less disk space. Review any skipped-file report before relying on a backup. Those files are also absent from an archive, move, or cross-host copy that restores from that backup. Preserve them separately before confirming an operation that skips them.

Before deprovisioning, deleting, moving, or changing storage mode, make sure important projects have current backups. If a project has changed region, verify that a backup exists in the destination backup region after the move completes.

Agent notes

When diagnosing storage or advising a lifecycle action:

1. Open the host Storage tab for the selected host.
2. Check storage mode, provider, disk size, current usage, and whether online grow is supported.
3. Distinguish host disk state from project backup state.
4. Before deprovision, delete, region move, or storage-mode change, verify project backup freshness and assigned projects.
5. Warn explicitly that /tmp, caches, host-local snapshots, and files outside the project backup model may not follow a project move.