Shared scratch disks on project hosts

What shared scratch is

A shared scratch disk is host-scoped working storage mounted at /scratch inside projects on a project host. It is useful for large shared datasets, model checkpoints, build caches, generated artifacts, and temporary working files that should not live in normal project quota.

The word shared is the important part: every project on that host sees the same /scratch filesystem. Do not put secrets, private student work, or user-specific data there unless every project and user on the host should be able to read and write it.

What it is not

Shared scratch is not project storage. It does not count toward project quota, does not move with a project, and is not copied by project backup, project copy, or project move. If a project moves to another host, the files in /scratch stay with the original host.

Shared scratch is also not a CoCalc backup. It uses provider network block storage rather than local SSD, and the provider disk type may have its own durability properties, but CoCalc does not back up scratch contents.

Copy finished results into the project

Agree on a shared input directory and give each project/run its own output directory, for example /scratch/study-data/ and /scratch/study-runs/<project-id>/<run-id>/. These names reduce accidental overwrites; they do not create a permission boundary between projects. Keep shared inputs unchanged while other jobs read them.

Before moving a project or removing scratch, copy the required finished outputs into that project's HOME or another retained destination. A symbolic link in HOME that points into /scratch is not a copy of the target data.

For a single completed result, run this in a Linux project terminal after replacing the source path. It requires the source file to exist and refuses to reuse the destination directory:

(
  set -e
  src=/scratch/study-runs/my-project/run-001/results.csv
  dst="$HOME/scratch-result-check"
  test -f "$src"
  mkdir "$dst"
  cp -- "$src" "$dst/results.csv"
  cmp -- "$src" "$dst/results.csv"
)

A zero exit status and no output from cmp mean the two files have identical bytes at comparison time. If copying or comparison fails, any destination files remain for inspection; keep the source until verification succeeds. Confirm the copied file opens in the project and record the input, code and environment needed to reproduce it. This copy checks one file; it does not create or verify a project backup. Check your configured retention and backup result separately.

Lifecycle rules

CoCalc preserves scratch across normal host stop/start, reboot, and supported machine replacements such as spot-to-standard fallback. Explicit host deprovisioning, host deletion, or scratch-disk deletion destroys scratch data. Before these destructive actions, copy important scratch files to separately retained storage. Project backups do not include them.

Adding scratch or deleting scratch can be requested while the host is running. Projects may need to be restarted before they see a newly added /scratch mount. Deletion can fail if running projects are still using the filesystem, because the host must unmount it before destroying the disk.

Growing and changing scratch

For GCP hosts, scratch disk growth is online. It does not require a host reboot, and projects can keep running while the disk and filesystem are enlarged.

GCP scratch disks can also be configured for automatic grow. When automatic grow is enabled, CoCalc watches host-level /scratch usage, grows by the configured increment when free space crosses the threshold, caps growth at the configured maximum, and still runs billing/admission checks before increasing pay-as-you-go storage.

For Nebius hosts, creating the initial scratch disk can be done without a host reboot. When growing an existing disk, CoCalc attempts to make the larger filesystem available online. Check the usable capacity after the operation. If filesystem growth does not complete, follow the warning to retry reconcile or restart the host if the provider has not exposed the new block size yet.

Scratch growth is one-way: you can grow the disk, but you cannot shrink it in place. To shrink or change disk type, delete the scratch disk and recreate it at the desired size and type, which destroys all scratch data.

Nebius scratch disks are sized in 93 GB increments. If you request a smaller or non-aligned size, the UI rounds up to the provider-supported size.

Billing and planning

Scratch is host pay-as-you-go storage. It can continue to cost money while the host is stopped, because the provider disk still exists. Use it deliberately for data that benefits from being shared on one host, and clean it up when the workload is finished.

For course or workshop hosts, explain the sharing model to users before enabling scratch. A public or shared-pool host with scratch can make the same filesystem visible to unrelated projects if placement is broad enough.

Agent notes

When helping with shared scratch:

1. Ask for or select the project host id; scratch is attached to a host, not to a project.
2. Open the selected host's Storage tab with the hosts.scratch.open docs action.
3. Confirm the host-owning bay before making control-plane changes.
4. Warn that /scratch does not follow project backup, copy, restore, or host-to-host move workflows.
5. Treat scratch deletion as destructive for every project using that host.
6. If the user is moving a project to another host, ask whether any needed data is only in /scratch and should be copied into project files or another durable location first.