Recover research files and environments

Recover one research file without rewinding the rest of a project, then learn when an environment or project restore is the appropriate operation. The exercise uses disposable data; do it before you need to recover important work.

Choose the smallest recovery operation

A clone is a copy of the current state, not a selection of an older checkpoint. Snapshots are host-local checkpoints. Backups are host-independent archives that can include project files, rootfs state, and TimeTravel history; their file-search interface searches HOME. Availability, retention, and the newest recoverable time depend on the project's runtime and configured schedules.

Prepare a disposable example

Use an editable project with Python 3 and enabled snapshots. Open its full CoCalc interface; from Essential, use File actions -> Full CoCalc on a file or More -> Settings -> Full project settings. If you do not have a suitable project, follow Create a project. Do not run a whole-project restore exercise in a project containing other people's work.

Open a project terminal and run this once. It deliberately refuses to reuse an existing example directory.

cd "$HOME"
python3 - <<'PY'
from pathlib import Path

folder = Path("recovery-demo")
folder.mkdir()
(folder / "measurements.csv").write_text("value\n2\n4\n6\n8\n")
print("Created recovery-demo/measurements.csv")
PY

If the directory already exists, choose a different name and substitute it throughout the exercise. In Files, open recovery-demo/measurements.csv and check that it contains the heading value followed by 2, 4, 6, and 8.

1. Open Settings -> Recovery -> Create Snapshot.
2. Enter a unique name such as recovery-demo-before-edit and choose Create Snapshot.
3. In Files -> Recovery -> Open Snapshots, open that snapshot and verify that its recovery-demo/measurements.csv has those original values. Do not change or delete the live file until this check succeeds.
4. Return to the live recovery-demo/measurements.csv in Files. Change its final value from 8 to 80, save it, and confirm the change after reopening the live file.

Named snapshots retain data and count against the project's quota. A Manual snapshot limit reached message means that you must resolve the limit before claiming a checkpoint exists.

Recover a file without overwriting current work

1. Use Files -> Recovery -> Open Snapshots again. Open the named checkpoint and select recovery-demo/measurements.csv.
2. In Snapshot selection, check Selected path and Preview. The preview should contain 8, not 80.
3. Choose Restore to /tmp/<path>. For this example the destination is /tmp/recovery-demo/measurements.csv. If you have used that temporary path before, preserve or remove your earlier comparison copy first.
4. After Restore completed, run the comparison below in a terminal.

cd "$HOME"
python3 - <<'PY'
import csv
from pathlib import Path

def mean(path):
    with path.open(newline="") as stream:
        values = [float(row["value"]) for row in csv.DictReader(stream)]
    return sum(values) / len(values)

live = Path("recovery-demo/measurements.csv")
recovered = Path("/tmp/recovery-demo/measurements.csv")
print(f"live mean={mean(live):.1f}")
print(f"recovered mean={mean(recovered):.1f}")
assert mean(live) == 23.0
assert mean(recovered) == 5.0
PY

Expected output:

live mean=23.0
recovered mean=5.0

Copy the checked version into HOME under a new name so it is retained with the research files. This command refuses to overwrite an existing result:

cd "$HOME"
python3 - <<'PY'
from pathlib import Path

source = Path("/tmp/recovery-demo/measurements.csv")
target = Path("recovery-demo/measurements-recovered.csv")
with target.open("xb") as stream:
    stream.write(source.read_bytes())
print("Saved recovery-demo/measurements-recovered.csv")
PY

Open the saved file in Files, then reload it and verify the four original values. Keeping the changed file and the recovered copy makes the decision reviewable. If the original file is missing, this same workflow recovers a separate copy without first recreating the original path.

For older data in a backup, use Recovery -> Open Backups, choose the backup and file, and inspect Backup selection. The temporary-copy option is the same, but Restore started means the operation is still asynchronous. Wait for its completion and inspect the restored file before using it.

Restore an earlier editor revision

For an edit retained in TimeTravel, open the live file, choose TimeTravel, and inspect the desired version. Use Restore This Version only after checking the displayed contents. Reopen the live editor, save if necessary, and verify its contents after a reload. Keep a separate copy of useful current work before restoring over it. An empty history is not evidence that a snapshot or backup also lacks the file; inspect those sources separately.

Restore an environment or an entire HOME

Use this procedure when a file copy is insufficient. First record the failing command, its error, the desired checkpoint, and the software location. For a Python environment, python3 -c 'import sys; print(sys.executable)' helps distinguish a HOME virtual environment from system software.

1. Save current work and coordinate with project collaborators. Whole-project snapshot restoration stops and restarts the project; running processes do not continue from their previous memory state.
2. Open Settings -> Recovery -> Restore Snapshot.
3. Under Snapshot to restore, choose the checkpoint you inspected.
4. Under Restore mode, explicitly choose the HOME, rootfs, or combined option from the table above. The dialog initially selects both.
5. Record Safety snapshot name outside the project before proceeding. Keep its unique suggested value or provide another unique name. The workflow creates this snapshot of the current state before restoring.
6. Choose Restore Snapshot and complete any sign-in verification the interface requests. Wait for the restore operation to finish and the project to be available again.
7. Reopen the research files, restart the notebook kernel, rerun the original failing command, and record the new result. A completed restore alone does not prove the scientific result or environment is correct.

Project secrets are managed separately from filesystem snapshots and backups; do not expect this operation to rewind secret values. See Project secrets. A rootfs restore preserves HOME, including a broken HOME-based virtual environment. For that case, rebuild the environment from its recorded dependencies or choose a suitable HOME restore after preserving newer research work.

Troubleshooting and cleanup

• Missing recovery controls can indicate that the runtime does not support snapshots or backups. Check Settings -> Recovery and the project's placement before assuming a recovery point exists.
• No matching history may mean the file was created after the selected checkpoint, retained history expired, or the project moved hosts. Check backup dates and the exact path; host-local snapshots do not follow a move.
• Storage usage includes retained history as well as live files. Deleting a live file may not immediately reduce usage retained by snapshots. Inspect storage and recovery points before cleanup; deleting a snapshot removes that recovery option. If quota prevents cleanup, preserve the error and ask support for the appropriate recovery path rather than running internal quota commands.
• A full restore can rewind chatrooms and Codex conversations stored in the restored filesystem. Keep the incident note and checkpoint identifiers outside that filesystem while restoring it.
• Copy useful recovered data out of /tmp; it is a temporary inspection location. Retain the named checkpoint until you have verified recovery, then remove only the disposable files and checkpoints you deliberately created.

For a real incident, leave the recovered file, checkpoint date, comparison, and next action in a handoff note. Follow Start and hand off a research task to give a colleague the correct access and links.